# Coldvio Agent API

Base URL after rollout: `https://api.coldvio.com`.

```http
Authorization: Bearer <CUSTOMER_AGENT_TOKEN>
Accept: application/json
```

Issue a purpose-bound token with `npx -y @coldvio/cli@0.1.0 login`. Dedicated `/v1/agent/*` routes reject dashboard and extension credentials. Shared LinkedIn generation, email generation, and campaign-action routes retain legacy extension access; calls made with agent credentials still require the matching scope and a one-use operation intent. Scopes: `agent:read`, `agent:write`, `agent:generate`, `agent:approve`.

Agent tokens expire after 90 days. Production rate limits are tenant-wide across every token, installation, and API instance: 180 agent API calls/minute, 30 generations/minute, and 60 approvals or rejections/minute per customer. Honor `Retry-After` on `429` responses. If the distributed limiter is unavailable, read-only routes use a bounded per-instance tenant fallback and return `X-Coldvio-RateLimit-Degraded: local`; writes fail closed.

Consequential agent requests first issue an intent at `POST /v1/agent/intents`. The intent expires after 120 seconds, is single-use, and is bound to the customer, operation, resource, and exact request payload. The CLI and MCP server handle this automatically after explicit confirmation.

Each operation intent is one-use and bound to the exact customer, operation, resource, and payload. Clients must not automatically retry a generation after an ambiguous network response. A new explicit customer confirmation may issue a new intent for the same payload, so failed attempts never permanently block a legitimate retry.

Errors: 401 missing, invalid, expired, revoked, or wrong-purpose credential. Dedicated `/v1/agent` routes use 403 for a valid token without the route scope; shared capability routes collapse capability mismatch into 401. 404 absent/non-owned; 409 state conflict; 429 rate limit.

- [OpenAPI 3.1](https://www.coldvio.com/developers/openapi.json)
- [MCP tool JSON](https://www.coldvio.com/developers/mcp-tools.json)
- [Security](https://www.coldvio.com/developers/security.md)