Create a response
const url = 'https://api.katara.com/v1/responses';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"model":"katara/cortex","input":"Explain a Merkle tree in two sentences.","max_output_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.katara.com/v1/responses \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "model": "katara/cortex", "input": "Explain a Merkle tree in two sentences.", "max_output_tokens": 200 }'Text, images, files, function, custom and web search tools. Any model name, or none, is
served by Katara Cortex, and the reply names katara/cortex. Without a key,
katara/cortex-genius or katara/cortex-smart fix the model and the reply still names
katara/cortex; with a key they are refused. Reasoning settings are accepted and change
nothing. See Responses.
The response is stored for 30 days unless the request sends store: false. With a key it
belongs to the key’s account; without a key it belongs to nobody and whoever holds its id
can read, continue or delete it. Without a key the call is paid per request with x402,
exactly as a chat completion.
Authorizations
Section titled “Authorizations”- bearerAuth
- None
Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Without a key, base64 of the x402 payment payload that signs the quote from a previous 402.
The same payload under the header name of the first x402 version, paid with exact.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Any model name; every one is served by Katara Cortex. Without a key, katara/cortex-genius or katara/cortex-smart fix the model; a request with a key that names either is refused with model_requires_x402.
A message (role user, assistant, system or developer, with string or typed content), or a
typed item: function_call, function_call_output (string or a list of parts),
custom_tool_call, custom_tool_call_output, reasoning, web_search_call,
tool_search_call, tool_search_output, additional_tools, agent_message, or an
item_reference to an item of a stored response. Replayed web_search_call items and
encrypted_content are dropped.
object
input_text, output_text and refusal; input_image with image_url or file_id; input_file with file_id or file_data; input_audio; and summary_text and reasoning_text in reasoning items. Files are uploaded through /v1/files.
object
JSON argument document encoded as text.
Sent as a system message.
False keeps the response from being stored.
A stored response to continue from. With a key, one of the account’s; without a key, one stored without a key.
function, custom, namespace, tool_search and web_search tools (web_search_preview and dated variants too). file_search, mcp, computer, computer_use, computer_use_preview, code_interpreter, image_generation, local_shell, shell and apply_patch are refused with unsupported_tool.
object
JSON Schema for the function arguments.
object
False gets at most one tool call per reply.
Lowers the cap of five web searches per request.
Accepted with any effort and changes nothing; Katara Cortex decides how much the model reasons. summary returns reasoning as summary text.
object
object
object
object
Returned with the response; never forwarded to providers. Limits are measured in UTF-8 bytes.
object
The same controls as on Chat Completions.
object
False excludes Katara Community.
Keeps a conversation on the model whose cache holds its start.
Accepted; the response is answered once it is complete.
Accepted. Katara returns no encrypted reasoning.
Not forwarded to providers.
Not forwarded to providers.
Accepted and ignored.
Accepted and ignored.
Accepted and ignored.
Accepted and ignored.
object
Accepted and ignored.
Accepted and ignored.
object
Accepted and ignored.
Example
{ "model": "katara/cortex", "input": "Explain a Merkle tree in two sentences.", "max_output_tokens": 200}Responses
Section titled “Responses”A response object, or a named server-sent event stream.
object
Unix seconds.
Assistant messages with output_text (and url_citation annotations for pages the answer quotes), function_call and custom_tool_call items, reasoning items and web_search_call items with their sources.
object
object
object
object
object
object
What this reply cost.
object
The settled price, in USDC, as a decimal string. For a request paid with x402 it is the charge, the model’s minimum included (0.025 USDC, 0.05 for katara/cortex-genius, 0.01 for katara/cortex-smart).
The Credits charge as a decimal string. This legacy field name is retained for compatibility; display Credits without a dollar sign.
On a request paid with x402, the payment that settles the reply.
object
The token paid.
The charge in the token’s base units, the same as amount in PAYMENT-RESPONSE.
The provider’s address, or managed when a vendor answered.
Prompt tokens the vendor read from its cache, billed at the cached input rate.
What the cached tokens saved against the input rate, in USDC.
The same saving in Credits, on a reply paid with account credits.
When katara.compaction summarised the conversation.
object
The system message to send in place of the summarised messages.
object
First index in this request’s messages that the summary replaces.
First index kept after it.
The summary request’s usage and its cost (cost_usdc or cost_usd).
object
Why no summary was made; the request went whole.
object
Tokens this request wrote to a new explicit cache (katara.cache).
How long that cache is kept.
What keeping it costs, in USDC; included in cost_usdc.
On Test, a reply with fixed text that no model wrote, served when no Test provider was free.
The stop sequence at which Katara ended the reply.
The searches this request was charged for.
object
The successful searches; only those are charged, and none when the request ended without an answer.
On a web search request, how many model calls it made.
Every search the model made, in order. Not on stream chunks, which carry each search as it runs.
object
object
On an image reply from a model that edits, the id to send as previous_edit_id.
What this reply cost.
object
The settled price, in USDC, as a decimal string. For a request paid with x402 it is the charge, the model’s minimum included (0.025 USDC, 0.05 for katara/cortex-genius, 0.01 for katara/cortex-smart).
The Credits charge as a decimal string. This legacy field name is retained for compatibility; display Credits without a dollar sign.
On a request paid with x402, the payment that settles the reply.
object
The token paid.
The charge in the token’s base units, the same as amount in PAYMENT-RESPONSE.
The provider’s address, or managed when a vendor answered.
Prompt tokens the vendor read from its cache, billed at the cached input rate.
What the cached tokens saved against the input rate, in USDC.
The same saving in Credits, on a reply paid with account credits.
When katara.compaction summarised the conversation.
object
The system message to send in place of the summarised messages.
object
First index in this request’s messages that the summary replaces.
First index kept after it.
The summary request’s usage and its cost (cost_usdc or cost_usd).
object
Why no summary was made; the request went whole.
object
Tokens this request wrote to a new explicit cache (katara.cache).
How long that cache is kept.
What keeping it costs, in USDC; included in cost_usdc.
On Test, a reply with fixed text that no model wrote, served when no Test provider was free.
The stop sequence at which Katara ended the reply.
The searches this request was charged for.
object
The successful searches; only those are charged, and none when the request ended without an answer.
On a web search request, how many model calls it made.
Every search the model made, in order. Not on stream chunks, which carry each search as it runs.
object
object
On an image reply from a model that edits, the id to send as previous_edit_id.
object
object
Example
{ "object": "response", "status": "in_progress", "model": "katara/cortex", "output": [ { "type": "message", "status": "in_progress", "role": "assistant", "content": [ { "type": "output_text" } ] } ], "katara": { "cost_usdc": "0.000018", "cost_usd": "0.000018", "billing_method": "credits", "payment": { "scheme": "upto", "network": "eip155:43114", "amount": "25000" }, "web_searches": [ { "error": "invalid_input" } ] }, "incomplete_details": { "reason": "max_output_tokens" }}Named events with JSON data and a sequence_number. Text, function and custom tool arguments arrive as deltas. A web search opens its web_search_call item with response.web_search_call.in_progress and response.web_search_call.searching when it starts, and response.web_search_call.completed follows once it has run. response.completed or response.incomplete carries the response with final usage and the katara charge. A failure ends with response.failed. An HTTP 200 alone is not success.
Headers
Section titled “Headers”The request id.
Payment result when paid with x402.
Invalid input or a refused feature, with param naming the field. Codes are invalid_json, invalid_type, invalid_value, unsupported_parameter, unsupported_tool and invalid_request.
object
object
Stable error code.
Explanation for the caller.
Examplegenerated
{ "error": { "type": "example", "code": "example", "message": "example", "param": "example" }}Missing, expired or invalid key.
object
object
Stable error code.
Explanation for the caller.
Examplegenerated
{ "error": { "type": "example", "code": "example", "message": "example", "param": "example" }}The funds behind the key cannot cover the request (insufficient_quota, with x-should-retry false), or, without a key, a quote with PAYMENT-REQUIRED set, as for chat completions, or a payment that does not verify (payment_invalid).
object
object
Stable error code.
Explanation for the caller.
An x402 quote for one request.
object
The ways this request can be paid, for the same maximum. upto entries, where offered, come before exact. Sign one.
object
upto: a Permit2 transfer of at most amount, of which only the charge is pulled. exact: an EIP-3009 transfer of amount, with the difference refunded. Neither collects more than was signed.
The chain as a CAIP-2 id.
The USDC contract the authorization is for.
The most this request can cost, in the token’s base units. At least the model’s minimum: 25000 (0.025 USDC), 50000 for katara/cortex-genius, 10000 for katara/cortex-smart.
The settlement contract; the authorization’s to.
Validity to give the authorization.
object
The token’s EIP-712 domain name.
The token’s EIP-712 domain version.
exact only. The job this quote is bound to. It may be signed as the authorization nonce; a random nonce also works.
The job this quote is bound to.
upto only.
upto only. The address that settles; the signed witness names it.
The address paid for the reply.
The model paid for: katara/cortex-genius or katara/cortex-smart when the request named one, otherwise katara/cortex for a chat, Messages, Responses or image request; the embedding model for embeddings.
katara/cortex for a chat, Messages, Responses or image request, whatever it named; the embedding model for embeddings.
True when a vendor’s model will answer.
eip2612GasSponsoring, when present: the token takes EIP-2612 permits, and a permit for
Permit2 sent with an upto payment is submitted with the settlement at Katara’s cost.
object
Example
{ "x402Version": 2, "error": "payment required", "accepts": [ { "scheme": "upto", "network": "eip155:43114", "asset": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", "amount": "25000", "maxTimeoutSeconds": 300, "extra": { "name": "USD Coin", "version": "2", "assetTransferMethod": "permit2" } } ]}Headers
Section titled “Headers”Base64 of the PaymentRequired object in the body. Present only on a quote.
previous_response_id names a response that is missing, expired, deleted or someone else’s (previous_response_not_found), or an item_reference names no stored item (not_found).
object
object
Stable error code.
Explanation for the caller.
Examplegenerated
{ "error": { "type": "example", "code": "example", "message": "example", "param": "example" }}Every vendor that could serve the request is rate limiting (provider_rate_limited). Retry-After says when to retry.
object
object
Stable error code.
Explanation for the caller.
Examplegenerated
{ "error": { "type": "example", "code": "example", "message": "example", "param": "example" }}Every candidate’s reply was refused or failed. Nothing was charged.
object
object
Stable error code.
Explanation for the caller.
Examplegenerated
{ "error": { "type": "example", "code": "example", "message": "example", "param": "example" }}No candidate could serve the request in time (provider_overloaded, upstream_timeout, no_capacity). Retry-After says when to retry.
object
object
Stable error code.
Explanation for the caller.
Examplegenerated
{ "error": { "type": "example", "code": "example", "message": "example", "param": "example" }}