REST API Overview

The Comvi REST API gives you programmatic access to all platform features. Use it to automate translation workflows, build custom integrations, or manage content from your CI/CD pipeline.

Base URL

https://api.comvi.io/api/v1

Authentication

All API requests require authentication. Comvi supports two methods:

API Keys

For server-to-server integrations and CI/CD pipelines. Pass the key in the X-API-Key header:

curl -H "X-API-Key: your-api-key" \
  https://api.comvi.io/api/v1/projects

Create API keys in the platform under Settings > API Keys. See Authentication for details.

Session Authentication

For browser-based access (used by the Comvi dashboard internally). Session cookies are set after login.

Request Format

Content-Type: application/json for request bodies
Accept: application/json for responses
Character encoding: UTF-8

Response Format

All responses return JSON:

{
  "id": 1,
  "name": "my-project",
  "createdAt": "2025-01-15T10:30:00Z"
}

List endpoints return paginated results using cursor-based pagination:

{
  "data": [...],
  "nextCursor": "eyJpZCI6MTAwfQ=="
}

Pagination

Parameter	Type	Description
`cursor`	`string`	Cursor from previous response’s `nextCursor`
`limit`	`number`	Items per page (default: 50, max: 100)

Error Responses

Errors return a consistent format:

{
  "statusCode": 404,
  "error": "NOT_FOUND",
  "message": "Project not found",
  "meta": {
    "projectId": 123
  }
}

Field	Type	Description
`statusCode`	`number`	HTTP status code
`error`	`string`	Machine-readable error code
`message`	`string`	Human-readable description
`meta`	`object`	Additional context (optional)

See Error Reference for a complete list of error codes.

Rate Limiting

The API applies a default global rate limit of 500 requests per minute.

Some endpoints define stricter route-specific limits, such as machine translation suggestion and CDN deployment endpoints.

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header.

API Sections

Section	Description
Authentication	API keys, sessions, CSRF
Projects	Create, update, list projects
Translations	CRUD for translation keys and values
Languages	Manage project languages
Namespaces	Organize keys into namespaces
Import/Export	Bulk import and export operations
Machine Translation	AI-powered translation
Organizations	Organization management
Members	Team member management
API Keys	Manage API keys
CDN	Publish and purge CDN
Webhooks	Event notifications
Glossaries	Terminology management
Translation Memory	Translation memory
Error Reference	Complete error code list

Next Steps

Authentication — set up API key authentication
Projects — create your first project via API
CLI Overview — use the CLI for common API operations