API reference
The API follows the OpenAI chat-completions shape. It is a subset: anything outside it is refused with an error that names the parameter, rather than accepted and changed without saying so.
The machine-readable version of this page is api.autarcho.com/openapi.yaml, an OpenAPI 3.1 document. It needs no key, so a client generator, an editor plugin or an agent tool can be pointed at it before anything exists.
From your stack
Anything that speaks the OpenAI chat shape points at this base URL. Two that people ask about, with the form that works today:
from litellm import completion
# LiteLLM routes any OpenAI-compatible endpoint through its openai/ prefix.
# The model is the id from GET /v1/models, or its 64-character hash.
response = completion(
model="openai/<model>",
api_base="https://api.autarcho.com/v1",
api_key="ak_<64 hex>",
messages=[{"role": "user", "content": "hello"}],
)
print(response.choices[0].message.content) from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="<model>",
base_url="https://api.autarcho.com/v1",
api_key="ak_<64 hex>",
)
print(llm.invoke("hello").content) Use the hash when the call has to mean the same model next month. An alias is a convenience and a
model owner can point it somewhere else; the hash is the file. A model that has left the verified
catalogue answers 404 model_not_found, which is final, while a model with no operator
online answers 503, which is worth retrying. The price per generated token is GET /model/{hash}/price, so cost tracking can read it rather than hard-code it.
For agents
There is an MCP server for agent clients: npx autarcho-mcp. It exposes list_models, get_price, chat_completion and get_balance, needs only AUTARCHO_API_KEY, and caps one completion at 2048
generated tokens. Source and configuration blocks: npmjs.com/package/autarcho-mcp.
Endpoints
| Method and path | What it does |
|---|---|
POST /v1/chat/completions | One completion for one conversation. |
GET /v1/models | The models available to your key. |
GET /v1/models/{model} | One model by id or alias. |
GET /model/{hash}/price | A price. Add ?for_client=true, and no key is needed. |
POST /v1/batches | A list of requests. See Batch requests. |
Authentication
Send Authorization: Bearer ak_<64 hex> on every call except the price lookup.
Keys are generated by your client, not issued through a sign-up form: there is no email
verification and no identity check. A key in that format that has no credit yet is a 402, the same as a key whose balance is spent. A missing key, or a value that could
not be a key at all, is a 401.
Chat completions
| Field | Type | Notes |
|---|---|---|
model | string | Required. A model id or an alias. |
messages | array | Required. Roles system, user and assistant, with string content. |
stream | boolean | Server-sent events instead of one response. Default false. |
max_tokens | integer | Upper bound on the tokens generated. |
temperature, top_p, top_k, min_p | number | Sampling. Each is validated and refused if out of range. |
presence_penalty, frequency_penalty | number | Between -2 and 2. |
logit_bias | object | Token id to a bias between -100 and 100. Up to 1024 entries. |
dry_multiplier and the other dry_* fields | number | Penalises repeated sequences, which breaks loops a token penalty cannot see. |
response_format | object | text, json_object or json_schema. |
tools, tool_choice | array, value | Function calling. See below. |
max_price_per_token_micro_usdc | integer | Refuse the request if the price is above this, before anything is charged. |
The response carries the text, why generation stopped, and what it cost.
{
"choices": [
{
"message": { "role": "assistant", "content": "Hello." },
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 0,
"completion_tokens": 6,
"cost_micro_usdc": 6
}
} finish_reason is stop when the model finished, length when
it reached max_tokens, and tool_calls when it asked for a function. prompt_tokens is always zero because the prompt is not billed.
Streaming
With stream: true the response is server-sent events, one piece of text per event,
ending with data: [DONE].
data: {"choices":[{"delta":{"content":"Hel"}}]}
data: {"choices":[{"delta":{"content":"lo"}}]}
data: {"choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE] The first event can take a while on a model that is not loaded yet, which is the reason to stream: you see progress instead of waiting on one response. Do not set a timeout of a few seconds on the first event.
Tool calls
Pass tools in the OpenAI shape and the model can answer with a call instead of text. tool_choice takes auto, required, none, or a
named function.
{
"choices": [
{
"message": {
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_1",
"type": "function",
"function": { "name": "get_weather", "arguments": "{\"city\":\"Oslo\"}" }
}
]
},
"finish_reason": "tool_calls"
}
]
} Send the result back as a user message and ask again. A streamed call arrives complete at the end of the stream, because a name and its arguments cannot be split before both exist.
Structured output
response_format with json_object returns a JSON object. With json_schema the output follows your schema, and when the schema admits only a
finite set of documents generation stops on its own: the text parses and finish_reason is stop. An open object can keep growing until max_tokens, so give it a realistic budget.
Reasoning models
A model that thinks before it answers returns the thinking in reasoning_content,
separate from content. Both are part of the generated token count.
Parameters that are refused
These return 400 with unsupported_parameter rather than being ignored: stop, seed, logprobs, n above 1, image or
audio content, and anything outside the table above.
Errors
An error body carries a code, a message, and a retryable flag, so a
client can decide without matching on prose.
| Status | Code | What to do |
|---|---|---|
| 400 | unsupported_parameter | Change or remove the parameter named in the message. |
| 401 | invalid_api_key | The key is missing, retired, or not in the key format. Add credit to a retired key and it is still refused: use its replacement. |
| 402 | insufficient_quota | The price is above your limit, or the key has no credit yet. Nothing was charged. |
| 404 | model_not_found | No such model. GET /v1/models has the list. |
| 409 | idempotency_in_progress | Wait for Retry-After and ask again. |
| 429 | rate_limited | Slow down, then retry with backoff. |
| 503 | unavailable | The request could not be served this time. Retry with backoff. |
Billing explains which failures are free and how to retry a request without being charged twice.