coldvioDocs
Start free
Docs/ api
Reference

Agent API

The allowlisted HTTPS API used by the CLI and MCP server, with tenant isolation and scope checks on every request.

Open OpenAPI 3.1Read as Markdown

Base URL and authentication

Production base URL: https://api.coldvio.com. Browser PKCE login through the CLI is the recommended way to issue a customer token. Dedicated /v1/agent routes accept only audience=agent credentials. Shared generation and campaign-action routes retain legacy extension access, while agent calls still require the matching scope and operation intent.

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

Machine-readable contract

Use the OpenAPI 3.1 document for endpoint discovery, schemas, and generated clients. The MCP catalog is a smaller, agent-oriented description of the exposed tools.

  • OpenAPI: /developers/openapi.json
  • MCP tool catalog: /developers/mcp-tools.json
  • Full LLM context: /llms-full.txt

Scopes

  • agent:read — voice, CRM, leads, campaigns, actions, posts, trends, and account summary.
  • agent:write — selected CRM fields only.
  • agent:generate — credit-consuming draft generation.
  • agent:approve — approve or reject an existing campaign action.

Errors and limits

Errors use an HTTP status and a JSON message. Treat 401 as a missing, invalid, expired, revoked, or wrong-purpose credential. Dedicated /v1/agent routes return 403 when a valid agent token lacks the route scope; shared generation and approval routes deliberately collapse capability mismatch into 401. Treat 404 as absent or non-owned data, 409 as a state conflict, 428 as a missing, expired, changed, or already-consumed operation intent, and 429 as a rate limit. Each intent is one-use: never automatically retry a generation after an ambiguous response. A newly confirmed customer operation receives a fresh intent, including after a failed attempt with the same payload. Production budgets are tenant-wide across tokens, installations, and API instances: 180 agent API requests, 30 generations, and 60 approvals or rejections per minute per customer. If the distributed limiter is unavailable, reads use a bounded per-instance tenant fallback and return X-Coldvio-RateLimit-Degraded: local; consequential writes fail closed, while self-revocation retains its own bounded local containment fallback.