API reference

Create a chat completion

OpenAI-compatible. Routes to an endpoint your guardrails and preferences allow, dispatches on your own provider credential, and fails over to the next candidate before the first byte ships -- walking models[] to exhaustion.

Free models without a key. A free model (GET /v1/models?free=true: every price zero) can be used before you add any provider key: where the platform holds a free-model key for its provider, an organisation with no key of its own for that model is served on it, at $0, with no hold. At most 50 such requests per organisation per UTC day (the operator may set another figure), across every free model and key; past that the attempt is not sent and the request is a 429 with metadata.reason: free_model_daily_limit. Your own key has no such limit, and once you add one for the provider it is used instead. The provider's own free-tier limits still apply, and its errors pass through. Every model with a price is served on your own key only.

With stream: true the response is server-sent events: one data: line per ChatCompletionChunk, SSE comments (lines starting with :) as keepalives, a final chunk carrying usage, then data: [DONE].

Authentication

Inference key (ar-v1-…) · Dashboard session

Parameters

X-Autonomous-Relay-Metadata enum · header

enabled adds agentrouter_metadata: on the final chunk when streaming, and beside error on an error once routing has begun. X-Metadata is accepted too.

X-Session-Id string · header

A sticky-routing key, used when the body has no session_id. The legacy X-AgentRouter-Metadata is accepted too.

X-Anthropic-Beta string · header

Forwarded to Anthropic as anthropic-beta.

HTTP-Referer string · header

Your app's URL, for attribution. The app listing keeps its path; each request row keeps only the scheme and host.

X-Autonomous-Relay-Agent string · header

The agent this request is for: 1 to 64 letters, digits, ., _, : or -, starting with a letter or digit. Recorded on the request, and bound by that agent's budgets (PUT /v1/agents/{agent}/budgets/{interval}) across every key it uses. A malformed value is a 400 before anything is spent. The legacy name X-AgentsRouter-Agent is accepted too.

X-Title string · header

Your app's name. X-App-Title and X-OpenRouter-Title are accepted too.

X-App-Visibility enum · header

hidden keeps the app out of public listings. Read on the app's first request only.

X-App-Categories string · header

Up to two comma-separated categories.

X-Cache enum · header

bypass answers from the provider and stores nothing, on a key with the response cache on.

Request body

model string

A catalog id, author/slug, optionally with a variant (:free, :nitro, :floor, :exacto), or a ~author/family alias, which resolves to the author/family-latest row when the catalog publishes one and otherwise resolves to nothing -- it never picks a model for you by guessing at the name. An id listed in /v1/models always means that listing: some free tiers are catalog rows of their own, named author/slug:free, and a suffix is only split off the id when no such row can serve the request. It always applies as a variant either way. Or @preset/<slug> (@<version> to pin one): your organisation's preset, whose settings fill in whatever this request does not set.

models string[]

A fallback chain, tried in order. At most three are attempted.

messages ChatMessage[]

prompt string

Legacy: sent as a single user message when messages is absent.

stream boolean

Default: false

max_tokens integer

max_completion_tokens integer

temperature number

top_p number

top_k integer

stop string | string[]

seed integer

tools object[]

Client functions, and server tools the gateway runs itself: {"type": "autonomousrelay:datetime", "parameters": {"timezone": "America/Toronto"}}, {"type": "autonomousrelay:experimental__search_models"}, or a registered MCP server's tools: {"type": "autonomousrelay:mcp", "server": "<name>", "allowed_tools": [...]} (§17.7; see POST /v1/mcp-servers), offered to the model as mcp__<server>__<tool> and called by the gateway on the server's credential. An installed marketplace plugin's tools: {"type": "autonomousrelay:plugin", "plugin": "<slug>", "allowed_tools": [...]} (see POST /v1/plugins/{id}/install), offered as plugin__<slug>__<tool> and called on the install's own credential -- {"type": "autonomousrelay:plugin", "plugin": "notion"} offers plugin__notion__search_pages and plugin__notion__read_page; a plugin not installed is a 404, one turned off a 403, one that cannot list its tools a 502. Every connection at once: {"type": "autonomousrelay:connected", "include": [...], "exclude": [...], "writes": [...]} offers the READ tools of every installed plugin and MCP server (at most 10 connections and 128 functions per request), plus only the write tools named exactly in writes -- which need a run_id whose agent has an approval policy, and always wait for a person. A connection that does not work (not connected, expired, turned off, unreachable) is skipped, not an error: the answer comes from the rest, the X-Autonomous-Relay-Connected-Tools response header and agentrouter_metadata.connected_tools say what was used and skipped, and the organisation's alert channels (or its owners, by email) are told once a day per connection. GET /v1/tools/available shows what it would draw on. With "stream": true the loop still runs: its progress arrives as SSE comment lines (: autonomousrelay {"type": "tool.called", ...}, which SDKs ignore), then the answer as ordinary chunks. Their use is reported in usage.server_tool_use. See GET /v1/tools for the catalogue and which are available.

max_tool_calls integer

The most server-tool executions this request may make.

Default: 30

tool_context object

Context for connector tools: a plugin tool whose connector manifest declares a key receives that key's value as _context. A hosted agent's run started by a connector event sets it from the event. Never sent to the model provider.

tool_choice any

none, auto, required, or {"type": "function", "function": {"name": …}}.

service_tier enum

OpenAI's processing tier. flex (Batch rates; OpenAI may refuse it with a 429 when busy, uncharged) and priority / fast (Fast mode, a per-token premium) are sent only to an OpenAI endpoint with a published price for that tier; anywhere else the request is served at standard. Billing follows the tier the provider reports serving at -- a Fast request OpenAI serves at default is billed at default. auto, default and scale are accepted and not forwarded.

One of: auto, default, flex, priority, fast, scale

response_format object

{"type": "json_object"} or {"type": "json_schema", "json_schema": {"name", "schema", "strict"}}. Passed as is on OpenAI-protocol providers; on Gemini it becomes JSON mode with the schema; on Anthropic a json_schema becomes structured outputs, with the bounds Anthropic does not enforce (minimum, maxLength, maxItems, …) left unchecked and additionalProperties: false assumed where unset. A schema Anthropic cannot express (additionalProperties other than false, a recursive or external $ref) is sent there without a format; json_object has no Anthropic counterpart. The response-healing plugin repairs a reply that is still not JSON.

