Streaming and receipts

The text-only subset supports model, string or basic message input, instructions, max_output_tokens, string-valued metadata, and stream. It also accepts validated text.format on capable models. Ordinary streaming uses Responses events.

curl https://api.tokenspend.dev/v1/responses \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $TOKENSPEND_API_KEY" \
  -d '{"model":"zai/glm-5.2","input":"hello","max_output_tokens":256}'

Astra also supports function tools, tool-result continuation, images, and reasoning effort through native Responses, and so do the GPT-5 models from 5.1 to 5.6. Send the full input history, including returned encrypted reasoning items. Storage is disabled; stored-response chaining, background mode, and hosted tools return 400 before forwarding.

Native Responses tool streams are validation-buffered. Text and arguments arrive after the complete response passes validation. Other models keep the text-only subset. Check the model registry before using optional controls.

Every routed response carries x-tokenspend-request-id, canonical model, immutable revision, and registry version headers. Standard response bodies and stream framing stay unchanged.

Workspace admins can open the receipt to see protocol, streaming state, attempt count, same-model retry, configured model switch, token breakdown, itemized cost, metering state, and idempotency outcome. The serving host is never part of this proof.

• Ordinary requests may try the same model twice after a network fault, 429, or 5xx.
• Tool, reasoning, and validated structured-output requests use one attempt.
• A model switch runs only from an admin policy saved before the request.
• Canceled or interrupted streams receive one failed, incomplete receipt.

Public handlers have a 300-second platform ceiling. Client cancellation stops upstream work. Use error.retryable to decide whether a new request may succeed.

Label a request with the x-tokenspend-tag header: 1 to 64 characters of letters, digits, and . _ : / -. The tag is stored on the receipt. Never put prompt text, code, or personal data in a tag.

GET /v1/receipts returns the receipts of requests made with the calling key, oldest first. Filter with tag, tag_prefix, request_id, since and limit (up to 200). Page with after set to the previous nextCursor.

curl "https://api.tokenspend.dev/v1/receipts?tag_prefix=job-42/" \
  -H "Authorization: Bearer $TOKENSPEND_API_KEY"

Each receipt has the request id, tag, model, status, token counts, itemized cost and latency. A key reads only its own receipts. Receipts never include prompts, responses or the serving host.

Streamed receipts also carry hostTtftMs, the time from sending your request to the model host until its first piece of the answer, and callerTtftMs, the time from TokenSpend receiving your request until that first piece was handed to your response (retries included). Both are null for non-streamed requests, for tool and reasoning streams that TokenSpend validates before releasing, and when the client leaves first.

Every receipt also has requestDurationMs (request received until the response finished), outputTokensPerSec (streamed only), failoverDelayMs (time lost to failed attempts before the one that served you) and, for failed requests, errorOrigin: provider, gateway or client.

Send an Idempotency-Key on Chat Completions, Responses, or Messages. TokenSpend scopes it to your workspace and route for 24 hours.

curl https://api.tokenspend.dev/v1/chat/completions \
  -H "Authorization: Bearer $TOKENSPEND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-42-generation" \
  -d '{"model":"zai/glm-5.2","messages":[{"role":"user","content":"hello"}]}'

• A duplicate never creates another model request, receipt, or debit.
• An in-flight retry returns 409 idempotency_in_progress.
• A completed retry returns 409 idempotency_already_completed.
• A changed body returns 409 idempotency_key_reused.

Duplicate responses carry the original x-tokenspend-request-id. TokenSpend stores keyed fingerprints and state, not a replay copy of the response. Use a new key after a failed request.