Agent setup

This page is written for an AI agent configuring a tool or codebase to use Princeps Sator. Follow it literally. Do not infer anything not stated here; where a value is needed that this page does not give, fetch it from the URL named.

1. Facts#

• Production API host: https://sator-api.princep.org
• Two endpoints, two base URLs:

• Every model id works on both endpoints.
• The API key looks like sk-sator-v1- followed by 24 alphanumeric characters. The user must supply it; it is created at https://sator.princep.org/dashboard. Never invent one.
• The key is accepted in either header on either endpoint: Authorization: Bearer <key> or x-api-key: <key>.
• GET https://sator-api.princep.org/v1/models needs no key and returns the exact list of valid model ids.
• POST /v1/messages requires max_tokens (positive integer) on every request. POST /v1/chat/completions does not.
• POST /v1/responses is served stateless: never send previous_response_id; send the full input each turn. Not served: /v1/embeddings (answers 404). /v1/messages/count_tokens is served (an estimate, never billed).

2. Choose the base URL#

1. Determine which wire the client speaks.
2. If it is an OpenAI-compatible client (OpenAI SDK, openai_compatible settings, "OpenAI base URL" field, OPENAI_BASE_URL, LangChain ChatOpenAI, @ai-sdk/openai-compatible), use https://sator-api.princep.org/v1.
3. If it is an Anthropic-compatible client (Anthropic SDK, Claude Code, ANTHROPIC_BASE_URL, LangChain ChatAnthropic, Zed anthropic_compatible), use https://sator-api.princep.org with no path.
4. Exception: the Vercel AI SDK's @ai-sdk/anthropic provider takes https://sator-api.princep.org/v1.

3. Decision table by harness#

Identify the harness from the repository or the user's request, then apply exactly the row that matches. Full pages are linked; the essentials are in the row.

4. Environment variable names#

5. Verify#

Run exactly this, with the user's key in SATOR_API_KEY:

curl -s https://sator-api.princep.org/v1/chat/completions \
  -H "Authorization: Bearer $SATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Reply with exactly: ok"}],"max_tokens":8}'

Expected: HTTP 200 and a JSON object of this shape. The id prefix varies by model (router-…, chatcmpl-…); prompt_tokens includes chat-template overhead and is far above the word count; a reasoning model adds reasoning_content beside content and may hit max_tokens while reasoning — judge success by object and by choices[0].message, never by the token counts or the exact wording:

{"id":"router-841ccc4fe2eb6c57ce12fa44e2709764","object":"chat.completion","created":1787596599,"model":"deepseek-v4-flash","choices":[{"index":0,"finish_reason":"stop","message":{"role":"assistant","content":"ok","reasoning_content":"…"}}],"usage":{"prompt_tokens":88,"completion_tokens":12,"total_tokens":100}}

If the harness uses the Anthropic wire, verify with:

curl -s https://sator-api.princep.org/v1/messages \
  -H "x-api-key: $SATOR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","max_tokens":8,"messages":[{"role":"user","content":"Reply with exactly: ok"}]}'

Expected: HTTP 200 and a JSON object of this shape. A thinking block precedes the text block only when the request enabled thinking — find the block with type: "text" rather than reading content[0]:

{"id":"msg_ca0525a31544409394c9c37b48200d05","type":"message","role":"assistant","model":"deepseek-v4-flash","content":[{"type":"text","text":"ok"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":88,"output_tokens":12,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}}

Interpret failures by status:

6. Do not#

• Do not append /v1 to the Anthropic base URL — except for the Vercel AI SDK's @ai-sdk/anthropic.
• Do not omit /v1 from the OpenAI base URL.
• Do not configure /v1/embeddings; it is not served. Do not send previous_response_id to /v1/responses; it is stateless.
• Do not invent a model id. Use one from the list below or from GET /v1/models.
• Do not rely on Claude Code's /model picker to show Sator models; set ANTHROPIC_MODEL or the ANTHROPIC_DEFAULT_*_MODEL variables.
• Do not put the key into a file the user has said to keep secret-free; prefer environment variables and {env:…} references where the harness supports them.
• Do not use OPENAI_API_BASE with the OpenAI SDK (it reads OPENAI_BASE_URL); do not use OPENAI_BASE_URL with Aider (it reads OPENAI_API_BASE).
• Do not trust a client's own cost display; the charged amount is at https://sator.princep.org/dashboard.

7. Model ids#

Generated from the catalog at build time. GET https://sator-api.princep.org/v1/models returns the same list live.

• glm-5.2
• glm-5.1
• kimi-k2.7-code
• kimi-k2.6
• mimo-v2.5
• minimax-m3
• minimax-m2.7
• qwen3.7-max
• qwen3.7-plus
• qwen3.6-plus
• hy3
• longcat-2.0
• muse-spark-1.2
• deepseek-v4-flash
• glm-5.3
• grok-4.6
• gpt-5.6-luna
• kimi-k3
• mimo-v2.5-pro
• qwen3.8-max
• deepseek-v4-pro
• deepseek-v4-flash-vision-exp

Context windows and max output per id: Models (https://sator.princep.org/docs/models.md).