Quickstart

Two endpoints do most of the work. search returns rows from the index. ask puts an agent in front of the same index and streams back an answer with its sources. Everything else is detail.

Get a key

Create one in your account. It is shown once, so put it somewhere your process can read it before you close the tab.

export BIGHUGGER_KEY=bh_live_...

Search the index

curl -G https://api.bighugger.com/v1/search \
  -H "authorization: Bearer $BIGHUGGER_KEY" \
  --data-urlencode 'q=small multilingual embedding models' \
  --data-urlencode 'kind=model' \
  --data-urlencode 'limit=5'

{
  "object": "list",
  "query": "small multilingual embedding models",
  "reranked": true,
  "took_ms": 214,
  "count": 5,
  "data": [
    {
      "id": "...",
      "kind": "model",
      "title": "...",
      "url": "https://...",
      "snippet": "...",
      "score": 0.71,
      "facts": {
        "kind": "model",
        "id": "...",
        "license": "apache-2.0",
        "params_total": 278043648,
        "context_length": 8192,
        "formats": { "safetensors": { "present": true } }
      }
    }
  ]
}

facts is the part that makes this different from a search box. Those fields were read out of the model's own configuration files rather than out of its description, so you can filter and sort on them instead of reading prose and guessing.

# Under 1B parameters, permissively licensed, available as safetensors.
curl -G https://api.bighugger.com/v1/search \
  -H "authorization: Bearer $BIGHUGGER_KEY" \
  --data-urlencode 'q=multilingual embeddings' \
  --data-urlencode 'max_params=1000000000' \
  --data-urlencode 'license=apache-2.0' \
  --data-urlencode 'format=safetensors'

Repeat a parameter to pass several values. Anything that does not fit comfortably in a URL can go to the same endpoint as a POST with a JSON body — same parameters, same results.

Ask a question

search gives you rows to rank yourself. ask gives you an answer, with the sources it used and the reasoning it did to get there.

curl -N -X POST https://api.bighugger.com/v1/ask \
  -H "authorization: Bearer $BIGHUGGER_KEY" \
  -H 'content-type: application/json' \
  -d '{"question":"Which open speech-to-text models run in under 4GB of VRAM?"}'

The response is newline-delimited JSON: one complete object per line, each with a type. Print the answer as it arrives and ignore the rest:

... | jq -rj 'select(.type=="text") | .delta'

The full set of event types is on the streaming page. Handle the ones you need and skip the rest — new types get added and skipping is what keeps your client working when they are.

Pick the right one

Reach for search when your code decides what to do with the results: building a shortlist, filtering a catalogue, populating a picker. It is a single round trip and it returns structure.

Reach for ask when the question needs several searches and a judgement to answer — comparisons, "which of these fits my constraint", anything where the useful output is a paragraph rather than a list. It costs more than a search because it does more than one.

Next

• Authentication — scopes, and one key per deployment
• Errors — the codes worth branching on
• Streaming — every event type, and a client that reads them