plugins object[]

[{"id": "response-healing"}] repairs a reply that should have been JSON (response_format json_object or json_schema): markdown fences, surrounding text, trailing commas, comments, bare keys, unclosed brackets. The repair is used only if it parses; a reply that already is JSON, or that max_tokens cut short (finish_reason: "length"), is returned as written. Not on streams. When it changed the answer, agentrouter_metadata.pipeline includes response_healing.

{"id": "context-compression"} fits a conversation to the serving endpoint's context window by removing whole messages from the middle out: system and developer messages, the first message and the last always stay, and a tool call goes with its results. The window left for the prompt is the context less max_tokens (a quarter of the window when unset). On by default for endpoints of 8,192 tokens or less; {"id": "context-compression", "enabled": false} turns it off. With it on, Anthropic's 1,000-message limit is met the same way. Never applied to an image-output model. A failover to a larger endpoint sends the conversation whole. When it removed messages, pipeline includes context_compression.

{"id": "file-parser", "pdf": {"engine": "pdf-text" | "native"}} decides how a PDF file part (file_data as a base64 data URL, or a file_id) reaches the model. native sends the file; pdf-text sends its text layer, read on our side, as a text part headed by the filename, page by page (at most 200 pages and 1,000,000 characters per request). Unset, each endpoint decides: the file where the model reads files, its text everywhere else, so PDFs work on any model. mistral-ocr is refused: OCR would send the document to a third party, so a scanned PDF has no text here and should go to a model that reads PDFs. A file that is not a PDF, or is password-protected, is a 400 when an endpoint needs its text. When the model was given text, the answer carries it as message.annotations (on a stream, on the final chunk's delta.annotations) [{"type": "file", "file": {"hash", "name", "content": [{"type": "text", "text"}]}}]; send that assistant message back with the conversation and the annotation is used instead of reading the file again. pipeline includes file_parser. Nothing is stored.

{"id": "auto-router", "cost_tier": "low" | "medium" | "high" | "xhigh" | "max", "allowed_models": [...], "excluded_models": [...]} configures "model": "autonomousrelay/auto": a paid model you can route to that fits the request (text out, image input when an image is sent, a window that holds it), from the tier by output price per million tokens (low to $2, the default; medium to $10; high to $30; xhigh to $60; max above), the most expensive first, then the newest; two fallbacks from the same tier; the nearest cheaper tier when the one asked for has nothing, then the nearest dearer one. Patterns take * for any run of characters. The prompt is not read and nothing is kept, so the same request picks the same model.

{"id": "moderation", "input": true, "output": false} checks the input (default) and, with output: true, the answer, using OpenAI's omni-moderation-latest on the organisation's own OpenAI BYOK key (a 400 without one). The input is checked before any provider sees it and before anything is held; a flag is a 403 with error_type moderation_flagged and metadata {reasons, flagged_input, provider_name, model_slug}. A flagged answer is withheld, and the request is billed because the model ran. Output moderation is refused on streams. If moderation cannot run, the request is refused (503), never sent unchecked. pipeline includes moderation.

{"id": "web", "engine": "native", "max_uses": 3, "allowed_domains": [...] | "excluded_domains": [...]} lets the model search the web with its provider's own search: Anthropic's web search tool on Claude models, Google Search grounding on Gemini 3 models, and OpenAI's and xAI's web_search tool (the request is run on their Responses API) on GPT-5 and later and Grok 4 models. Gemini 2.5 is not served: it is priced per grounded prompt. Only those endpoints are candidates; with none, a 404. max_uses (1-20) applies on Claude; the domain lists on Claude, OpenAI and xAI (at most 5 on xAI), so a request with domains never goes to Gemini. Each search is metered as a web_search line at the provider's published price per 1,000: $10 Anthropic, $14 Gemini (before Google's free monthly allowance), $10 OpenAI, $5 xAI. The pages the search cited come back as url_citation annotations on the message (on a stream, in delta.annotations as they arrive), with start_index/end_index where the provider gives character offsets. Outside engines (Exa and the like) are refused: they would be a new recipient of your queries. Other plugin ids are ignored.

reasoning object

{ effort: minimal|low|medium|high|xhigh|max } or { max_tokens: n }. On Anthropic's current models (Fable, Opus 4.6 and later, Sonnet 4.6 and later) this becomes adaptive thinking with effort as the depth (minimal is low; xhigh is high on the 4.6 models); a max_tokens budget turns thinking on at the model's default depth, since those models size their thinking inside the request's own max_tokens. On older Claude models it is extended thinking with that budget (floor 1024). Either way the thinking text is returned as message.reasoning (or delta.reasoning when streaming). temperature, top_p and top_k are dropped alongside thinking, and on Fable, Opus 4.7 and later and Sonnet 5 always, because Anthropic refuses them there.

provider ProviderPreferences

Routing preferences (§6.2). Preferences reorder; constraints reject. Guardrails outrank everything here.

session_id string

Keeps a conversation on one endpoint so its prompt cache stays warm (§6.6).

prompt_cache_key string

Used as the sticky-routing key when there is no session_id.

routing_stability enum

Defaults to sticky when the request has a pin key, adaptive otherwise (§17.2).

One of: adaptive, sticky, pinned

Responses

