Notes for AI agents

When to use this pageCopy Anchor Link

Read this page if you are an AI agent (Claude Code, Cursor, Codex, ChatGPT or another) setting up a tool, an SDK or code to call AI models through EZAT Router for a user, or debugging such a setup.

Required valuesCopy Anchor Link

Optional headers, for code you write:

See Prompt caching.

Safe setup procedureCopy Anchor Link

1. Find the key without seeing it. Ask the user which environment variable holds their EZAT Router key; suggest EZAT_API_KEY. Never ask them to paste the key into the chat. If they have no key, tell them to create one at https://router.ezat.io/keys and export it in their own terminal.

2. Check it's set, without printing it. Print only its length and prefix:

   Copy Text

   printf 'length %s, prefix %s\n' "${#EZAT_API_KEY}" "${EZAT_API_KEY:0:8}"

   Expect length 48, prefix ezat_sk_. A different length usually means quotes, spaces or a cut-off copy.

3. Validate the key with a request that costs nothing:

   curl

   Copy Text

   curl --fail-with-body -sS -o /dev/null -w '%{http_code}\n' https://api.router.ezat.io/v1/models \
     -H "x-api-key: $EZAT_API_KEY"

   200 means the key works. 401 means it is missing, mistyped, expired or revoked: stop and tell the user.

4. Pick a model. Use the model the user asks for, or one from GET https://api.router.ezat.io/v1/models. Don't rely on a list from memory or from this page.

5. Send one tiny request with a small max_tokens:

   curl

   Copy Text

   curl --fail-with-body -sS https://api.router.ezat.io/v1/messages \
     -H "x-api-key: $EZAT_API_KEY" \
     -H "anthropic-version: 2023-06-01" \
     -H "content-type: application/json" \
     -d '{"model": "anthropic/claude-sonnet-5-5", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK."}]}'

   On 402, the organization has no credit or the key reached its spend limit: tell the user to add credit at https://router.ezat.io/billing (or use another key), and stop.

6. Configure the tool. Use the format the tool speaks:

   • Claude Code and Anthropic SDKs: base URL https://api.router.ezat.io. For Claude Code, ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN (Claude Code).
   • OpenAI SDKs and OpenAI-format tools: base URL https://api.router.ezat.io/openai/v1 (OpenAI-format tools).
   • Your own code: read the key from the environment variable at runtime, on the server.

   Put the key in user-level or untracked configuration only. Ask before changing a global config file the user didn't mention.

7. Verify inside the tool. Make one request through the tool itself. In Claude Code, /status shows the base URL and which credential is in use.

8. On errors, follow the error type. Retry 429, 500 and 529 (503 in the OpenAI format) with backoff, waiting at least the seconds in the retry-after header when there is one. A 504 on a non-streaming request means the model took too long: send it again with streaming. Don't retry 400, 401, 402, 403, 404 or 413: fix the cause first. See Errors and Troubleshooting.

Do not do thisCopy Anchor Link

• Don't ask the user to paste a key into the chat, and don't print, echo or log a key, even partly beyond its ezat_sk_ prefix.
• Don't write a key into a committed file: source code, a tracked .env, a project's .claude/settings.json, a CI config in the repository.
• Don't put a key in frontend, browser or mobile app code, or in a URL or query string.
• Don't add /v1 to https://api.router.ezat.io, and don't give https://api.router.ezat.io to an OpenAI client: it needs https://api.router.ezat.io/openai/v1.
• Don't hard-code prices or model lists. Read GET https://api.router.ezat.io/v1/models, Models and Pricing when you need them.
• Don't sign up, pay, top up, or create or revoke keys for the user. They do those in the dashboard.
• Don't overwrite an existing Anthropic or OpenAI setup that the user uses for other work without asking. Change only what the task needs.
• Don't retry a 402 in a loop, and don't send large or long requests just to test a setup.
• Don't rely on Message Batches, the Files API, server tools that run on Anthropic's side (web search, code execution) or the MCP connector: EZAT Router doesn't serve them.

Machine-readable docsCopy Anchor Link

Read only the pages you need. Prices and the model list change; fetch them when you need them instead of keeping a copy.