API overview

Every interface to A8 shares one kind of key and one set of request parts and response fields. Each interface carries them in its own fields, and its page shows where.

§1Base URL and routes

The same request returns the same verdict through any interface.

§2Authentication

Every request carries an API key, as Authorization: Bearer <key> or as x-api-key: <key>. The key's permissions set what the request can do: models:infer to judge, models:explain for precedents and recall, and models:train to teach and retract. See API keys.

§3Request

A request has six parts:

Each interface carries the parts in the fields its own clients already send:

With reasoning on, A8 also accepts a prompt that holds the criterion and the subject in one message, as many eval frameworks write their graders. A8 finds each part and answers in the format the prompt asks for. With reasoning off, A8 reads the layout as written, as each interface’s page lays out. See Chat Completions.

§3.1Verdict shape

Each property of the schema is one field of the verdict. Its type sets the kind of judgment the field holds:

A property with a description carries its own criterion and is judged on its own, so one request can carry several criteria. The request's criterion applies to the other properties. In this schema, urgent and tone are judged against their descriptions, and queue against the system message:

{
  "type": "object",
  "properties": {
    "queue": {"enum": ["billing", "shipping", "account"]},
    "urgent": {
      "type": "boolean",
      "description": "Does the customer need an answer today?"
    },
    "tone": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5,
      "description": "How polite is the message?"
    }
  }
}

A forced tool call is read the same way. When a request requires one function, the function's parameters are the verdict shape, and the verdict comes back as that tool call.

§3.2Subject context

Some judgments relate the subject to something else: a source it must be grounded in, a question it must answer, a reference it must match. For those, the subject is a JSON object with output, plus any of reference, context and question. A user message that holds a JSON object with output is read as a subject object, and any other text, JSON included, is judged as text:

The object travels inside the user message as a JSON string:

import json

subject = {
    "output": "Your refund went out on Monday.",
    "context": ["Refund issued on Monday to the original card."],
}
messages = [
    {"role": "system", "content": "Is the output supported by the context?"},
    {"role": "user", "content": json.dumps(subject)},
]

A criterion taught against a standard is judged against that standard. A request that leaves it out abstains and names it in abstention.missing.

§3.3Continue a conversation

A request is a conversation, and A8 answers its latest user message. To follow up on a verdict, send the conversation again with A8’s response as an assistant message and a new user message after it. The follow-up can bring a new subject to judge against the same criterion, change the subject or add a standard such as a reference:

messages = [
    {"role": "system", "content": "Which queue does the ticket belong in?"},
    {"role": "user", "content": "It arrived crushed. I want a refund."},
    {"role": "assistant", "content": '{"queue": "shipping"}'},
    {
        "role": "user",
        "content": "The customer adds: the box was fine. I was charged twice.",
    },
]

{"queue": "billing"}

Recorded from a8-1-1@20260715t140322z on 2026-10-22.

• A8 answers the conversation as sent. Assistant messages are read as earlier turns, whatever they hold, and the response depends on the messages in the request alone.
• The whole conversation is the request. The same conversation against the same version gets the same verdict, and a teach of it records the whole conversation as its input.
• With reasoning off, A8 judges the latest user message alone. Earlier turns are history, so the conversation gets the verdict its latest user message gets on its own.
• On Responses, previous_response_id continues from a stored response. Its input and output come before the new input, and the verdict is the one the whole conversation gets. See Responses.

§4Response

Each interface answers with its own object and puts the verdict where that API puts a model's output. These fields are on every response, under the same names:

A Chat Completions response, with the fields in place:

{
  "id": "eval-9f2c1d84ab30e5f7",
  "object": "chat.completion",
  "model": "a8-1-1:95@20260715t140322z",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"queue\": \"shipping\"}",
        "refusal": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 812,
    "completion_tokens": 0,
    "total_tokens": 812,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 0}
  },
  "system_fingerprint": "fit-1a2b3c4d5e6f7890.9e2a1b3c",
  "min_accuracy": 95
}

Recorded from a8-1-1@20260715t140322z on 2026-10-22.

An abstention returns 200 and sits where each API puts an answer a model declined to give, so a typed client reads it like any other response. See Accuracy and abstention.

With reasoning on, A8 filters some requests whose text is harmful, such as hate speech, violence or self-harm. A filtered request returns 200 in the slot each API keeps for content its filters stop, apart from verdicts and abstentions, and is free. Each interface’s page shows its form.

§5Versioning and compatibility

The request and response formats follow the APIs A8 implements. Within a model version such as a8-1, A8’s own fields change by addition only. These changes count as compatible:

• A new optional request parameter.
• A new response field, or a new field inside abstention or precedents.
• A new value of abstention.kind. Read an unfamiliar kind as an abstention.
• A new error code under an existing status.
• A new response header.
• A different order of properties in a JSON object.

Every other change ships with a new model version, announced on Deprecations and in the Release notes. See Model identifiers for how identifiers and horizons hold a verdict fixed.

§6Request IDs

Every response carries an x-request-id header, and the Anthropic route also sends it as request-id, the header the Anthropic SDKs read. An error body carries the same ID. Quote it when you write to [email protected] about a request.

§7SDKs

You call A8 through the standard SDKs or any client that takes a custom base URL, such as LangChain, LlamaIndex, the Vercel AI SDK, Pydantic AI and LiteLLM.

The SDKs keep A8’s extension fields on the response object:

resp = client.chat.completions.create(**request)

resp.model                         # the version that answered
resp.model_extra.get("min_accuracy")  # the level the verdict is promised at
resp.model_extra.get("abstention") # set on an abstention

type A8Fields = { min_accuracy?: number; abstention?: { kind: string } };

const resp = await client.chat.completions.create(request);
const { min_accuracy, abstention } = resp as typeof resp & A8Fields;