# 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.

```sh
export BIGHUGGER_KEY=bh_live_...
```

## Search the index

```sh
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'
```

```json
{
  "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.

```sh
# 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.

```sh
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:

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

The full set of event types is on the [streaming](/docs/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](/docs/authentication) — scopes, and one key per deployment
- [Errors](/docs/errors) — the codes worth branching on
- [Streaming](/docs/streaming) — every event type, and a client that reads them