REST API
The Comvi REST API manages projects, translations, languages, members and integrations.
Base URL
Section titled “Base URL”https://api.comvi.io/v1Every path in the reference is relative to that base.
Authentication
Section titled “Authentication”| Method | Header or cookie | Use it for |
|---|---|---|
| API key | Authorization: Bearer $COMVI_API_KEY |
Server-to-server, CI, CLI. Bound to one project |
| Session | Cookie set by POST /v1/auth/login |
Browser access, organization-scoped and management routes |
Start with GET /v1/project. It returns the project the key belongs to and confirms the key works.
curl -H "Authorization: Bearer $COMVI_API_KEY" https://api.comvi.io/v1/project{ "id": 5, "organizationId": 1, "name": "my-web-app", "description": "Main web application translations", "sourceLocale": "en" }Each endpoint states which method it accepts. See Authentication for scopes and the full rules.
Request and response format
Section titled “Request and response format”Send Content-Type: application/json and Accept: application/json. Encoding is UTF-8. Every response is JSON.
Pagination
Section titled “Pagination”List endpoints use cursor pagination with two envelopes.
| Envelope | Used by |
|---|---|
{ "data": [], "pagination": { "nextCursor": "…", "hasMore": true } } |
Translation keys, comments, permission audit logs. pagination.totalItems is declared but populated only by some endpoints |
{ "<resource>": [], "nextCursor": "…", "hasMore": true } |
Projects, users, glossary terms, translation memories, TM entries. Webhook deliveries add total |
| Parameter | Type | Meaning |
|---|---|---|
cursor |
string |
nextCursor from the previous response, sent back unchanged. The projects list takes an integer instead, see Projects |
limit |
integer |
Items per page. Each endpoint states its range and default; most take 1 to 100 and default to 50 |
hasMore is always present. Stop when it is false.
Errors
Section titled “Errors”{ "code": "PROJECT_NOT_FOUND", "message": "Project not found", "meta": { "projectId": 123 } }| Field | Type | Meaning |
|---|---|---|
code |
string |
Machine-readable code. Branch on it |
message |
string |
Human-readable description |
meta |
object |
Optional context, varies by error |
The HTTP status is on the response, not in the body. Request validation failures return 422 with code and meta but no message. See Errors for every code.
Rate limiting
Section titled “Rate limiting”The global limit is 500 requests per minute. Some routes set a stricter limit of their own, such as machine translation suggestions and CDN deploys. Over the limit the API answers 429 with TOO_MANY_REQUESTS and a Retry-After header.
Resources
Section titled “Resources”| Page | Covers |
|---|---|
| Authentication | API keys, scopes, sessions |
| Projects | Create, read, update, delete, stats, AI context |
| Translations | Keys, values, status, batch operations, events |
| Languages | Project locales and the system locale list |
| Namespaces | Group keys into namespaces |
| Import/Export | Web and CLI import and export flows |
| Machine Translation | Suggestions, streams, batch jobs |
| Organizations | Organization CRUD |
| Members | Organization and project members, invitations |
| API Keys | Manage keys, read the key’s project |
| CDN | Trigger a CDN deploy |
| Webhooks | Subscriptions, deliveries, signatures |
| Glossaries | Organization glossary terms |
| Translation Memory | Memories, entries, search, TMX |
| Errors | Every error code and status |
Next steps
Section titled “Next steps”- Authentication to create an API key
- Projects to create a project over the API
- CLI for the common operations without writing requests