Anathema API Reference

The API exposes a chat endpoint, POST /v1/chat/completions, matching the OpenAI Chat Completions shape, plus model-discovery endpoints under /v1/models. Chat responses come back as standard JSON, or as a Server-Sent Events stream when you set stream: true. You authenticate with a Bearer API key created in your developer dashboard.

The API is stateless. There is no server-side conversation memory, so send the full message history on every request, exactly as you would with OpenAI.

Replace the placeholder with a secret key from the Keys tab, then run:

Every request needs a Bearer API key. Create, rotate, and revoke keys in your dashboard.

• Keys are shown once. Copy the key when you create it; we only ever store a hash.
• Rotate to swap a live key for a new one. The old key stops working immediately.
• Revoke to kill a key instantly. A revoked or rotated-out key returns 401.
• Scopes: keys carry a chat scope (today's only scope). Future scopes will gate additional capabilities.
• IP allowlist (optional): restrict a key to specific IPs or CIDRs from its settings. A request from a non-allowlisted IP is rejected.

You must fund your account before you can create keys (minimum $5). See Pricing.

lexi answers candidly on subjects most models refuse and holds consistent positions rather than hedging. She is a fixed personality, not a blank slate you reshape per request, and she grounds answers with built-in research and a curated library (see Tools & grounding).

ana is a coding model. She is calibrated and direct, and she surfaces a blocker rather than routing around it. She is in beta and served differently from lexi, which is covered under Data handling below.

What either model will and won't do is governed by our Acceptable Use Policy.

Model ID

ana

Context

900,000

Max output

130,048

Input $/M

$5.50

Cached input $/M

$0.50

Output $/M

$20.00

Vision

Yes

Max images

8

Tools

Yes

Status

Beta

Model ID

lexi

Context

900,000

Max output

64,000

Input $/M

$3.00

Cached input $/M

$0.30

Output $/M

$15.00

Vision

Yes

Max images

8

Tools

Yes

Status

Active

Context is the most you can send in one request, counting your own messages. The system prompt we add rides outside it, and outside your bill. Max output is the visible tokens one response can return. Cached input bills the leading tokens of a request the engine has already processed recently. It applies to that repeated prefix only, and the rest of the prompt bills at the input rate, so a bill sits between the two figures rather than at either one.

ana runs on Kimi K3, served by third-party infrastructure rather than hardware we operate. Requests you address to ana leave our systems to be answered.

Both models have built-in tools they use on their own to ground answers in current, real information. You don't configure or invoke them; the model decides when they help, runs them server-side, and you receive the finished answer. The individual tool calls do not appear in the response.

The tool set differs by model:

• Web research (lexi and ana): live search plus page reading for current events and facts.
• Library search (lexi and ana): a curated corpus of primary sources the model can list, draw on, and cite.
• Firearm-file search (lexi only): the GunCAD Index of 3D-printable firearm files.
• Code execution (ana only): a sandbox that runs Python, JavaScript, Bash, C, or Rust and returns the real output. Ana is a coding model and calls it herself when a question is better answered by running code. It costs you nothing beyond the tokens of the turn, and there is no per-request switch to enable it.

Not on the API: image generation and long-term memory are features of the consumer app and do not run through the API on either model.

The tools above are what the model has on a request that sends no tools array of your own. Send one and yours take their place. See Function calling.

Send your own tools and the model calls them the standard OpenAI way: it returns tool_calls with finish_reason: "tool_calls" instead of a normal answer. You run the call, then send the result back as a role: "tool" message to continue the conversation. Works on both models.

Your tools replace ours. Send a tools array and the model gets exactly those, plus the one reserved name below. The built-in tools under Tools & grounding, research and page fetching among them, are not added beside yours: a coding harness brings its own, and every call you receive is for a function you defined.

A name you define is always yours. Send a tool called research and it is your research, called and returned to you like any other tool of yours. You will never receive a call for a function nobody defined.

"anathema_tools": false asks for a plain completion: send it with no tools array of your own and the model gets none of the built-in tools above either. On a request that does carry your own tools it changes nothing, since ours are already out.

One name is reserved: aup_violation. It is ours on every call, including calls that send "anathema_tools": false, and it is never returned to you to run. A request whose tools array defines a function by that name returns 400 unsupported_feature naming it. Rename the function and send it again.

tool_choice is honored: "auto", "none", "required", or a named function. A named function must be one you defined in this request's tools array.

On ana, response_format and tools combine freely on one request. The model either calls one of your tools or answers in your schema, and both stay available for the whole turn. When it calls one, that ends the turn the same way it would without a schema: you get finish_reason: "tool_calls" and no content, and the schema applies to the answer it gives after you send the tool result back. On lexi the two cannot be combined: a schema constrains her output from the first token, so there is no point in the turn at which she could call one of your tools instead, and the request returns a 400 saying so rather than accepting tools it could never dispatch.

Tool definitions count toward your prompt tokens and toward the model's published input limit. There is no separate cap on how many tools you can send.

Run list_files yourself, then send the result back as a role: "tool" message, with the same tools array resent alongside it:

The API is stateless, so tools must be resent on the follow-up. A request that omits it is not sending your tools, and the model gets our built-in set for that turn instead.

Standard OpenAI Chat Completions fields:

Idempotency: send an Idempotency-Key: <unique-string> header to make retries safe. A repeated key replays the original response instead of billing twice. A streamed response cannot be replayed, so a streamed request holds its key only while it runs: a duplicate sent while it is still running gets 409 idempotency_key_in_use, and a retry sent after it finishes runs again and is billed again.

Because the API is stateless, a multi-turn conversation is just the running history resent on each call: append the model's previous reply as an assistant message, add the new user turn, and send the whole array again. This works the same way on both models.

Every token you resend is billed again, so for long sessions trim old turns yourself once they stop being relevant. There is no hidden server-side truncation: if the history exceeds the context window you get context_length_exceeded.

Add one or more system messages to steer how the model responds: tone, format, length, focus, output structure. Your instructions are layered on top of its persona. Both models work this way.

You can shape the delivery, but you can't override a model's core identity or positions with a system prompt. Lexi and Ana are both fixed personalities, and instructions that try to make either one someone else are ignored.

A non-streaming request returns a standard chat.completion object. The answer is in choices[0].message.content, and token counts are in usage:

finish_reason is stop on a complete answer, length when output hit the max_tokens budget (raise max_tokens or continue the conversation to get the rest), and tool_calls when the model is asking you to run one of the functions you supplied. Handling that one is covered under function calling above. usage.prompt_tokens is what you are billed for on the input side. It counts your tokens only: your messages, your system prompt, any image tokens, and any tool definitions you send. The model's own persona rides every request internally but is neither reported nor billed, on either model. prompt_tokens_details.cached_tokens reports how much of your prompt was served from prefix cache: stable content (your system prompt, earlier conversation turns you resend) caches automatically, so keeping your system prompt byte-identical across calls makes repeat requests faster. Both models report cached tokens. On the output side, usage.completion_tokens counts every token the model generates, billed at the output rate, and that includes internal reasoning tokens whenever reasoning ran. The reasoning text itself is never returned. On lexi, reasoning always runs, at low effort unless you ask for more, shares the max_tokens budget with the answer, and is reported exactly in usage.completion_tokens_details.reasoning_tokens. On ana, reasoning runs on every request and responses carry no completion_tokens_details at all, so her reasoning is inside completion_tokens without a separate line for it.

Every response carries headers worth reading:

Send the standard OpenAI response_format with a JSON Schema and the response content is guaranteed to parse as a valid instance of it. JSON.parse(content) cannot throw and cannot return a shape outside your schema. Tools keep working underneath on both models: if the request needs research or a library lookup, the model does that first and the final answer still lands in your schema.

The answer arrives in choices[0].message.content as the JSON string, same key as every other response, nothing new to parse, and any OpenAI SDK handles it unmodified. Rules worth knowing:

• Schema subset. Supported keywords: type, properties, required, items, enum, const, anyOf, additionalProperties (boolean), internal $ref/$defs, and numeric/length/array bounds. pattern and format are rejected. Anything unsupported returns a 400 naming the keyword and its location.
• Field description steers the model. description and title on a field are passed through to guide what the model puts there. Use them the way you would on any OpenAI structured-output call. The remaining annotations (examples, default, $comment, and similar) are accepted and ignored.
• Caps. Schemas up to 32 KiB, 8 levels deep, 256 properties total, 64 entries per enum. Property names are plain identifiers.
• Both models constrain generation. The inference engine holds the output to your schema as it is produced, so the model cannot choose to answer off-schema and there is no validate-and-retry step to pay for. One consequence worth planning around: a schema that fights the question is answered rather than refused. Give an enum that excludes the true answer and you get a value from the enum, not an error.
• Check finish_reason before you parse. A constrained response can still be cut off by max_tokens, and a truncated instance is incomplete JSON. That arrives as a normal 200 with finish_reason: "length", the same as any other truncated response. Treat "length" as a failed parse and retry with a larger budget. Reasoning tokens count against max_tokens, so a schema that needs the model to think can be cut off well before the JSON looks long.
• Streaming works on both models. stream: true with a schema is supported everywhere, and concatenating the content deltas gives you exactly the instance a non-streamed call returns. On ana the JSON arrives as one delta rather than token by token, because a half-written object is not something you could parse anyway.
• Contradictory bounds are rejected. Bounds no value can satisfy (minLength above maxLength, minimum above maximum, and the same pattern on items and exclusive bounds) return a 400 naming both bounds and the field. Nothing is billed.
• Reasoning follows the model's own default here too. On lexi it runs at low effort by default; setting "medium" or "high" raises it, and the response still parses as valid JSON. On ana reasoning runs regardless, and the response still parses as valid JSON.
• Reuse the schema byte-identically across calls. The schema rides in the prompt, so a stable schema prefix-caches and bills at the cached rate; a schema that changes every call loses those hits.
• Billing is unchanged. Output tokens are the JSON itself; tool steps bill exactly as without a schema.

Loose JSON mode. If you only need valid JSON without a fixed shape, send {"type":"json_object"} instead of a schema. The response content is guaranteed to parse as JSON, and the model fills it from your prompt, so describe the fields you want in the message. When you know the shape, prefer json_schema: it is strictly stronger (the keys and types are enforced, not just the JSON-ness). json_object follows the same per-model streaming rule as json_schema, and like it, reasoning runs at low effort by default and higher if you set reasoning_effort.

Give the schema a way to say "I don't know." A structured request is always answered in your schema, even when a search turns up nothing, so the model cannot fall back to a prose "I couldn't find that." If your use case depends on research or retrieval, add a field that can express the absence: a found boolean, a nullable result, or a confidence number. Without one, a populated-looking answer can mask a search that came up empty. The JSON will be valid either way, so the uncertainty has to live in the schema, not in the prose you no longer get.

Set "stream": true to receive a text/event-stream of chat.completion.chunk events terminated by data: [DONE], exactly like OpenAI:

With the OpenAI SDK it's the same iterator you already use:

Both models can see images. Send them as content parts in the standard OpenAI vision format: a user message whose content is an array of text and image_url parts.

Two ways to supply an image:

• A public https URL. We fetch it for you.
• An inline base64 data URL, like data:image/png;base64,…. The request body is capped at 12 MB, which comfortably fits a max-size (8 MB) image plus your prompt. An image too large to fit inline can be passed as a hosted URL instead; those are fetched server-side and don't count against the body limit. An oversize body returns 413 payload_too_large.

• Formats: JPEG, PNG, WebP, GIF.
• Max size: 8 MB per image (hosted URLs).
• Images per request: per model, in the Max images column of the table under The models. GET /v1/models reports the same number as max_images_per_request.

Images attach only to user (and assistant) turns, not system. An image the fetcher read and rejected returns image_input_invalid (400); a failure inside our own fetch path returns image_service_unavailable (503) or image_service_error (502) instead, since there is nothing in the request to change. A content part that isn't text or an image returns multimodal_not_supported.

Both models can read the content of links in your request. When URL fetching is enabled for your organization, we fetch the text of any URLs in the latest user message, then give the model the page content so it answers from the page rather than from the link alone. The setting is per organization and applies to every model.

URL fetching is off by default. An organization owner turns it on under Developers → Settings → URL fetching. The setting applies to every request the organization makes. There is no per-request override, so an OpenAI client works without modification.

• Up to 5 URLs per request are fetched, taken from the latest user message. Additional URLs are ignored.
• You are billed for the fetched content as input tokens at the standard rate. A large page can raise the cost of a request.
• A fetch that fails does not fail your request. The model receives an inline note such as [Could not fetch <url>: timeout] and answers from the rest of the message, so it never invents page content.
• Fetched content is treated as untrusted. The model reads it as quoted source material and ignores any instructions embedded in a page.

If fetched content pushes the request past the model context window, the request returns 400 context_length_exceeded. Shorten the message or fetch fewer pages.

GET /v1/models lists available models and GET /v1/models/{id} retrieves one, both authenticated with the same Bearer key (no balance or rate-limit cost). The objects use the standard OpenAI shape plus capability fields, so a client that probes /v1/models on init works unchanged.

The limits that are the same on every model. Context window, output ceiling and images per request vary by model and are in the table under The models. Each limit is explained in the section it belongs to.

We do not silently truncate. A prompt over the context window returns 400 context_length_exceeded so you can split the work rather than get an answer about a partial input. Need higher rate limits? See Rate limits.

Pay-as-you-go, billed per token. No subscription.

Per million tokens. Minimum first purchase $5.

Caching is automatic and free to use. When a request starts with content the engine recently processed (your system prompt, earlier turns of a conversation you resend, a document you keep asking about), those tokens bill at the cached rate and the response reports them in usage.prompt_tokens_details.cached_tokens. There is nothing to enable and no cache-write fee. To maximize hits: keep your system prompt byte-identical across calls, append to conversations instead of editing earlier messages, and reuse stable context verbatim. Caching is best-effort (a cold start or long idle resets it), so the first request in a while bills at the standard rate.

• Spend cap: set a monthly usage cap in your dashboard; requests pause when you hit it (it resets each period; it is not a charge ceiling).
• Auto-recharge: opt in to top up your balance automatically when it runs low.

Plan API spend for your expected input and output. Estimates use the selected model’s rates.

Defaults per organization:

Pace yourself with the x-ratelimit-* response headers (see Responses). Over-limit requests return 429 with a retry-after header. Need more? Request a raise from your dashboard, or contact [email protected] for higher limits.

OpenAI-compatible error envelope. Every error carries a request_id; include it in support requests.

401invalid_api_key

Key is missing, malformed, revoked, blocked by your IP allowlist, or lacks the scope this endpoint requires

402insufficient_balance

Out of credits; top up your balance

402spend_cap_exceeded

Monthly spend cap reached

404model_not_found

A model id we do not serve, either unknown or retired. The message lists what is available, and GET /v1/models returns the same set

429rate_limit_exceeded

Too many requests; back off and retry

400invalid_content_type

The Content-Type header is missing or does not say application/json, so the body was never read. Send Content-Type: application/json and retry the request unchanged

400invalid_json

The body did not parse as JSON. Nothing else in the request was read, so no field is named. Check what your client actually put on the wire

400invalid_request_body

The body is JSON but does not match the schema, for example no model, an empty messages array, a role we do not accept, or n above 1. The message quotes the first field that failed, and that is the one to fix

400unsupported_feature

A parameter is shaped correctly but its value is not implemented here, such as logprobs, a tool_choice other than auto, or json_schema with stream true. The message names the parameter. Drop it or send a supported value

400tool_choice_unsupported

Named tool_choice is not supported on ana. Use auto, required or none; named choices on lexi are unchanged

400max_tokens_too_small

max_tokens below the 512 minimum; raise it or omit it

400max_tokens_too_large

max_tokens above the output ceiling (16,384, minus the active reasoning budget); lower it or omit it

400invalid_response_format_schema

response_format.json_schema failed validation; the message names the violating keyword or cap and its location

400aup_refusal

Request refused under the acceptable use policy

403org_suspended

Organization's API access is suspended; contact support

502no_response

The model produced no output (transient). Retry; not billed.

400image_input_invalid

An image was unreadable, too large, the wrong type, or could not be fetched

503image_service_unavailable

We could not load a remote image URL. Nothing to change in the request; retry it

502image_service_error

We could not load a remote image URL and a retry will not clear it. Send the image inline as a base64 data: URL, or contact support

400multimodal_not_supported

A content part type other than text or image_url was sent

400tool_role_unsupported

A role:"tool" message was sent on a request with no tools array. A role:"tool" message answers one of your own tool calls, so it only makes sense on a request that also sends tools

413payload_too_large

Request body exceeds 12 MB; shrink an inline image or pass a hosted image URL

400context_length_exceeded

Prompt exceeds the model's context window; shorten it or split across requests

400idempotency_key_invalid

The Idempotency-Key header arrived empty or longer than 256 characters. Send a key of 1 to 256 characters, or leave the header off

409idempotency_key_conflict

This Idempotency-Key was already used with a different request body, inside the 24 hour window the key lives for. Mint a fresh key per distinct request and reuse one only to retry the request that created it

409idempotency_key_in_use

A request holding this Idempotency-Key is still running, so this one was refused instead of running the same work twice. Retry once the first request finishes, or send a new key

Best practice: retry 429 and transient 5xx with exponential backoff; reuse an Idempotency-Key so the retry of a non-streamed request can't double-bill. On a streamed request the key refuses a concurrent duplicate rather than replaying, so back off before retrying. Not every 5xx is transient, and the Meaning column says which: image_service_error returns the same result on every attempt until we fix it. Both image_service_* responses also carry an x-should-retry header, true on the 503 and false on the 502; the official OpenAI client reads it instead of the status.

• max_tokens is a ceiling, not a target. On both models it includes reasoning. On lexi the default is 32,000 at low effort and 64,000 at medium or high. A small budget is served, and truncated with finish_reason: "length" if the answer does not fit. Omit it to use the model's default. The maximum is per model, in the table under The models.
• Don't tune temperature or top_p. They are accepted but ignored on both models, each of which runs at a fixed, tuned profile.
• On lexi, reasoning runs at low effort by default. Responses stay direct, so JSON, classification, and extraction stay clean and parse-ready, with no markdown fences and no preamble. For harder, open-ended tasks, set reasoning_effort to "medium" or "high". ana always reasons, so size max_tokens with that in mind.
• Use an Idempotency-Key on anything you might retry.
• Check finish_reason. length means the answer was cut off; raise max_tokens or continue the conversation.
• High max_tokens values suit input-anchored work. Translation, extraction, transformation, and annotation of long inputs decode cleanly at length, because the source material anchors the output. Open-ended generation asked to run very long tends to thin out and repeat well before the ceiling; for that, several focused requests beat one enormous one.
• Stream for interactive UX; non-streaming for batch.
• Handle 429 and 5xx with exponential backoff, pacing off the x-ratelimit-* headers.
• Trim old turns in long conversations; you pay for the full history on every call.
• Store keys server-side, never in client code. Rotate on suspicion of exposure.

The API is versioned in the path (/v1). Within a version we make only backwards-compatible changes: new fields on responses, new endpoints, new models, new capabilities. We will not remove fields or change the shape of an existing response under /v1, so code written against it today keeps working.

A genuinely breaking change would ship under a new version path, and we would give notice before retiring an old one. Treat unknown response fields leniently (ignore what you don't recognize) so additive changes never break your client.

Both models are far more permissive than mainstream ones, but not unbounded, and the same policy governs each. What is and isn't allowed is spelled out in our Acceptable Use Policy. Requests that cross those lines are refused with aup_refusal, and repeated or severe violations can result in suspension of your API access (you'll see org_suspended). Build accordingly: handle refusals gracefully and don't route prohibited content through the API.

Questions, limit raises, or a key you can't explain: email [email protected] with the request_id from the response.