# Instructions for agents

Short rules for an AI agent or a coding assistant that reads these docs to call the CloudOverture API.

- The API is REST over HTTPS at `https://qa-api.cloudoverture.com/v1`. The full description is the OpenAPI file at `https://qa-api.cloudoverture.com/v1/openapi.json`.
- Sign every request with `Authorization: Bearer <key>`. The company comes only from the key; no request field names a company.
- Test with a `co_test_` key in a sandbox. Never put a `co_live_` key in a browser page, a sample, or a log.
- The REST API takes member keys only. An AI agent that acts for a member connects at the MCP address instead.
- Money is a decimal string with a currency code, e.g. `"480.00"` and `"usd"`. Never send a JSON number for money, and never send a total: the server computes every total and every tax.
- Send an `Idempotency-Key` header on every write, and reuse it when you retry the same request. Invoice send and void require one, and so does an invoice create without an `external_id`.
- Branch on the error's `code`, never on its `message`. Each code has a page at `/errors/<code>`.
- On `429` and on a `5xx`, wait `Retry-After`, then retry with growing waits plus a small random delay, at most 5 tries.
- Quote the `request_id` of a failing call to support.
- There is no search endpoint and no bulk endpoint. One call works on one record. To read a lot, page through a list.
- Every page of these docs is also served as markdown: add `.md` to its address. The index is [llms.txt](/llms.txt).