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@1","instructions":"Answer in two sentences.","input":"What is a Merkle tree?","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@1", "instructions": "Answer in two sentences.", "input": "What is a Merkle tree?", "max_output_tokens": 200 }'The OpenAI Responses API request shape. With a key the call is paid as a chat completion
with that key, from Account Credits or in USDC under the same rules. Without a key it is
paid per request with x402 exactly as a chat completion: the same 402 challenge, the same
schemes, the same 0.025 USDC minimum and the same settlement. Send the same body again with
the payment in PAYMENT-SIGNATURE.
Calls are stateless, with or without a key. store: true, previous_response_id, conversation,
background: true, a stored prompt and item_reference input items are refused with
stateless_only before any quote. Send the whole conversation in input.
Pay per request with x402 lists what the route takes.
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
object
Bounds the output and therefore the quote.
Function tools only.
object
format of text, json_object or json_schema.
object
effort, for models that reason.
object
Responses are never stored.
Returned as sent.
object
Example
{ "model": "katara/cortex@1", "instructions": "Answer in two sentences.", "input": "What is a Merkle tree?", "max_output_tokens": 200}Responses
Section titled “Responses”The response, or a server-sent event stream of Responses events when stream is true.
object
reason is max_output_tokens when the reply was cut there.
A message item with output_text, a reasoning item when the model reasoned, and a function_call item per tool call.
object
object
What this reply cost and who produced it.
object
The settled price, in USDC, as a decimal string. For a request paid with x402 it is the charge, the 0.025 USDC minimum included.
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.
The concrete model behind every successful named-model or Cortex reply.
object
The address that served, or the managed identity.
True when a managed vendor answered.
named for a selected model, available, pinned, failover:<n> after n models failed before delivering, or managed:<why>.
What this reply cost and who produced it.
object
The settled price, in USDC, as a decimal string. For a request paid with x402 it is the charge, the 0.025 USDC minimum included.
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.
The concrete model behind every successful named-model or Cortex reply.
object
The address that served, or the managed identity.
True when a managed vendor answered.
named for a selected model, available, pinned, failover:<n> after n models failed before delivering, or managed:<why>.
Example
{ "id": "resp_7f3a9c2e1b0d", "object": "response", "status": "completed", "store": false, "katara": { "cost_usdc": "0.000018", "cost_usd": "0.000018", "billing_method": "credits", "payment": { "scheme": "upto", "network": "eip155:43114", "amount": "25000" }, "served": { "model": "katara/qwen3-coder-30b-a3b@1" } }}event: and data: lines: response.created, response.in_progress, then for each
output item response.output_item.added, its delta events and
response.output_item.done, and last response.completed (or response.incomplete)
with the whole response. There is no data: [DONE]. A failure after content was sent
ends with response.failed and is not charged.
Headers
Section titled “Headers”Request id for support and for matching usage records.
As for chat completions. amount is absent on a stream; response.completed carries the charge in response.katara.
The call asked for stored state (stateless_only) or used a field the route does not take (unsupported_parameter), with param naming the field in both cases, was malformed (invalid_request), or named a model its key’s credits cannot pay for (model_requires_usdc).
object
object
For people. Wording may change.
Stable. Branch on this.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}Unknown key, or a call to the Test network without one (invalid_api_key).
object
object
For people. Wording may change.
Stable. Branch on this.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}Without a key, a quote, with PAYMENT-REQUIRED set, or a payment that does not verify (payment_invalid); with a credits key, insufficient_credits. As for chat completions.
object
object
For people. Wording may change.
Stable. Branch on this.
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 25000 (0.025 USDC).
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 the request named.
The model that will answer.
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
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}Headers
Section titled “Headers”Base64 of the PaymentRequired object in the body. Present only on a quote.
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" }}An upto payment from a wallet that has not approved Permit2 and carries no permit (permit2_allowance_required).
object
object
For people. Wording may change.
Stable. Branch on this.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}Too many unpaid quotes from one address (quote_rate_limited), or a USDC key whose balance cannot cover the call (insufficient_quota). 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”The provider quoted for a named model failed before delivering (provider_failed). Nothing was charged; request a new quote.
object
object
For people. Wording may change.
Stable. Branch on this.
Example
{ "error": { "type": "invalid_request_error", "code": "invalid_api_key" }}No provider can take the request right now (no_capacity). 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" }}