# ZeroCredit AI — agent instructions

ZeroCredit AI is an enterprise AI gateway. One OpenAI-compatible HTTP API routes
each request to a compatible model across providers, optimizing cost, latency and
quality, with per-organization accounting and governance.

Base URL: `https://zerocreditai.com/api/public/v1`
OpenAPI: `https://zerocreditai.com/openapi.json`
MCP server: `https://zerocreditai.com/mcp`

For an existing OpenAI-compatible client, replace its provider API key with a
ZeroCredit token (`zc_...`) and set its base URL to the URL above. Provider
credentials are connected separately in ZeroCredit: they pay for and execute
model calls on the customer's provider accounts, while the ZeroCredit token
authenticates the application to the gateway.

## When to use ZeroCredit AI

Reach for this API when the job is one of these:

- **Send a chat completion without picking a model.** You have a prompt and no
  strong model preference: `POST /chat/completions` with `model: "zerocredit-auto"`
  and the gateway selects a compatible, cost-efficient model for that request.
- **Call many providers through one credential.** You would otherwise hold
  separate OpenAI, Anthropic, Google, xAI or DeepSeek keys and separate SDKs. One
  `zc_...` token and one OpenAI-compatible client covers all of them.
- **Cut spend on a workload you already run.** Ask for cheaper routing on
  bulk, low-stakes traffic while keeping strong models for hard requests; identical
  requests can be served from the semantic cache.
- **Attribute AI cost to a project, team or customer.** Send a `project_id` and
  every request is priced from provider-reported tokens and recorded against that
  project for reporting and budgets.
- **Keep working when a provider fails.** Failover and retries are handled inside
  the gateway, so a provider outage or 429 does not become your outage.
- **Use your own provider keys (BYOK) with central control.** Your keys stay
  primary; ZeroCredit-managed credits are only a fallback.
- **Compare model prices and capabilities before choosing.** `GET /catalog`
  returns routable models, context windows, capabilities and list prices without
  any credential.

Do not use this API for: model training or fine-tuning, hosting your own weights,
or storing documents — it is a routing and governance layer, not a model host or
a datastore.

## How an agent should call it

1. **Look around first, no credential needed.**
   - `GET /api/public/v1/status` — endpoints, capabilities, auth methods.
   - `GET /api/public/v1/catalog` — models, context windows, list prices.
   - `POST /api/public/v1/sandbox/chat/completions` — deterministic sandbox
     response for validating request and response handling with no key.
2. **Get a credential self-serve.** Sign up at `https://zerocreditai.com/auth`
   (free tier, no sales call) and create an API token in the developer settings at
   `https://zerocreditai.com/app/developer`. Tokens start with `zc_`.
   Human-delegated access can use OAuth 2.0 instead; metadata is at
   `https://zerocreditai.com/.well-known/oauth-authorization-server`.
3. **Call the API like OpenAI.**

   ```bash
   curl https://zerocreditai.com/api/public/v1/chat/completions \
     -H "Authorization: Bearer $ZEROCREDIT_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model":"zerocredit-auto","messages":[{"role":"user","content":"Summarize this contract clause."}]}'
   ```

4. **Read the rate-limit headers.** Every API response carries
   `RateLimit-Policy` (and `RateLimit`, `RateLimit-Remaining`, `RateLimit-Reset`
   once the caller is identified). A `429` includes `Retry-After` in seconds —
   wait that long, then retry with jitter.
5. **Handle errors structurally.** Errors are JSON:
   `{"error":{"code","type","message","param","hint"}}`. Use `error.code` for
   control flow and `error.hint` for the corrective action. Unknown paths return
   `404` — JSON under `/api/`, Markdown when the request sends
   `Accept: text/markdown`.

## Endpoints

| Method | Path | Auth | Purpose |
| --- | --- | --- | --- |
| GET | `/api/public/v1/status` | none | Service, endpoint and capability listing |
| GET | `/api/public/v1/catalog` | none | Public model catalog and list prices |
| POST | `/api/public/v1/sandbox/chat/completions` | none | Deterministic sandbox completion |
| GET | `/api/public/v1/models` | `zc_` token | Models available to the caller |
| POST | `/api/public/v1/chat/completions` | `zc_` token | Chat completions, streaming, vision, tools, structured output, web search |
| POST | `/api/public/v1/embeddings` | `zc_` token | Embeddings |
| POST | `/api/public/v1/images/generations` | `zc_` token | Image generation |

CLI: `npx @zerocredit/cli status` (commands: `status`, `catalog`, `openapi`,
`models`, `chat`, `embed`; reads `ZEROCREDIT_API_KEY`).

Full reference: `https://zerocreditai.com/docs`.