# 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](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

```json
{
  "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](https://covo.lanaai.io/docs/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.