# REST API

Reference for the Comvi REST API. Base URL, authentication, pagination, errors, rate limits, and one page per resource.

Canonical: https://comvi.io/docs/api

The Comvi REST API manages projects, translations, languages, members and integrations.

> **caution**
>
> The REST API is not a production read path for translations. It is rate-limited and slower than the CDN. Read translations at runtime from the [CDN](/docs/platform/cdn) or bundle them at build time with the [CLI](/docs/cli/pull).

## Base URL

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

Every path in the reference is relative to that base.

## 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.

```bash
curl -H "Authorization: Bearer $COMVI_API_KEY" https://api.comvi.io/v1/project
```

```json
{ "id": 5, "organizationId": 1, "name": "my-web-app", "description": "Main web application translations", "sourceLocale": "en" }
```

Each endpoint states which method it accepts. See [Authentication](/docs/api/authentication) for scopes and the full rules.

## Request and response format

Send `Content-Type: application/json` and `Accept: application/json`. Encoding is UTF-8. Every response is JSON.

## 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](/docs/api/projects#get-v1projects) |
| `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

```json
{ "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](/docs/api/errors) for every code.

## 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

| Page | Covers |
|------|--------|
| [Authentication](/docs/api/authentication) | API keys, scopes, sessions |
| [Projects](/docs/api/projects) | Create, read, update, delete, stats, AI context |
| [Translations](/docs/api/translations) | Keys, values, status, batch operations, events |
| [Languages](/docs/api/languages) | Project locales and the system locale list |
| [Namespaces](/docs/api/namespaces) | Group keys into namespaces |
| [Import/Export](/docs/api/import-export) | Web and CLI import and export flows |
| [Machine Translation](/docs/api/machine-translation) | Suggestions, streams, batch jobs |
| [Organizations](/docs/api/organizations) | Organization CRUD |
| [Members](/docs/api/members) | Organization and project members, invitations |
| [API Keys](/docs/api/api-keys) | Manage keys, read the key's project |
| [CDN](/docs/api/cdn) | Trigger a CDN deploy |
| [Webhooks](/docs/api/webhooks) | Subscriptions, deliveries, signatures |
| [Glossaries](/docs/api/glossaries) | Organization glossary terms |
| [Translation Memory](/docs/api/translation-memory) | Memories, entries, search, TMX |
| [Errors](/docs/api/errors) | Every error code and status |

## Next steps

- [Authentication](/docs/api/authentication) to create an API key
- [Projects](/docs/api/projects) to create a project over the API
- [CLI](/docs/cli) for the common operations without writing requests