Create a chat completion
const url = 'https://api.staging.katara.com/v1/chat/completions';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"model":"katara/llama-3.1-8b-instruct@1","messages":[{"role":"user","content":"Explain a Merkle tree in two sentences."}],"max_tokens":200}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.staging.katara.com/v1/chat/completions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "model": "katara/llama-3.1-8b-instruct@1", "messages": [ { "role": "user", "content": "Explain a Merkle tree in two sentences." } ], "max_tokens": 200 }'Same request body as OpenAI chat completions. Set stream: true for server-sent events.
The reply carries a katara object with what you were charged and who served you.
In a stream it arrives as one final chunk with an empty choices array, after the content
and before data: [DONE].
Admission is checked before any work starts: the balance behind the key must cover the
maximum this request could cost (input estimate plus max_tokens at the offer price).
Otherwise the request is refused with insufficient_quota and nothing is charged.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
object
object
Bounds the output and therefore the maximum charge.
object
object
Example
{ "model": "katara/llama-3.1-8b-instruct@1", "messages": [ { "role": "user", "content": "Explain a Merkle tree in two sentences." } ], "max_tokens": 200}Responses
Section titled “Responses”The completion, or a server-sent event stream when stream is true.
object
Who served the request. <bundle>:<profile> for a named model,
cortex:<model> for a reply routed by katara/cortex@1.
object
object
Null when the reply is tool calls only.
Validated calls. Every entry has an id, a non-empty name and arguments that parse as a JSON object.
object
object
A JSON object document.
object
What this reply cost and who produced it.
object
The settled price, in USDC, as a decimal string.
The provider’s address, or managed when a vendor answered through katara/cortex@1.
Present on replies routed by katara/cortex@1. The concrete model behind the reply.
object
The address that served, or the managed identity.
True when a vendor answered because no marketplace provider could.
available, failover:<n> after n models failed before delivering, or managed:<why>.
Example
{ "id": "chatcmpl-7f3a9c2e1b0d", "object": "chat.completion", "model": "katara/llama-3.1-8b-instruct@1", "system_fingerprint": "0xb353…:0x620b…", "choices": [ { "index": 0, "finish_reason": "stop", "message": { "role": "assistant", "content": "A Merkle tree hashes data in pairs up to one root hash…" } } ], "usage": { "prompt_tokens": 18, "completion_tokens": 52, "total_tokens": 70 }, "katara": { "cost_usdc": "0.000018", "provider": "0xfFe5…38DC" }}data: {chunk} lines ending with data: [DONE]: a role chunk, content deltas, each
tool call whole in one chunk, a finish chunk, a chunk with empty choices carrying
usage, then one carrying katara. A failure after content was sent ends with an
error chunk (stream_interrupted or provider_output_invalid) before [DONE].
Headers
Section titled “Headers”Request id for support and for matching usage records.
Malformed request, or a feature the model does not support (feature_not_supported, with param naming the field for tool options).
object
object
For people. Wording may change.
Stable. Branch on this.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}Missing or unknown key (invalid_api_key).
object
object
For people. Wording may change.
Stable. Branch on this.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}The account is suspended (account_suspended).
object
object
For people. Wording may change.
Stable. Branch on this.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}Unknown model (model_not_found).
object
object
For people. Wording may change.
Stable. Branch on this.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}The balance behind the key cannot cover this request (insufficient_quota).
Add USDC, or raise the budget cap, then retry.
object
object
For people. Wording may change.
Stable. Branch on this.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}Headers
Section titled “Headers”Every provider tried answered with something the marketplace refused to deliver, such as a malformed tool call (provider_output_invalid). Nothing was charged. Retry after Retry-After.
object
object
For people. Wording may change.
Stable. Branch on this.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}Headers
Section titled “Headers”No provider can take the request right now (no_capacity); a named model is never substituted. Retry after Retry-After, or ask katara/cortex@1.
object
object
For people. Wording may change.
Stable. Branch on this.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}