Chat

POST /v1/chat/completions is an OpenAI-compatible chat endpoint with memory built in. On every request Anona retrieves the most relevant memories from the space, injects them into the prompt, and stores the exchange back, so the conversation stays grounded in what came before without any extra calls. Point an existing OpenAI-compatible client at the Anona base URL and pick a space.

from openai import OpenAI

client = OpenAI(
    api_key="anona_live_YOUR_KEY",
    base_url="https://api.anonalabs.com/v1",
    default_headers={"X-Anona-Space-Id": "support-bot"},
)

Request

POST https://api.anonalabs.com/v1/chat/completions
Authorization: Bearer anona_live_...
Content-Type: application/json

{
  "model": "gpt-4o-mini",
  "space_id": "support-bot",
  "messages": [
    { "role": "user", "content": "What plan did I say I was on?" }
  ],
  "memory_limit": 5,
  "temperature": 0.7,
  "max_tokens": 512
}

Field	Type	Default	Description
`messages`	array	required	Standard chat messages, each with `role` and `content`.
`model`	string	deployment default	Optional. Omit it to use whatever model this deployment serves; that is the recommended default. Naming a model the deployment does not serve returns `400 invalid_model`, and the message names the one it does.
`stream`	boolean	`false`	Stream the reply as server-sent events. See Streaming.
`stream_options`	object	none	Streaming only. `{"include_usage": true}` appends the final usage chunk, exactly as on OpenAI. Omit it and no usage chunk is sent.
`max_tokens`	integer	none	Optional.
`temperature`	float	none	Optional.

Fields Anona does not model (top_p, n, stop, presence_penalty and the rest of the OpenAI request) are forwarded to the provider unchanged.

Memory tunables

Every knob can be set in the body or as a header. The header form exists so a stock client can set them once in default_headers and leave every call site alone; when both are present, the body wins.

Body field	Header	Type	Default	Description
`space_id`	`X-Anona-Space-Id`	string	`"default"`	Which space to recall from and store into. Omit it and the turn lands in a space literally named `default`, created on the first proxied turn if it does not exist yet, so a space you never created appears in your space list and in the dashboard. Set it once in `default_headers` to keep products apart.
`user_id`	`X-Anona-User-Id`	string	none	Scope the turn to one end user: it recalls only that user’s memories and stores the turn under them. One space, many users. See Scoping.
`agent_id`	`X-Anona-Agent-Id`	string	none	Scope the turn to one agent.
`session_id`	`X-Anona-Session-Id`	string	none	Scope the turn to one conversation or run.
`memory_limit`	`X-Anona-Memory-Limit`	integer, 1 to 20	`5`	How many memories to inject.
`memory_token_budget`	`X-Anona-Memory-Tokens`	integer	none	Approximate token cap for the injected block. Whole memories are dropped, lowest-ranked first, until it fits; the text is never truncated mid-sentence. The count is an estimate, not a tokenizer.
`auto_record`	`X-Anona-Auto-Record`	boolean	`true`	Store this turn back into the space. Set `false` for read-only turns, such as evaluating against a space without polluting it.
`memory`	`X-Anona-Memory`	boolean	`true`	Set `false` to skip recall and injection entirely for one call.

A header that cannot be parsed returns 400 invalid_tunable naming the header.

Space defaults

The same knobs can be stored on the space, so they apply to every proxied call without touching a call site. Resolution is per field, in this order:

request body  →  request header  →  space default  →  platform default

Method	Path	Description
`GET`	`/v1/spaces/{space_id}/chat-settings`	The space’s stored defaults. An unconfigured space returns all nulls, not a 404.
`PUT`	`/v1/spaces/{space_id}/chat-settings`	Replace them. A field left out of the body is cleared, not kept.
`DELETE`	`/v1/spaces/{space_id}/chat-settings`	Remove every override. Idempotent.

curl -X PUT https://api.anonalabs.com/v1/spaces/support-bot/chat-settings \
  -H "Authorization: Bearer anona_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"memory_limit": 12, "auto_record": false}'

{
  "space_id": "support-bot",
  "memory_limit": 12,
  "memory_token_budget": null,
  "auto_record": false,
  "memory": null
}

space_id is not a settable default: it is the key the defaults are stored under. A null means unset, not “off”: that field falls through to the platform default, so a space can configure one knob and inherit the rest. These endpoints are free, cost no credits, and remain available when an organization has run out of credits, because configuration should never be the thing you cannot change.

Response

OpenAI-shaped, plus two Anona fields.

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "gpt-4o-mini",
  "choices": [ { "index": 0, "message": { "role": "assistant", "content": "..." } } ],
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 },
  "memories_injected": 3,
  "space_id": "support-bot"
}

Field	Description
`memories_injected`	How many memories were pulled into this turn’s prompt.
`space_id`	The space the turn was recalled from and stored into.

The same two values are also returned as the X-Anona-Memories-Injected and X-Anona-Space-Id response headers, which is how you read them on a stream. The user turn and the assistant reply are both stored back into space_id automatically, unless auto_record is false.

Streaming

Send "stream": true and the reply arrives as server-sent events in the standard OpenAI chunk format, terminated by data: [DONE].

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What plan am I on?"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Memory recall happens before the model is called, so injection is unaffected by streaming. The first chunk carries the memories_injected and space_id fields alongside the usual chunk payload, and both are on the response headers from the start. The turn is recorded and billed after the last token, using the token counts from the final chunk. If the connection drops mid-stream, whatever the model already produced is still recorded and still billed, from an estimate of the text that was sent, since the counts travel in a chunk that never arrived. Token counts reach you only if you ask for them, as on OpenAI: set "stream_options": {"include_usage": true} and the stream ends with a usage chunk. Billing does not depend on it.

Errors raised before the first token (an unavailable model, an unreachable provider) come back as a normal JSON error with a real status code. Once the stream has started the status is already sent, so a later failure ends the stream early instead.

Other request shapes

Shape	Endpoint
OpenAI Chat Completions	`/v1/chat/completions` (this page)
OpenAI Responses	`/v1/responses`
Anthropic Messages	`/v1/messages`

All three run the identical memory wrapper and accept the same tunables.

You never supply an LLM key. Anona runs the model for you, model is a hint, and billing is metered in Anona credits rather than by the underlying provider.

API Essentials

Memory (data plane)

LLM Proxy (drop-in)

Account (control plane)

Request

Memory tunables

Space defaults

Response

Streaming

Other request shapes

​Request

​Memory tunables

​Space defaults

​Response

​Streaming

​Other request shapes

Request

Memory tunables

Space defaults

Response

Streaming

Other request shapes