Search

Retrieval across the whole index, with no model in the loop. One call embeds the query, searches every corpus, reranks the candidates against the query, and returns rows carrying the facts each kind is judged by — ids, licences, file sizes, parameter counts, benchmark scores. Reach for it when your own code will rank, filter or render the results and you do not want prose written for you.

A search is issued as one request, and the account is billed once for it, however much work the call bundles. It can be sent as GET or POST, and the two take the same parameters, so the method you choose does not change what the call accepts or returns. A call that cannot be billed is refused before it does any work, so the account is only ever billed for calls that actually run.

One limit to plan around is the result cap: a request for more rows than the maximum returns the maximum rather than failing, and the oversized request is still one call, billed as one call. An over-generous request therefore never errors and never costs more — it simply comes back with fewer rows than you asked for, so check the count in the response rather than assuming the size you requested was honoured.

Tags @api @search

Call it

GET https://api.bighugger.com/v1/search

curl -X GET https://api.bighugger.com/v1/search \
  -H 'authorization: Bearer $BIGHUGGER_API_KEY'

Every call is authenticated with an API key as a bearer token. A key carries scopes, so a key that cannot reach this endpoint is refused rather than silently returning less.

What it guarantees

graph LR
  cap["Search"]
    b0("One call returns ranked rows,<br/>billed as one call")
    b1("A call that cannot be billed<br/>is refused before it runs")
    b2("GET and POST take the same<br/>parameters")
    b3("A request for more rows than<br/>the maximum returns the<br/>maximum")
  cap --> b0
  cap --> b1
  cap --> b2
  cap --> b3
  classDef cap fill:#eef2ff,stroke:#1d4ed8,stroke-width:1px,color:#1d4ed8
  classDef beh fill:#fffdf2,stroke:#eeb900,stroke-width:1px,color:#14161a
  class cap cap
  class b0,b1,b2,b3 beh

Always true

Given a caller with an API key
And the key carries the search scope

One call returns ranked rows, billed as one call

Billing the account for a single search rather than per row keeps costs predictable and stops charges from growing with the rows returned.

Given an account that can cover a search
When the key is accepted
And the key carries the search scope
Then rows are returned
And the account is billed in single tokens

Vocabulary account

A call that cannot be billed is refused before it runs

Allowing an underfunded call to run would let the service perform work it can never be paid for, so the request is stopped before any cost arises.

Given an account whose balance cannot cover a search
When the search is requested
Then the request is refused with a payment error
And nothing is billed for the refused call

Vocabulary account

GET and POST take the same parameters

Without a shared parameter set, callers would maintain separate request-building code for each method, and the paths could quietly drift into returning different results.

Given a caller sending <method>
When the request carries the same query and filters
Then both return the same results

Examples — methods accepted

method
GET
POST

A request for more rows than the maximum returns the maximum

Without a ceiling on rows, a single caller could demand arbitrarily large result sets and degrade the service for everyone else.

Given a caller asking for more rows than the maximum
When the limit is read
Then the response returns the endpoint's maximum number of rows

What to know

Each call is billed to your account once, whatever it returns, so there is nothing to save by keeping requests small — when you need many rows, prefer fewer, fuller calls. A call that cannot be billed is refused before the search runs: nothing executes, nothing is consumed, and once the account problem is fixed the same request can be sent again unchanged. That kind of refusal is a setup problem rather than a query problem, so if calls start coming back refused, look at the account before the parameters.

GET /v1/search takes the same parameters over POST, so choose the method per call — GET for a short query you want visible in a log, POST once the query outgrows a URL. Asking for more rows than the maximum is not an error: you get the maximum, and the cap is silent, so the number of rows actually in the response is the only count worth trusting. Rows are not uniform, either; the facts each carries depend on the kind of result it is, so a field present on one row can be missing on the next, and your code should check before it sorts, filters or renders on one.