API reference
The facts that hold for each operation: the address, the key, the shapes and the errors.
The ByteRover API is JSON over HTTP. This reference covers every operation that an API key can call. If you're making your first call, start with Quickstart: the API.
The basics
| Fact | Value |
|---|---|
| Base address | https://byterover.ai/api |
| Version | /v1 in each path |
| Authentication | Authorization: Bearer brv_.... See Authentication and API keys. |
| Request body | JSON, with the header Content-Type: application/json |
| Response body | JSON |
| Times | ISO 8601 strings in UTC, such as 2026-11-10T09:12:44.000Z |
| IDs | Strings with a prefix: drv_ drive, doc_ document, upl_ upload, op_ operation, key_ API key |
curl https://byterover.ai/api/v1/key \
-H "Authorization: Bearer $BYTEROVER_API_KEY"Conventions
- Unknown fields are refused. The search body accepts only the fields in this reference, so a misspelled field name returns
INVALID_REQUESTinstead of being silently ignored. - Lists are paged. A list of documents returns
next_cursor; send it back ascursorto get the next page. Anullcursor means you're on the last page. - Slow work returns an operation. Uploads and deletes return an
operation. Poll it withGET /v1/operations/{operationId}until itsstatusisdoneorfailed. - Calls that change content can carry an
Idempotency-Key. See Idempotency. - Changes can carry
expected_version. See Versions.
Errors
Every error has this shape and a stable code:
{
"error": {
"code": "INVALID_REQUEST",
"message": "effort is required."
}
}Errors and retries lists every code and what to do about it.
For agents that read these pages
Every docs page has a Markdown version at its address plus .md. llms.txt lists the pages, and agents.md explains how to choose a way to connect.