Concepts

REST conventions

Base URL, headers, idempotency, confirmations, revisions, pagination, errors and rate limits for the REST API.

Base URL	`https://covo.lanaai.io/api/v1`
Format	JSON request and response bodies; responses are never cached (`Cache-Control: no-store`)
OpenAPI	https://covo.lanaai.io/api/v1/openapi.json (OpenAPI 3.1, with `x-required-scope`, `x-destructive`, `x-idempotent` and `x-mcp-tool`)
Agent ids	`agt_` and 12 letters and digits; permanent, unlike usernames

Headers

Header	When
`Authorization: Bearer ...`	Always
`Content-Type: application/json`	On POST and PATCH
`Idempotency-Key`	Optional, on operations that create something; see below
`X-Client-Name`, `X-Client-Version`	Optional; names your app in Studio and the audit log

Inputs

Path, query and body parameters merge into one input, validated against the operation's schema. Unknown fields are rejected.

Idempotency

Send Idempotency-Key (8 to 200 characters of letters, digits, _ . : -) on operations that create something. A retry with the same key and input returns the first result with idempotent_replay: true. The same key with a different input answers 422 idempotency_key_reused; while the first call is still running, 409 idempotency_in_progress.

Confirmations

Sensitive writes (publishing, unpublishing, rolling back, applying drafts, removing items, moving or deleting short links) answer 409 confirmation_required unless the request has "confirm": true. Ask the person first, then send it.

Revisions

Every change bumps the agent's revision. Send expected_revision from your last read with update_agent_configuration; if someone changed the agent since, you get 409 version_conflict instead of overwriting their work.

Lists

Lists take limit and offset and return items with total.

Errors

{
  "error": {
    "code": "insufficient_scope",
    "message": "This token cannot change agents.",
    "field": "agent_id",
    "resolution": "Create a token with the agents:write scope.",
    "details": {}
  },
  "requestId": "f3c1..."
}

code is stable; resolution says what to do. Quote requestId when asking for help. All codes: Errors.

Rate limits

300 requests per minute per token, and 600 operations per minute (an MCP batch counts each call).
6 test runs (run_agent_test) per minute.
Over the limit: 429 rate_limited with Retry-After in seconds (also details.retry_after_sec).

Cross-origin

The API answers browser requests from any origin. It uses bearer tokens only, never cookies.