Create a message (Anthropic's Messages API)

Anthropic-compatible: the Anthropic SDKs work with their base URL set to this host. The request is translated to a chat completion and served by the same pipeline, so every gate, routing rule, preset, server tool and file applies, and any model answers it, not only Claude. The answer comes back as a message, or with stream: true as Anthropic's events (message_start, content_block_*, message_delta, message_stop, ping).

The key goes in x-api-key (as the Anthropic SDK sends it) or Authorization: Bearer. anthropic-version is accepted and ignored; anthropic-beta is forwarded to Anthropic. A Claude name such as claude-opus-4-8 or claude-opus-4-8-20260101 means anthropic/claude-opus-4.8; any other model is named by its catalogue id. models (or fallbacks: [{"model": ...}], at most three), provider, session_id and run_id work as on chat completions.

Not taken: Anthropic's own server tools (declare autonomousrelay:* tools instead -- autonomousrelay:plugin, autonomousrelay:mcp and autonomousrelay:connected included, as on chat completions), images inside a tool_result, a document by URL, and cache_control (ignored). Thinking blocks sent back are dropped; tool-use arguments stream as one input_json_delta per call, once the model has finished.

Authentication

Inference key (ar-v1-…) · Dashboard session

Parameters

x-api-key string · header

An inference key, as the Anthropic SDK sends it. Used when there is no Authorization header.

anthropic-version string · header

Accepted and ignored.

anthropic-beta string · header

Forwarded to Anthropic.

X-Autonomous-Relay-Agent string · header

The agent this request is for, as on chat completions.

Request body

model stringrequired

A catalogue id, or a Claude name (claude-opus-4-8).

max_tokens integerrequired

messages object[]required

system string | object[]

stream boolean

temperature number

top_p number

top_k integer

stop_sequences string[]

tools object[]

tool_choice object

thinking object

metadata object

fallbacks object[]

Models tried in order after model.

Responses

Create a response (OpenAI's Responses API)

OpenAI-compatible Responses API. The request is translated to a chat completion and served by the same pipeline, so every gate, routing rule, preset, server tool and file applies, and any model answers it. The answer is a response; with stream: true, the Responses events (response.created, response.output_item.*, response.output_text.delta, response.function_call_arguments.*, response.completed or response.incomplete), each with a sequence_number.

Stateless. Nothing is stored, so store: true, previous_response_id, conversation and background are refused with a 400 rather than ignored; send the whole conversation as input. store: false is accepted.

Input items: messages (input_text, input_image by URL or file_id, input_file by file_data or file_id), function_call and function_call_output; reasoning items are dropped. Tools: function, and our autonomousrelay:* declarations -- server tools, autonomousrelay:plugin, autonomousrelay:mcp and autonomousrelay:connected, as on chat completions; OpenAI's built-in tools are refused. text.format (json_schema, json_object), reasoning.effort, max_output_tokens, tool_choice and parallel_tool_calls map to their chat equivalents; models and provider work as on chat completions. Function-call arguments stream as one delta per call, once the model has finished.

Authentication

Inference key (ar-v1-…) · Dashboard session

Parameters

X-Autonomous-Relay-Agent string · header

The agent this request is for, as on chat completions.

Request body

model string

A catalogue id.

input string | object[]required

instructions string

Sent as a system message ahead of the input.

max_output_tokens integer

stream boolean

temperature number

top_p number

user string

tools object[]

tool_choice enum | object

parallel_tool_calls boolean

text object

reasoning object

store boolean

Only false (or absent): nothing is stored.

models string[]

provider object

Routing preferences, as on chat completions.

Responses

Create a text completion (legacy)

OpenAI's legacy text completion, for clients that still call it. The prompt is sent as one user message and served by the chat pipeline -- every gate, routing rule and preset applies -- and the answer's text comes back as choices[0].text; with stream: true, as text_completion chunks ending in data: [DONE].

One prompt per request: a list of more than one is refused, since each would be its own routed and billed request. The catalogue's models are chat models, so what only a true completion model can honour is refused rather than dropped: suffix, echo, best_of and n above 1, logprobs (chat completions return them), and token-id prompts.

Authentication

Inference key (ar-v1-…) · Dashboard session

Parameters

X-Autonomous-Relay-Agent string · header

The agent this request is for, as on chat completions.

Request body

model string

A catalogue id.

prompt string | string[]required

max_tokens integer

stream boolean

temperature number

top_p number

stop string | string[]

seed integer

frequency_penalty number

presence_penalty number

user string

models string[]

provider object

Routing preferences, as on chat completions.

Responses

Create embeddings

OpenAI-compatible. Routed like a chat completion -- model, an optional models[] fallback list and provider preferences -- through the same gates in the same order: auth, rate limit, every budget, the content filters (a redacted input is what is embedded), your guardrails and privacy policy, a hold, and failover before anything is returned. Billed on the provider's prompt-token count.

Only models whose catalogue modality outputs embeddings are candidates; naming a chat model is a 400 saying so. input is a string or up to 2,048 strings; token arrays are refused, since the router cannot know which tokeniser the endpoint it picks will read them with.

Authentication

Inference key (ar-v1-…) · Dashboard session

Parameters

X-Autonomous-Relay-Agent string · header

The agent this request is for; bound by that agent's budgets, as on chat completions.

HTTP-Referer string · header

Your app's URL, for attribution.

X-Title string · header

Your app's name.

Request body

model string

An embedding model id from /v1/models.

models string[]

Fallbacks, tried in order after model.

input string | string[]required

encoding_format enum

base64 returns each vector as little-endian float32s, base64-encoded.

One of: float, base64

dimensions integer

For models that can shorten their output; others refuse it upstream.

provider object

Routing preferences, as on chat completions.

Responses

Text to speech

OpenAI's request; the answer is the audio itself, in response_format (mp3 by default). Routed like embeddings -- model, models and provider as on chat completions, the same budgets, content filters (a redacted input is what is spoken) and guardrails. Only text-to-speech models with a published price are candidates, and the request is billed per character of input, at that price. voice is passed as given: each model has its own voices (af_bella on Kokoro, Ashley on Inworld, a free-text description on the VoiceDesign models), and its default when omitted.

The body is audio, so the request id travels in the x-autonomous-relay-generation-id header; GET /v1/generation?id= reads its cost.

Authentication

Inference key (ar-v1-…) · Dashboard session

Parameters

X-Autonomous-Relay-Agent string · header

The agent this request is for, as on chat completions.

Request body

model string

A text-to-speech model id from /v1/models.

models string[]

Fallbacks, tried in order after model.

input stringrequired

voice string

The model's own voice name or, on a VoiceDesign model, a description.

response_format enum

One of: mp3, opus, flac, wav, pcm

speed number

provider object

Routing preferences, as on chat completions.

Responses

Speech to text

OpenAI's multipart request: file (flac, mp3, mp4, mpeg, mpga, m4a, ogg, opus, wav or webm, at most 25 MB) and model, with optional language (ISO-639-1), prompt and temperature. Routed like embeddings, through the same budgets and guardrails; the content filters read prompt. Only speech-to-text models with a published price are candidates, and the request is billed per second of audio, as the provider measured it.

response_format: json ({text, usage}), verbose_json (adds language, duration, segments, words), or text (the transcript as plain text). usage is {type: "duration", seconds, cost, ...}. The request id is also in the x-autonomous-relay-generation-id header.

Authentication

Inference key (ar-v1-…) · Dashboard session

Parameters

X-Autonomous-Relay-Agent string · header

The agent this request is for, as on chat completions.

Responses

Generate images

OpenAI's request and response, routed like embeddings: model, models and provider as on chat completions, through the same budgets, content filters (a redacted prompt is what is drawn) and guardrails. Only text-to-image models with a published output price are candidates; a model whose price cannot be computed from the request (per token, tiered by megapixel) is not served, and the 404 names published_price.

Billed at that price, per image or per megapixel of size ((width/1024) x (height/1024)), for the images actually returned; GET /v1/models/{author}/{slug}/endpoints shows each endpoint's image_output price and its image_output_unit. Images come back as b64_json only: nothing is hosted, so there is no URL to give. Up to 4 images; each side of size from 256 to 2048 (models may accept less).

Authentication

Inference key (ar-v1-…) · Dashboard session

Parameters

X-Autonomous-Relay-Agent string · header

The agent this request is for, as on chat completions.

Request body

model string

A text-to-image model id from /v1/models.

models string[]

Fallbacks, tried in order after model.

prompt stringrequired

n integer

size string

WIDTHxHEIGHT or auto (1024x1024).

response_format enum

One of: b64_json

provider object

Routing preferences, as on chat completions.

Responses

Rerank documents against a query

Each document's relevance to the query, most relevant first -- the request and response shape Cohere and Jina share. Routed and billed like embeddings: model, models and provider as on chat completions, the same budgets, content filters (a redacted query or document is what is scored) and guardrails, and the provider's input-token count as the bill. Only reranker models are candidates; another kind is a 400 that says so.

Served today by DeepInfra's Qwen3 rerankers. Up to 1,000 documents, each a string or {"text": ...}. instruction steers the task on models that take one.

Authentication

Inference key (ar-v1-…) · Dashboard session

Parameters

X-Autonomous-Relay-Agent string · header

The agent this request is for, as on chat completions.

Request body

model string

A reranker model id from /v1/models.

models string[]

Fallbacks, tried in order after model.

query stringrequired

documents string | object[]required

top_n integer

How many results to return; all by default.

return_documents boolean

Include each result's text.

instruction string

Steers the reranking task, on models that take one.

provider object

Routing preferences, as on chat completions.

Responses

Preview how a request would route

Answers "why would I get that model, from that provider?" before the money is spent. Router metadata answers it afterwards; this runs the same gates, the same filters and the same ranking against a request that is never dispatched.

It mirrors POST /v1/chat/completions gate for gate and in order: the same auth, the same budget checks in the same precedence, the same content filter applied before routing, the same per-model candidate load, filter and rank, the same fallback depth, and the same sticky hoist.

It has no side effects. No ledger hold, no run reservation, no request row, no sticky pin written, no provider contacted. Rate limited in its own bucket, so debugging a routing problem never eats the quota needed to fix it.

Read ordering before trusting cascade as a prediction: the default ranking is a weighted random draw, and sampled means a real request draws again.

Authentication

Inference key (ar-v1-…) · Dashboard session

Parameters

X-Session-Id string · header

A sticky-routing key, used when the body has no session_id.

Request body

model string

The model to route, exactly as /v1/chat/completions takes it -- :free, :nitro, :floor, :exacto suffixes and ~author/family-latest aliases included.

models string[]

A fallback chain, previewed in order. Walked to the same depth a real request would walk it.

provider ProviderPreferences

Routing preferences (§6.2). Preferences reorder; constraints reject. Guardrails outrank everything here.

tools object[]

Only the COUNT matters here: a non-empty list makes tools a required parameter, which is a hard filter under require_parameters.

messages ChatMessage[]

Optional. Supplied only so content filters and the sticky prefix hash can be evaluated; nothing is sent to a provider. Omit them and content_filter comes back null rather than a fabricated allow.

session_id string

Sticky-routing key, as on the chat route.

prompt_cache_key string

routing_stability enum

One of: adaptive, sticky, pinned

routing_seed string

Seeds the weighted draw so a preview is reproducible and quotable in a bug report. Named routing_seed, not seed: the latter is OpenAI's sampling seed on the chat route, and one name for two knobs on sibling endpoints is a trap.

Responses

Run an evaluation

A dataset, a task and up to 8 models (at most 400 cells), producing a scored comparison with per-cell cost and latency (§17.6). Every cell is a real POST /v1/chat/completions on your credentials -- the same rate limit, budgets, guardrails, routing and billing as if you had sent it, and a request row of its own -- so an evaluation is the same account, keys and routing you would run in production. A cell your rate limit refuses waits for the window and is tried again.

The answer streams as NDJSON: one {"type": "cell", ...} line per cell as it completes (four at a time), then {"type": "summary", ...} per model. Nothing is stored: the dataset arrives with the request, the outputs go back in the stream, and there is no run to fetch later.

Scorers: none, exact and contains (against each item's expected; case and spacing ignored unless case_sensitive), and json (the answer parses as JSON, code fences allowed). There is no regex scorer: a caller's pattern run over a model's answer can stall a backtracking engine, so pattern scoring waits for a linear-time one.

Authentication

Inference key (ar-v1-…) · Dashboard session

Request body

models string[]required

dataset object[]required

task object

scorer object

Responses

List models

Public. Rate limited per client address: 120 a minute, 20,000 a day.

Authentication

None: this endpoint is public.

Parameters

limit integer · query

Page size.

offset integer · query

Rows to skip.

q string · query

A case-insensitive substring of the name or id.

model_authors string · query

Comma-separated authors, e.g. anthropic,openai.

context integer · query

Minimum context length, in tokens.

output_modalities string · query

Comma-separated; the model produces ANY of them: text, image, audio, video, embedding, rerank. Other values are ignored.

input_modalities string · query

Comma-separated; the model accepts ALL of them: text, image, file, audio, video. Other values are ignored.

max_prompt_price number · query

The most the cheapest endpoint may charge for input, in USD per million tokens. total_count counts after it.

free enum · query

true: only models whose every price is zero (the catalogue's is_free).

sort enum · query

Anything else sorts by id.

Responses

Get a model

Public and rate limited, as the list is. pricing is absent here; the endpoints route has every endpoint's prices.

Authentication

None: this endpoint is public.

Parameters

author string · pathrequired

e.g. anthropic.

slug string · pathrequired

e.g. claude-sonnet-5.

Responses

List a model's endpoints

Public and rate limited. Every provider serving the model, with its price, measured uptime and latency, and tool-call reliability.

Authentication

None: this endpoint is public.

Parameters

author string · pathrequired

e.g. anthropic.

slug string · pathrequired

e.g. claude-sonnet-5.

Responses

A model's availability per provider over the last week

Public and rate limited. For each provider that served the model in the last 7 UTC days, one figure per day: the share of dispatches it answered without failing on its side (a 5xx, unreachable, a broken stream). A caller's own errors -- a bad request, their key's rate limit -- do not count against it. A day with fewer than min_dispatches dispatches, or from fewer than min_organizations organisations, is null: not measured.

Authentication

None: this endpoint is public.

Parameters

author string · pathrequired

e.g. anthropic.

slug string · pathrequired

e.g. claude-sonnet-5.

Responses

How a model's input and output prices have changed, per provider

Public and rate limited. One series per provider and SKU (prompt, completion), oldest first: each point is a USD-per-token price and the time it took effect (from) and was replaced (to, null for the current price). Prices are effective-dated, so every change since the catalogue began recording them is here; an unchanged price written again is one point.

Authentication

None: this endpoint is public.

Parameters

author string · pathrequired

e.g. anthropic.

slug string · pathrequired

e.g. claude-sonnet-5.

Responses

Everything the home page shows

Public and rate limited, cached 30 seconds. The first 60 models, the providers, the purchase fee schedule, and the endpoints of the first six models -- each exactly as its own operation returns it. A part that could not be read is null; an endpoints read that failed is left out.

Authentication

None: this endpoint is public.

Responses

Whether free models work without a provider key here

Public and rate limited. Whether this deployment serves the catalogue's free models without a provider key of your own, on its own key: available, the daily request limit per organisation, and the models it applies to. available is false, and models empty, when it does not -- then every model, free ones included, runs on your own provider key.

Authentication

None: this endpoint is public.

Responses

Models added and prices changed in the catalogue lately

Public and rate limited. Ready models added in the last days days (default 30, at most 90), newest first, and every input (prompt) or output (completion) per-token price that changed on an endpoint in that window -- rises and drops -- with the price before and after, in USD per token. A change is the importer replacing an endpoint's price: the same definition the price_drop alert uses.

Authentication

None: this endpoint is public.

Parameters

days integer · query

Responses

Ask to be emailed when a model's price drops

Public; no account. Double opt-in: the address is sent one confirmation email, and nothing else until its link is clicked; an unconfirmed request is deleted after 7 days. Once confirmed, an email is sent when the model's input or output price drops on any provider -- once per drop, several models' drops in one email -- each with a one-click unsubscribe link. The answer is the same 202 whether or not an email was sent (an address already subscribed, over its limit of 20 models or of requests per day), so it says nothing about any address. Rate limited per client address and per email address.

Authentication

None: this endpoint is public.

Parameters

author string · pathrequired

e.g. anthropic.

slug string · pathrequired

e.g. claude-sonnet-5.

Request body

email stringrequired

The address to email.

lang enum

The language of the emails. Default en.

One of: en, fr

Responses

Whether price-drop emails can be requested here

Public. available is false on a deployment with no email configured, where subscribing answers 503.

Authentication

None: this endpoint is public.

Responses

Confirm a price-drop email subscription

The link in the confirmation email. Valid for 7 days, and idempotent while valid. Redirects to the model's page with price_alert=confirmed, or to /models?price_alert=invalid for an unknown or expired link.

Authentication

The token in the link we sent (query parameter token)

Parameters

token string · queryrequired

From the confirmation email.

Responses

Unsubscribe from price-drop emails (link)

The link in every price-alert email; no sign-in. Deletes the subscription -- or, for an email's "stop all" link, every subscription of the address -- and the address once it has none. Redirects to the model's page (or /models) with price_alert=unsubscribed, or price_alert=invalid for a link already used or unknown. Never refused by region: it only deletes.

Authentication

The token in the link we sent (query parameter token)

Parameters

token string · queryrequired

From the email.

Responses

Unsubscribe from price-drop emails (one-click, RFC 8058)

What a mail client POSTs to the List-Unsubscribe URL, with the body List-Unsubscribe=One-Click (form-encoded; ignored). The same deletion as the link.

Authentication

The token in the link we sent (query parameter token)

Parameters

token string · queryrequired

From the email's List-Unsubscribe header.

Responses

List providers

Public and rate limited.

Authentication

None: this endpoint is public.

Responses

Model rankings by tokens processed

Public and rate limited. Tokens processed per model -- prompt, completion, reasoning and cache, by the model that served them -- over day (since 00:00 UTC), week (7 days), month (30 days), or trending (the largest increase, this week against the week before). A measure of use, not of quality. Aggregated only, and a model is listed only once at least min_organizations (3) distinct organisations used it in the period; in trending, last week's figure is null when last week was below that threshold too. Recomputed at most every ten minutes.

Authentication

None: this endpoint is public.

Parameters

range enum · query

day, week (default), month or trending.

Responses

The apps directory: apps by tokens processed

Public and rate limited. Apps are what requests name in HTTP-Referer; each is listed by its domain only (paths merged, www. dropped) -- never the X-Title or categories a caller sends, which anyone can set. A domain is listed once it has at least min_requests (100) completed requests in the period; apps whose first request sent X-App-Visibility: hidden never are, nor are local or private hosts. week (7 days, the default) or month (30). Recomputed at most every ten minutes.

Authentication

None: this endpoint is public.

Parameters

range enum · query

week (default) or month.

Responses

Get a provider and the models it serves

Public and rate limited. The directory row, and every ready model the provider has an active endpoint for, with the endpoint's prompt and completion price, context, quantization, region and published uptime -- the same figures as the model's own endpoints list.

Authentication

None: this endpoint is public.

Parameters

slug string · pathrequired

e.g. anthropic.

Responses

Inspect the calling key

For an inference key: its limit, what remains of it, and what it has spent plus what its in-flight requests have reserved.

Authentication

Inference key (ar-v1-…)

Responses

List keys

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

include_disabled boolean · query

Include revoked keys.

Responses

Create a key

The plaintext key is in this response and never again: only a salted hash is stored.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Request body

name string

limit number

A spend limit in USD. Omit for none.

limit_reset string | null

The window the ceiling covers, in UTC calendar terms. Null means lifetime: the ceiling never resets.

One of: daily, weekly, monthly, lifetime, null

limit_mode enum

hard (the default) refuses a request once the key is at or past its ceiling, with 403 budget_exceeded. soft serves it and adds an x-autonomous-relay-limit-warning header carrying the same sentence.

One of: hard, soft

Default: "hard"

include_byok_in_limit boolean

Count spend on your own provider credential toward the ceiling, at list price. On by default: every model is BYOK-only, so without it the ceiling would count nothing.

Default: true

workspace_id string

Put the key in this workspace (client). Omit for the caller's own workspace. Another organisation's id is a 404.

class enum

One of: inference, management

Default: "inference"

expires_at string

When the key stops authenticating (401 key_expired). With a time zone, in the future, within ten years. Omit for a key that does not expire.

rpm_limit integer | null

The key's own requests per minute, counted in calendar minutes on top of the account quota; null for none. Inference keys only.

tpm_limit integer | null

The key's own tokens (prompt + completion) per minute; null for none. Requests are refused once the minute's count reaches it, and a request's tokens are counted when it finishes, so requests in flight can overshoot it. Inference keys only.

cache_enabled boolean

Answer this key's repeated non-streaming chat completions from the response cache, at no cost. Inference keys only. An identical request gets the same answer, whatever its temperature.

Default: false

cache_ttl_seconds integer

How long an answer stays cached.

Default: 3600

Responses

Change a key's spend limit, rates or expiry, or pause and resume it

Changes the ceiling, its window, its mode, whether BYOK spend counts, the key's requests and tokens per minute, the workspace, a pause or the expiry. Only these: a key's class, name and secret are fixed at creation. At least one field is required. The new ceiling applies at once on the instance serving this call and within the auth cache's 10-second TTL everywhere else.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

hash string · pathrequired

The key's hash, from the list.

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Request body

limit number | null

The new ceiling in USD; null removes it.

limit_reset string | null

The window the ceiling covers, in UTC calendar terms. Null means lifetime: the ceiling never resets.

One of: daily, weekly, monthly, lifetime, null

limit_mode enum

hard (the default) refuses a request once the key is at or past its ceiling, with 403 budget_exceeded. soft serves it and adds an x-autonomous-relay-limit-warning header carrying the same sentence.

One of: hard, soft

include_byok_in_limit boolean

workspace_id string

Move the key to this workspace of the same organisation.

paused boolean

false resumes a key paused by a runaway flag or by hand; true pauses it by hand. A paused key answers 403 key_paused.

expires_at string | null

Set or move the expiry (with a time zone, in the future, within ten years); null removes it. Refused on the calling key and on a dashboard sign-in key, which would lock their holder out.

rpm_limit integer | null

The key's own requests per minute, counted in calendar minutes on top of the account quota; null for none. Inference keys only.

tpm_limit integer | null

The key's own tokens (prompt + completion) per minute; null for none. Requests are refused once the minute's count reaches it, and a request's tokens are counted when it finishes, so requests in flight can overshoot it. Inference keys only.

cache_enabled boolean

Turn the response cache on or off for this key. Inference keys only. Turning it off stops lookups at once; entries already stored expire on their TTL, or go now with DELETE /v1/cache.

cache_ttl_seconds integer

How long answers stored from now on stay cached.

Responses

Revoke a key

Disables the key and ends every dashboard session it created.

Propagation is bounded at 10 seconds (§17.4: "publish that TTL"). The instance serving this call stops accepting the key immediately; any other instance stops within the auth cache's TTL. That cache serves no stale window — past ten seconds the entry is refused and the caller waits on the database — so ten seconds is the real bound, not the point at which a refresh merely begins.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

hash string · pathrequired

The key's hash, from the list.

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Responses

Describe the response cache

The organisation's live response-cache entries and their size. The cache is turned on per inference key (cache_enabled); available is false while the deployment does not run it, in which case nothing is cached whatever a key says.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Responses

Purge the response cache

Deletes every cached answer of the organisation at once; the next request of each kind is a miss. Owner and Admin only (org:write).

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Responses

List recent requests

Newest first, keyset-paginated. Cost is summed per row, over the window.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

limit integer · query

Page size.

days integer · query

The window, ending now.

cursor string · query

The next_cursor of the previous page. Opaque; do not parse it.

model string · query

The model that served.

provider string · query

A provider slug.

workspace string · query

One client: a workspace id. A malformed id is a 400.

agent string · query

One agent: the X-Autonomous-Relay-Agent value.

tag string · query

Requests a classifier tagged with this.

status string · query

The request status, e.g. complete.

byok boolean · query

BYOK requests only, or none.

app string · query

An app_id.

Responses

Export a month of requests as CSV

One row per request in a UTC calendar month, for the account or one client (workspace). Columns: created_at, request_id, client, key, requested_model, served_model, provider, status, error_code, byok, prompt_tokens, completion_tokens, billed_usd (what this account was charged), list_price_usd (the tokens at catalogue list price: under BYOK, the number a client is re-billed on and the one budgets measure) and agent. Text cells that a spreadsheet would run as a formula are prefixed with a single quote. Capped at 200,000 rows, after which a # truncated line ends the file. At most 6 exports a minute per key.

Needs the Pro ($29/month) plan or above.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

month string · query

YYYY-MM, UTC. Default: the current month.

workspace string · query

One client: a workspace id. Another organisation's is a 404.

Responses

Query usage analytics

Aggregates over your requests and what they cost -- the rows Activity and Logs read, so the numbers agree. Name at least one metric, up to two dimensions to group by, up to twenty filters on dimensions, a time range (default the last 7 days, at most 92) and a granularity for a series. group_limit keeps the top groups by the first metric over the whole range, so a series has the same groups in every bucket. GET /v1/analytics/meta lists every metric and dimension. A seat limited to some workspaces queries those alone.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Request body

metrics string[]required

e.g. requests, spend_usd, total_tokens, error_rate, avg_ttft_ms.

dimensions string[]

e.g. model, provider, api_key, workspace, agent.

filters object[]

time_range object

granularity enum

One of: none, hour, day, week, month

Default: "none"

limit integer

Default: 1000

group_limit integer

order_by object

Responses

List analytics metrics and dimensions

Every metric, dimension, filter operator and granularity POST /v1/analytics/query accepts, and its limits.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Responses

List analytics metrics and dimensions (alias)

The same as GET /v1/analytics/meta, under the name the design requirements use.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Responses

Scrape usage as Prometheus metrics

The caller's organisation in the Prometheus text exposition format (version 0.0.4), for a Prometheus scrape_config with the management key as bearer_token. Counters count finished requests since the start of the current UTC month and reset to zero at each month boundary, which rate() and increase() treat as an ordinary counter reset; autonomousrelay_counters_since_timestamp_seconds says when. Families: autonomousrelay_requests_total{model,provider,status}, autonomousrelay_tokens_total{model,provider,type} (type is prompt or completion), autonomousrelay_spend_usd_total{model,provider} (USD billed), the autonomousrelay_request_duration_seconds{model,provider} histogram, and the autonomousrelay_active_keys{class} gauge. The 25 models with the most requests keep their own model label; the rest are summed as other. A seat limited to some workspaces sees those alone. Computed at most every 15 seconds per organisation; a faster scrape reads the same numbers.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Responses

Get activity totals

The KPI cards (§14.9), with the prior period of equal length beside them and a daily series for the sparklines. Both periods are read in one pass, so they cannot disagree about where "now" was.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

days integer · query

The window, ending now. The prior period is the same length again.

workspace string · query

One client: a workspace id. A malformed id is a 400.

Responses

Get one request

Everything recorded about one request (§14.10): the list row, plus the key that made it, its session and run, the usage lines it was billed on, and every dispatch to a provider in order. Metadata only -- stored content is GET /v1/generation/{id}/content. Another organisation's id is a 404.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

id string · pathrequired

The request id (gen-…).

Responses

List upstream provider requests

One row per dispatch to a provider, newest first and keyset-paginated. A request that failed over twice appears three times -- filter by request to see a single generation's attempts in order.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

limit integer · query

Page size.

days integer · query

The window, ending now.

cursor string · query

The next_cursor of the previous page. Opaque; do not parse it.

workspace string · query

One client: a workspace id. The dispatches made for its requests. A malformed id is a 400.

request string · query

A generation id: every dispatch made for it.

provider string · query

A provider slug.

status enum · query

Whether the dispatch committed.

Responses

List conversations

Generations grouped by session_id, most recently active first. Only requests that carried one are included.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

limit integer · query

Page size.

days integer · query

The window, ending now.

cursor string · query

The next_cursor of the previous page. Opaque; do not parse it.

workspace string · query

One client: a workspace id. A malformed id is a 400.

Responses

Get one request's record

Which endpoint served it, at which price version, and what each SKU cost -- enough to recompute the charge.

Not the content. Prompts and completions are stored only when your organisation has enabled input/output logging (§13.1), which is off by default and never retroactive; when it is on, the content is read from GET /v1/generation/{id}/content, not from here.

Authentication

Inference key (ar-v1-…)

Parameters

id string · queryrequired

The id of a chat completion.

Responses

Get one generation's stored prompt and completion

§13.1. Returns content only if your organisation had input/output logging enabled when the generation was made.

Stored encrypted (AES-256-GCM, data key wrapped by Cloud KMS) in a table separate from request metadata, under an AAD bound to your organisation — a credential ciphertext cannot be read here and content cannot be read from the credential path. Deleted automatically past your configured retention.

This is the only read path for stored content, and it is yours. §13.1 forbids using it for training or analytics, and there is no internal reader.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

id string · pathrequired

The generation id (gen-…).

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Responses

Read a generation's scores

Every score your organisation's keys attached to the generation, oldest first; an empty list when there are none. Another organisation's id is a 404.

Authentication

Inference key (ar-v1-…)

Parameters

id string · queryrequired

The generation id (gen-…).

Responses

Score a generation

Attach a score to a request your organisation made, so you can see which models your users rate well. value is a number from -1 to 1 -- thumbs down -1, thumbs up 1, a finer rating mapped into the range. label is an optional slug (helpful, wrong_answer).

One score per generation per key: posting again from the same key replaces it. Any inference key of the organisation that made the request may score it, as any may read it with GET /v1/generation; another organisation's id is a 404.

No free text. A comment is refused with a 400: a comment is content an end user typed, and the gateway stores no content.

Authentication

Inference key (ar-v1-…)

Request body

id stringrequired

The generation id (gen-…).

value numberrequired

label string | null

Responses

Feedback by model

The average score and the number of scores, by the model that served the request, over requests made in the last days days (default 30, at most 90). Most-scored first, at most 100 models. A workspace-limited person sees their workspaces' requests only.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

days integer · query

The window, ending now, by when the request was made.

Responses

Get the balance

Held credits are reserved by requests in flight and are shown apart from the available balance.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Responses

Get the purchase fee schedule

Public. While nothing a credit can buy exists (BYOK-only), purchasable is false and the fee is reported as 0.

Authentication

None: this endpoint is public.

Responses

List purchases

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

limit integer · query

Page size.

cursor string · query

The next_cursor of the previous page. Opaque; do not parse it.

Responses

Get a purchase's invoice or receipt

Resolved from Stripe on demand; only the checkout session id is stored.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

id string · pathrequired

A purchase id.

Responses

Start a credit purchase

Returns a Stripe Checkout URL. Refused with 409 while credits cannot be spent (BYOK-only, zero fee) -- checked before the body is read.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Request body

amount numberrequired

USD.

Responses

Receive a Stripe event

For Stripe, not for you. Credits on checkout.session.completed and checkout.session.async_payment_succeeded only when payment_status is paid, once per session; logs async_payment_failed; acknowledges everything else with 200.

Authentication

Stripe signature

Responses

The organisation's plan

trial (Team's features) for 14 days from creation; then the paid plan while its subscription is active, trialing or past_due (Stripe retrying a renewal): pro ($29/month: guardrails, usage alerts, exports, presets, classifiers), team ($99: Pro plus members, more workspaces and client reports), business ($399: Team plus SSO and SCIM), or enterprise (an invoiced annual contract, set up per customer in Stripe with tier: enterprise in the subscription metadata); limited otherwise. Each plan includes the ones before it. A feature the plan does not include answers 402 subscription_required when created or changed, naming the plan it needs; what was set up keeps working. Readable by every role.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Responses

Subscribe to a plan

Returns a Stripe Checkout URL for the plan named in plan -- pro ($29), team ($99, the default) or business ($399) a month, per organisation, card only. The plan changes when Stripe's webhook confirms the payment, not when this URL is created. Owner, Admin or Finance.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Request body

plan enum

Defaults to team.

One of: pro, team, business

Responses

Change plan

Moves a live Pro, Team or Business subscription to another of the three. The new price is prorated on the next invoice. Answers 202: the plan changes when Stripe's customer.subscription.updated arrives, usually within seconds. Enterprise is set by contract and is not changed here. Owner, Admin or Finance.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Request body

plan enumrequired

One of: pro, team, business

Responses

Open the billing portal

Returns a Stripe billing portal URL: the card, invoices, and cancelling. Owner, Admin or Finance.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Responses

List provider credentials

Keys are never returned, by this or any route -- only key_hint.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Responses

Add a provider credential

Encrypted with a per-credential key before it is stored. Nothing routes until you have one for the provider that serves your model.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Request body

provider stringrequired

A provider slug with an adapter, e.g. anthropic.

api_key stringrequired

name string

tier enum

One of: prioritized, fallback

priority integer

fallback_policy enum

One of: platform, none_for_models, none_for_provider

model_filter object

allowed_models string[] | null

Model ids or * patterns, ANDed with model_filter.

allowed_api_key_hashes string[] | null

Only these API keys (their hash, as GET /v1/keys lists it) may use the credential.

allowed_user_ids string[] | null

Only keys these members are behind -- created, or signed in with -- may use the credential. A key no person is behind is outside the list.

Responses

Enable, disable or scope a provider credential

disabled and the three scope fields can change; a field left out is unchanged, null makes it unrestricted. To change the key, add a new credential and delete this one.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

id string · pathrequired

A credential id.

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Request body

disabled boolean

allowed_models string[] | null

Model ids or * patterns, ANDed with model_filter.

allowed_api_key_hashes string[] | null

Only these API keys (their hash, as GET /v1/keys lists it) may use the credential.

allowed_user_ids string[] | null

Only keys these members are behind -- created, or signed in with -- may use the credential. A key no person is behind is outside the list.

Responses

Delete a provider credential

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

id string · pathrequired

A credential id.

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Responses

List usage-alert channels

Where the organisation is told that a key crossed a share of its spend ceiling. email_available says whether this deployment can send email. A webhook's signing secret is never returned here: only once, when the channel is created.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Responses

Add a usage-alert channel

A key crossing any of thresholds (percent of its ceiling, default 50, 80 and 100), or an agent crossing them on one of its budgets (agent_limit.threshold), is announced once per threshold per ceiling window, on every channel that lists that threshold; a key that jumps several thresholds in one request is announced once, at the highest. A webhook target must be a public https URL on the default port; a slack target must be a https://hooks.slack.com/... incoming-webhook URL; email needs the deployment to be configured for it. Webhook deliveries are JSON, signed in x-autonomous-relay-signature: t=<unix>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<raw body> with the channel's signing_secret. At most 20 channels per organisation.

Needs the Pro ($29/month) plan or above.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Request body

kind enumrequired

One of: webhook, slack, email

target stringrequired

An https URL, or an email address for email.

name string

thresholds integer[]

Whole percentages from 1 to 100. Default [50, 80, 100].

events enum[]

What the channel receives. usage (the default): key and agent limit crossings and runaway flags. price_drop: a model this organisation used in the last 30 days got cheaper (input or output tokens), announced once, within 15 minutes of the change.

Responses

Change what a channel receives

Only events: a new target is a new channel. Changing events keeps the channel and its webhook signing secret. A price_drop event is JSON {type, model, provider, sku, old_usd_per_million, new_usd_per_million, effective_at, at}, with x-autonomous-relay-event: price_drop, signed as every other delivery is.

Needs the Pro ($29/month) plan or above.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

id string · pathrequired

The channel id.

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Request body

events enum[]required

What the channel receives. usage (the default): key and agent limit crossings and runaway flags. price_drop: a model this organisation used in the last 30 days got cheaper (input or output tokens), announced once, within 15 minutes of the change.

Responses

Remove a usage-alert channel

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

id string · pathrequired

The channel id.

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Responses

Send a test alert

Delivers a test event now and reports the outcome, so a wrong URL or a receiver that rejects the payload shows at once. The attempt is recorded in the delivery log.

Needs the Pro ($29/month) plan or above.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

id string · pathrequired

The channel id.

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Responses

What a runaway flag does

alert: every flag is sent to the alert channels and nothing else happens (the default). pause: a flagged KEY is also paused -- it answers 403 key_paused until resumed with PATCH /v1/keys/{hash} {"paused": false}. An agent flag is never a pause: a tag is not a credential.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Responses

Choose what a runaway flag does

Requires config:write (Developer or above): this decides whether a heuristic may stop production traffic.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Parameters

x-csrf-token string · header

Required with a session cookie on any method but GET: the value of the ar_csrf cookie. Not used with a bearer key.

Request body

runaway_action enumrequired

One of: alert, pause

Responses

Runaway-spend flags

A key or an agent (X-Autonomous-Relay-Agent) flagged because its last 15 minutes were far above its own previous 24 hours: spend at least 3x its usual 15 minutes and at least $5, or requests at least 5x usual and at least 300. Checked every five minutes; a subject is flagged at most once an hour, and each flag is sent to every alert channel as a spend.runaway event. With runaway_action = pause (see /v1/alerts/settings) a flagged key is also paused; action says which happened. The last 30 days, at most 100.

Authentication

Management key (ar-mgmt-…) · Dashboard session

Responses