Ask
Ask a question in the words you would use with a colleague and get one recommendation back, with the reasoning behind it and the sources it rests on. It plans the search, runs it across the index and the open web, reads what comes back, and commits to an answer. Every model id, parameter count, file size and licence in that answer is looked up at the time of answering rather than recalled, so what you get is checkable.
A question opens a thread that outlives the request, so what you ask next continues it rather than starting over. The answer is assembled from candidates reranked against the question you asked, and it is written out a line at a time, so a terminal can start printing it before the run finishes.
A question is billed once, however many steps the run takes — the cost does not grow with the work behind it. A run the account cannot fund is refused before any work starts, with the shortfall named in the refusal, so you never pay for a partial answer; give that refusal its own handling in your integration.
Tags @agent @api
Call it
POST https://api.bighugger.com/v1/ask
curl -X POST https://api.bighugger.com/v1/ask \
-H 'authorization: Bearer $BIGHUGGER_API_KEY' \
-H 'content-type: application/json' \
-d '{"question": "..."}'
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 guaranteesgraph LR
cap["Ask"]
b0("A question becomes a thread<br/>that outlives the request")
b1("A terminal reads the answer a<br/>line at a time")
b2("A run that cannot be funded is<br/>refused up front, with the<br/>shortfall named")
b3("One question is billed once,<br/>however many steps it takes")
b4("Candidates are reranked<br/>against the question before an<br/>answer is written")
cap --> b0
cap --> b1
cap --> b2
cap --> b3
cap --> b4
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,b4 behAlways true
Given a caller with an API key carrying the chat scope
A question becomes a thread that outlives the request
Without a thread that outlives the request, the question disappears once answered and nothing later can be built from it.
Given a question
When the question opens a thread
Then the question appears in the web history of the same account
And a workbook can be built from it later
A terminal reads the answer a line at a time
Without this, a caller would have to wait for the whole answer before reading anything, and a new kind of line would break clients written before it existed.
Given a caller without a browser
When the answer streams
Then each line is a self-contained JSON object carrying a type
And a client may render the types it understands and skip the rest
A run that cannot be funded is refused up front, with the shortfall named
Funding is checked before a run starts so that a caller who cannot afford it is refused immediately with the exact shortfall, rather than left stranded mid-question.
Given an account whose balance cannot cover a run
When the question is submitted
Then the request is refused with a payment error and the shortfall named
Vocabulary account
One question is billed once, however many steps it takes
Metering each internal step would make one question's cost unpredictable, so the customer is charged for the finished run rather than the work it took.
Given a question that plans, retrieves and writes
When the stream finishes
Then the whole run is billed once rather than per step
Candidates are reranked against the question before an answer is written
Ordering candidates by how well they fit the question keeps the answer grounded in the strongest evidence rather than in whichever documents happened to surface first.
Given a plan for the question
When candidates are gathered from the index
Then they are reordered by a model that reads the question and the candidate together
And only the ordered head reaches the model
What to know
The wording you send is load-bearing: what comes back is chosen against the question as asked, so put the real constraints into the question itself rather than holding them back for a follow-up. Handle one refusal as its own error case — if the account cannot fund the run, a call to POST /v1/ask is turned away before any answer begins and the response names the shortfall, so surface that shortfall to your user instead of a generic failure. The answer then arrives a line at a time, so read the stream as it opens; a client that buffers the whole body before rendering will look hung to whoever is waiting.
What you get back is one recommendation with its reasoning and the sources it rests on, and a client should carry all three — every model id, size and licence in the answer was looked up at the moment of answering, so the sources are what make it checkable. A question is billed once however much work the answer takes, which cuts both ways: splitting one question into several calls multiplies the bill without improving the answer, and an automatic retry after a dropped stream is quietly a second question as far as the bill is concerned. Keep the reference the response hands back as well — every question opens a thread that outlives the request, the workbook keeps it, and a follow-up asked against that thread is how the conversation continues later.