# Zapros

> Zapros is a metered AI API aggregator at https://zapros.ai. It provides OpenAI-compatible chat, Responses, embeddings, asynchronous video generation, scoped management automation, and a stateless MCP server. Prices and balances are in RUB.

## Machine-readable references

- OpenAPI 3.1: https://zapros.ai/openapi.json
- MCP endpoint: https://zapros.ai/mcp
- MCP OAuth protected-resource metadata (RFC 9728): https://zapros.ai/.well-known/oauth-protected-resource/mcp
- Management OAuth protected-resource metadata (RFC 9728): https://zapros.ai/.well-known/oauth-protected-resource/api/v1/management
- OAuth authorization-server metadata (RFC 8414): https://zapros.ai/.well-known/oauth-authorization-server
- OAuth token revocation (RFC 7009): POST https://zapros.ai/oauth/revoke
- Human Agent Connect onboarding: https://zapros.ai/connect
- Human documentation: https://zapros.ai/docs
- Chat and Responses model catalog: https://zapros.ai/api/v1/models
- Embedding model catalog: https://zapros.ai/api/v1/embeddings/models
- Video model catalog: https://zapros.ai/api/v1/videos

## Authentication and secret separation

- Inference keys start with `zpr_`. Use them only for inference endpoints with `Authorization: Bearer zpr_...`.
- Manually provisioned management tokens start with `zpm_`. Use them for the management REST API or MCP with `Authorization: Bearer zpm_...`.
- Agent Connect OAuth access tokens start with `zpo_` and normally expire after 15 minutes. Each grant and token has exactly one audience: `https://zapros.ai/mcp` or `https://zapros.ai/api/v1/management`. These are separate grants and token families: an MCP token must fail at Management REST and a Management token must fail at MCP.
- Management and OAuth scopes are `account:read`, `models:read`, `usage:read`, `compute:read`, `keys:read`, `keys:create`, `keys:update`, and `keys:revoke`. Legacy manual tokens with `keys:write` remain compatible, but new grants use the three narrow mutation scopes.
- A management token cannot create another management token, access payments, or top up a balance. Never expose a `zpm_` token to an untrusted model, browser, log, or prompt.
- OAuth key creation never returns a raw newly created `zpr_` to an OAuth client, whether it uses MCP or Management REST. It returns a 15-minute, session-authenticated dashboard claim: the owner may safely retry Reveal until explicitly acknowledging that the key was saved. ACK erases encrypted replay copies; expiry before ACK disables the key. Manual `zpm_` calls through MCP use the same claim because output can enter model context. A trusted direct Management REST creation with `zpm_` returns the secret once; if the same idempotent operation was also completed through MCP, a later terminal replay returns claim metadata and never restores an acknowledged or expired secret.

- Each account may retain at most 20 active and 100 total management tokens.
- Agent Connect public clients revoke a grant with `POST /oauth/revoke`, an exact `zpo_` or `zprf_` token, and their public `client_id`. Revocation invalidates the entire grant, both OAuth token families, and active inference keys created by that grant. Unknown, wrong-client, and already-revoked tokens receive the same empty HTTP 200 response.

## Inference

The OpenAI-compatible base URL is `https://zapros.ai/api/v1`.

- POST `/chat/completions`: chat completions, including streaming.
- POST `/responses`: Responses API, including streaming.
- POST `/embeddings`: text embeddings.
- POST `/videos`: start an asynchronous video job.
- GET `/videos/{id}`: poll a video job with an active inference key from the same owning project.

Always select a current model from a catalog endpoint. The catalogs fail closed when price data is stale. Respect HTTP 402 budget/balance errors, HTTP 429 with Retry-After, and the request ID returned in response headers.

## Management API

Use a scoped manual `zpm_` bearer token, or complete OAuth authorization with the exact resource `https://zapros.ai/api/v1/management` and use the resulting `zpo_` token. Management OAuth is a separate grant from MCP OAuth, even for the same client:

- GET `/api/v1/management/account`
- GET `/api/v1/management/models?kind=all&limit=50`
- POST `/api/v1/management/cost-estimates`
- GET `/api/v1/management/projects?limit=50`
- POST `/api/v1/management/projects/default`
- GET/POST `/api/v1/management/keys`
- PATCH/DELETE `/api/v1/management/keys/{id}`
- GET `/api/v1/management/usage?days=30`
- GET `/api/v1/management/compute/offers`
- GET `/api/v1/management/compute/instances`

