API reference

All requests go to:

https://tryknot.xyz/v1

Authenticate with either header — whichever your client already sends:

Authorization: Bearer knot_live_…
x-api-key: knot_live_…

Keys are stored only as a SHA-256 hash, so a database dump does not reveal them, and a lost key cannot be recovered — only replaced.

Embeddings, transcription and speech endpoints exist in the gateway and are covered by the router and the meter, but no model of those kinds is published yet, so each answers 404. They will be listed here the moment one is.

All prices are per 1,000,000 tokens.

cost = (prompt_tokens − cached_tokens) × input_price
     + cached_tokens                   × cached_input_price
     + completion_tokens               × output_price

Three conventions are easy to get wrong, so they are stated plainly:

• cached_tokens is a subset of prompt_tokens, not an addition to it. The cached portion is priced once, at the discounted rate.
• reasoning_tokens is already inside completion_tokens. It is shown separately in your usage log but never billed twice.
• If a model has no cached rate configured, cached tokens are billed at the full input price — never free.

Images are billed on the token counts the model reports, so cost tracks the size and quality of what was generated rather than a flat per-image fee.

Live prices for every model are on the catalog.

Set stream: true for server-sent events in the standard OpenAI chunk format, terminated by data: [DONE].

Knot forces stream_options.include_usage on, so the final chunk carries token counts — that chunk is what the request is billed from, which is why a streamed request costs exactly what a non-streamed one would.

The model field in every chunk is the public ID you asked for. Upstream deployment names are never exposed.

Each public model is backed by an ordered pool of capacity, usually spanning several accounts and regions.

• 429, 408 and 5xx are retried against the next deployment in the pool.
• Other 4xx return immediately — a malformed request fails identically everywhere, so retrying would only burn quota and delay the error you need to see.
• Failover is decided on response headers, before any body bytes reach you, which is why streamed requests get it too. Once a stream has started it is committed to that deployment.
• The x-knot-attempts response header reports how many deployments were tried. Greater than 1 means failover happened.

Requests are limited per key. Exceeding the limit returns 429 with a Retry-After header, which the OpenAI SDKs already back off on — so a well-behaved client needs no special handling.

The limit is generous enough that interactive use will not reach it. It exists to stop a runaway retry loop from draining a balance.

Errors use the OpenAI envelope, so existing SDK error handling works unchanged:

{
  "error": {
    "message": "…",
    "type": "…",
    "code": "…",
    "param": null
  }
}

A 4xx from the upstream model is forwarded verbatim, so you see exactly what the model said rather than a paraphrase.

For agents and assistants: /llms.txt is a short summary with the live catalog, and /llms-full.txt is this reference in full.