BigHugger
Request accessSign in

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

ParameterTypeDefaultNotes
qstringrequiredWhat you are looking for, in plain language. query is accepted as an alias.
kindstring, repeatableall kindsRestrict to one or more entity kinds.
limitinteger20Rows to return, up to 50. Asking for more returns the maximum rather than an error.
rerankbooleantrueSet 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.

ParameterTypeMatches
licensestring, repeatableLicence identifier, e.g. apache-2.0, mit
formatstring, repeatableWeight format the entity is published in, e.g. safetensors, gguf, mlx
pipeline_tagstring, repeatableTask, e.g. text-generation, automatic-speech-recognition
library_namestring, repeatableLibrary the entity is built for, e.g. transformers, mlx
authorstring, repeatablePublishing account or organisation
languagestring, repeatableLanguage code the entity covers
family_rootstringThe model this one is derived from — a quantisation, a fine-tune, a conversion
min_params / max_paramsintegerTotal parameter count
min_size_bytes / max_size_bytesintegerSize of the weights on disk
has_chat_templatebooleanOnly entities that ship a chat template
gatedbooleanWhether 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.

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:

{
  "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

FieldTypeNotes
objectstringAlways list
querystringThe query as it was interpreted
rerankedbooleanWhether the returned order came from reranking
took_msintegerServer-side time for the call
countintegerRows in data
dataarrayThe 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