# Search parameters

Every parameter `GET /v1/search` accepts, and what each one does to the result set.

The same names work either way. On a `GET` they are query parameters; on a `POST` they are keys in
a JSON body, either at the top level or nested under `filters`. Use whichever fits — a handful of
constraints reads better in a URL, a generated set reads better as JSON.

## The query

| Parameter | Type | Default | Notes |
| --- | --- | --- | --- |
| `q` | string | required | What you are looking for, in plain language. `query` is accepted as an alias. |
| `kind` | string, repeatable | all kinds | Restrict to one or more entity kinds. |
| `limit` | integer | 20 | Rows to return, up to 50. Asking for more returns the maximum rather than an error. |
| `rerank` | boolean | `true` | Set `false` to skip reranking and get the fused order instead. |

`kind` accepts `model`, `dataset`, `paper`, `repo`, `package`, `mcp_server`, `skill` and
`framework`. An unrecognised value is ignored rather than rejected, so a client that learns a new
kind before you do does not start failing.

**Reranking is on for a reason.** A short query — three or four words — puts almost no signal in
the embedding, and the fused order reflects that. Reranking reads the candidates against the actual
question and reorders them, which is most of the difference between a plausible list and a useful
one. Turn it off when you are going to rank the rows yourself and want the latency back.

## Filters

Filters narrow the candidate set before ranking. They are exact constraints, not hints: a row that
fails one is not returned at a lower score, it is not returned.

| Parameter | Type | Matches |
| --- | --- | --- |
| `license` | string, repeatable | Licence identifier, e.g. `apache-2.0`, `mit` |
| `format` | string, repeatable | Weight format the entity is published in, e.g. `safetensors`, `gguf`, `mlx` |
| `pipeline_tag` | string, repeatable | Task, e.g. `text-generation`, `automatic-speech-recognition` |
| `library_name` | string, repeatable | Library the entity is built for, e.g. `transformers`, `mlx` |
| `author` | string, repeatable | Publishing account or organisation |
| `language` | string, repeatable | Language code the entity covers |
| `family_root` | string | The model this one is derived from — a quantisation, a fine-tune, a conversion |
| `min_params` / `max_params` | integer | Total parameter count |
| `min_size_bytes` / `max_size_bytes` | integer | Size of the weights on disk |
| `has_chat_template` | boolean | Only entities that ship a chat template |
| `gated` | boolean | Whether access requires accepting terms |

Repeat a parameter to pass several values, and they are combined as *or*: `license=mit` plus
`license=apache-2.0` returns either. Different parameters are combined as *and*.

```sh
curl -G https://api.bighugger.com/v1/search \
  -H "authorization: Bearer $BIGHUGGER_KEY" \
  --data-urlencode 'q=speech to text' \
  --data-urlencode 'kind=model' \
  --data-urlencode 'format=gguf' \
  --data-urlencode 'license=apache-2.0' \
  --data-urlencode 'license=mit' \
  --data-urlencode 'max_params=2000000000'
```

The same call as a body:

```json
{
  "q": "speech to text",
  "kind": ["model"],
  "filters": {
    "format": ["gguf"],
    "license": ["apache-2.0", "mit"],
    "max_params": 2000000000
  }
}
```

### Sizes are numbers, not buckets

`max_params` and `max_size_bytes` take an exact figure because you have one. If a model has to fit
in 8GB of memory, that is a number you already know, and rounding it into a "small" band loses the
only information that mattered. Pass the number.

## The response

| Field | Type | Notes |
| --- | --- | --- |
| `object` | string | Always `list` |
| `query` | string | The query as it was interpreted |
| `reranked` | boolean | Whether the returned order came from reranking |
| `took_ms` | integer | Server-side time for the call |
| `count` | integer | Rows in `data` |
| `data` | array | The results |

Each row carries `id`, `kind`, `title`, `url`, `snippet`, `score` and `facts`.

`facts` is the structured record for that entity — the fields read out of its own configuration
rather than out of its description. It is the same schema the filters above are named after, which
means anything you can filter on you can also read back and display. Fields are present when they
are known and absent when they are not; treat a missing field as unknown rather than as zero,
because for a parameter count those are very different claims.

## Related

- [Quickstart](/docs/quickstart) — the first call
- [Errors](/docs/errors) — what a refused request looks like