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 pathWhat it does
POST /v1/chat/completionsOne completion for one conversation.
GET /v1/modelsThe models available to your key.
GET /v1/models/{model}One model by id or alias.
GET /model/{hash}/priceA price. Add ?for_client=true, and no key is needed.
POST /v1/batchesA 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

FieldTypeNotes
modelstringRequired. A model id or an alias.
messagesarrayRequired. Roles system, user and assistant, with string content.
streambooleanServer-sent events instead of one response. Default false.
max_tokensintegerUpper bound on the tokens generated.
temperature, top_p, top_k, min_pnumberSampling. Each is validated and refused if out of range.
presence_penalty, frequency_penaltynumberBetween -2 and 2.
logit_biasobjectToken id to a bias between -100 and 100. Up to 1024 entries.
dry_multiplier and the other dry_* fieldsnumberPenalises repeated sequences, which breaks loops a token penalty cannot see.
response_formatobjecttext, json_object or json_schema.
tools, tool_choicearray, valueFunction calling. See below.
max_price_per_token_micro_usdcintegerRefuse 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.

StatusCodeWhat to do
400unsupported_parameterChange or remove the parameter named in the message.
401invalid_api_keyThe key is missing, retired, or not in the key format. Add credit to a retired key and it is still refused: use its replacement.
402insufficient_quotaThe price is above your limit, or the key has no credit yet. Nothing was charged.
404model_not_foundNo such model. GET /v1/models has the list.
409idempotency_in_progressWait for Retry-After and ask again.
429rate_limitedSlow down, then retry with backoff.
503unavailableThe 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.