API reference
The public surface is intentionally small: one model endpoint, a catalog, and account introspection. Everything else lives in the console.
Base URL & authentication
All endpoints live at https://api.projectares.ai. Pass your key in the x-api-key header (or as a Bearer token). Keys are prefixed sk-ares- and can be created for a personal account or an organization — usage is billed to the key's account.
/v1/messagesThe industry-standard Messages protocol — including streaming via "stream": true (SSE), system prompts, prompt caching via cache_control, and multi-turn conversations. Project Ares routes from the model ID and returns every response in the same shape, so one client handles every model.
Optional Ares extensions: "speed": "fast" (or header x-ares-speed: fast) requests the priority lane — quicker responses, billed at 2× (standard billing applies automatically when a model can't run fast). Cache reads bill at 10% of input; cache writes at 125% (1-hour caches at 200%).
/v1/modelsEvery model on the platform with lifecycle metadata: { id, display_name, family, status, context_window, retiresAt?, replacement? }. Deprecated models keep working but carry a sunset date and a suggested replacement (also surfaced per-request via the x-ares-deprecation header); retired models fail loudly with the fix in the error. Requires auth.
/pricingPublic, no auth: what every model costs, in credits and USD per million tokens, including cache rates and the fast-lane multiplier. This is generated from the same table the meter bills with — it cannot disagree with your ledger.
/catalogThe curated model catalog: { models: [{ id, label, group }] }. Public, no auth. Build your model picker from this — when Project Ares enables a new model it appears here immediately.
/meIntrospect the calling key: email, plan, and credits — your currently available usage in micro-USD (1,000,000 = $1.00).
/statusLiveness and the number of available models. Useful for health checks.
Errors
Every error — whatever happens behind the gateway — arrives in ONE Ares taxonomy. You never see, and never need to handle, another vendor's error format.
| Status | Type | Meaning |
|---|---|---|
| 400 | invalid_request_error | The request itself is malformed — the message says what to fix |
| 401 | authentication_error | Missing, revoked, or unknown key |
| 402 | billing_error | Trial ended, allowance used and balance empty, or spend limit reached |
| 404 | not_found_error | That model doesn't exist or isn't available — see /v1/models |
| 429 | rate_limit_error | Over 120 requests/minute on one account, or global throttle |
| 502 | api_error | The model service is temporarily unavailable — retry with backoff |
| 529 | overloaded_error | The model is temporarily overloaded — retry in a moment |
Error bodies always look like {"type":"error","error":{"type":"…","message":"…"}} — so existing SDK retry logic works unchanged. Mid-stream failures arrive as an SSE error event in the same shape.
Rate limits
- 120 requests / minute per account on
/v1/messages. - A global per-IP throttle protects the platform; sustained abuse is flagged to staff automatically.