API reference

Annotide exposes a REST API under /api/v1. Every install serves its own interactive, always-current API documentation at /api/v1/docs — for example https://annotate.example.com/api/v1/docs — generated straight from the version you’re running.

Note

The document below is a snapshot from the repository at build time, for browsing without a running install. For anything you’ll actually call, use your install’s own /api/v1/docs.

Download the OpenAPI document (JSON), or open it in any OpenAPI viewer, for example Swagger Editor.

Using the API

• API keys (Settings → API keys) authenticate scripts, CI and service accounts. Create a service account for anything that isn’t a person.
• Idempotency. Create requests carry an Idempotency-Key, so a retried request answers with the first result instead of creating a duplicate.
• Errors follow RFC 9457 (type, title, status, detail).
• The Python SDK and CLI wraps this API with typed responses, retry handling and an MCP server for AI agents — it’s the easiest way to script against Annotide.