`GET /models` and `POST /cost-estimates` require `models:read`; an estimate reads current catalog pricing and never calls a provider, reserves balance, or charges the account. Before key management, call `GET /projects` with any key-management scope. If it returns an empty page, `POST /projects/default` under `keys:create` idempotently creates or repairs the personal organization, workspace, wallet, and default project. Every key list/create/update/revoke operation requires that explicit `project_id` (query for list/revoke, body for create/update). `POST /api/v1/management/keys` also requires a stable 8–128 character `Idempotency-Key`, an explicit monthly budget, a per-request limit, and a non-empty allowed-model list. A direct `zpm_` REST creation receives the new `zpr_` secret once while it remains available; the 24-hour idempotency record prevents duplicate creation but cannot recover a secret erased by claim acknowledgement or expiry. A Management OAuth caller receives only an owner-authenticated dashboard claim and can list, update, revoke, and read usage only for keys created by that exact grant. Mutations use the separate `keys:create`, `keys:update`, and `keys:revoke` scopes and are audited. Compute endpoints are discovery-only until hosting is enabled; do not infer that an empty offer list is an error.

## MCP

Zapros MCP is a stateless JSON-RPC 2.0 endpoint. It supports MCP `2026-07-28` and compatibility with `2025-11-25` and `2025-06-18`. It uses POST only; it does not expose an SSE GET stream or protocol sessions.

Preferred onboarding is Agent Connect OAuth. Client-specific instructions are at `https://zapros.ai/connect`. Point the MCP client at `https://zapros.ai/mcp`; the unauthenticated challenge identifies RFC 9728 protected-resource metadata, which links to RFC 8414 authorization-server metadata. Public clients use authorization code with S256 PKCE, an exact registered redirect URI, and `resource=https://zapros.ai/mcp`. Client secrets are not accepted. Client ID Metadata Documents and bounded dynamic public-client registration are supported for client compatibility. The returned `zpo_` access token is short-lived; refresh tokens rotate on every exchange, and reuse revokes the whole grant.

The consent screen binds the grant to aggregate limits: total monthly budget across all active keys created by the connection, per-request maximum, model allowlist, maximum active-key count, and grant expiry. An OAuth connection may list, update, or revoke only keys created by that same connection. Users can inspect and revoke connected applications under Dashboard → Agents & MCP; revocation invalidates tokens and disables the connection's active keys.

Manual MCP access remains supported. For that mode create a scoped `zpm_` token in the dashboard and configure `Authorization: Bearer zpm_...` explicitly. A manual token remains account-scoped and is a different trust model from a consent-bounded OAuth connection.

For MCP 2026-07-28 every request must include:

- `Content-Type: application/json`
- `Accept: application/json, text/event-stream`
- `Authorization: Bearer zpo_...` for OAuth, or `Bearer zpm_...` for manual setup
- `MCP-Protocol-Version: 2026-07-28`
- `Mcp-Method` exactly matching the JSON-RPC body method
- `Mcp-Name` exactly matching `params.name` for `tools/call`
- `params._meta["io.modelcontextprotocol/protocolVersion"]` equal to `2026-07-28`

Encode an unsafe or non-ASCII `Mcp-Name` as `=?base64?{canonical-base64-utf8}?=`. Browser requests are accepted only from `https://zapros.ai`, `https://www.zapros.ai`, or an explicitly configured origin; native MCP clients normally omit `Origin`.

Begin modern discovery with `server/discover`. Available methods are `ping`, `tools/list`, and `tools/call`. Available tools are `get_account`, `list_projects`, `ensure_default_project`, `list_models`, `estimate_cost`, `list_api_keys`, `create_api_key`, `update_api_key`, `revoke_api_key`, `get_usage`, `list_compute_offers`, and `list_compute_instances`. `list_projects` is available with any key-management scope; `ensure_default_project` requires `keys:create` and is idempotent. Read the returned project object's `id` field and pass that value as the `project_id` argument to every key tool. Tool availability is filtered by token scope.

The modern params._meta object must also include io.modelcontextprotocol/clientCapabilities as an object (it may be empty). JSON-RPC request IDs must be strings or safe integers; omit the ID for notifications and never send explicit null. A successful create_api_key result contains only `secret_delivery.method=dashboard_claim`, a claim URL, and its expiry—never the raw `zpr_` secret. Grant only the narrow key mutation scopes the client needs.

Example discovery body:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "server/discover",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "my-agent", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}
```

MCP tool results include both `structuredContent` and a text JSON fallback. The MCP server deliberately excludes payments, balance top-ups, management-token creation, and compute mutations.