# Organizations

List, create, update and delete organizations through the Comvi REST API.

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

An organization is the top-level entity. Every project, member and billing plan belongs to one, and a user can belong to several.

Every endpoint takes a session cookie and nothing else. A Bearer key returns `401 AUTHENTICATION_REQUIRED`. Sign in first, see [Sessions](/docs/api/authentication#sessions). Common errors: `401 AUTHENTICATION_REQUIRED`, `403 READ_ONLY_MODE` on writes. See [Errors](/docs/api/errors).

## Organization object

```json
{ "id": 1, "name": "Acme Corp", "createdAt": "2025-01-10T08:00:00.000Z", "updatedAt": "2025-01-10T08:00:00.000Z" }
```

### `GET /v1/organizations`

List the organizations the signed-in user belongs to. A user with none gets an empty array.

```bash
curl -b cookies.txt https://api.comvi.io/v1/organizations
```

Returns an array of organization objects.

### `GET /v1/organizations/{id}`

Read one organization. The caller must be a member.

| Parameter | In | Type | Required | Meaning |
|-----------|----|------|----------|---------|
| `id` | path | `integer` | Yes | Organization ID |

```bash
curl -b cookies.txt https://api.comvi.io/v1/organizations/1
```

Returns one organization object.

| Status and code | When |
|-----------------|------|
| `404 ORGANIZATION_NOT_FOUND` | Does not exist, or the caller is not a member |

### `POST /v1/organizations`

Create an organization. The caller becomes its owner with full permissions. Any signed-in user may call it.

| Parameter | In | Type | Required | Meaning |
|-----------|----|------|----------|---------|
| `name` | body | `string` | Yes | 1 to 255 characters |

```bash
curl -X POST -b cookies.txt -H "Content-Type: application/json" \
-d '{"name": "Acme Corp"}' https://api.comvi.io/v1/organizations
```

Returns `201 Created` with the organization object.

| Status and code | When |
|-----------------|------|
| `403 OWNED_FREE_ORG_LIMIT_EXCEEDED` | Free plan users can own at most one organization |
| `409 TRANSACTION_CONFLICT` | The database rolled the transaction back. Retry |
| `422 FIELD_REQUIRED` | `name` is missing |

### `PATCH /v1/organizations/{id}`

Rename an organization.

Requires `organization.edit`, held by owners and managers.

| Parameter | In | Type | Required | Meaning |
|-----------|----|------|----------|---------|
| `id` | path | `integer` | Yes | Organization ID |
| `name` | body | `string` | No | 1 to 255 characters |

```bash
curl -X PATCH -b cookies.txt -H "Content-Type: application/json" \
-d '{"name": "Acme Corporation"}' https://api.comvi.io/v1/organizations/1
```

Returns the updated organization object.

| Status and code | When |
|-----------------|------|
| `403 FORBIDDEN` | No `organization.edit` on the organization |
| `404 ORGANIZATION_NOT_FOUND` | Does not exist |

### `DELETE /v1/organizations/{id}`

Permanently delete an organization with all its projects, translations, members and data. This cannot be undone.

Requires `organization.delete`, held by the owner only. A manager gets `403 FORBIDDEN`.

| Parameter | In | Type | Required | Meaning |
|-----------|----|------|----------|---------|
| `id` | path | `integer` | Yes | Organization ID |

```bash
curl -X DELETE -b cookies.txt https://api.comvi.io/v1/organizations/1
```

Returns `204 No Content`.

| Status and code | When |
|-----------------|------|
| `403 FORBIDDEN` | No `organization.delete` on the organization |
| `404 ORGANIZATION_NOT_FOUND` | Does not exist |
| `409 TRANSACTION_CONFLICT` | The database rolled the transaction back. Retry |

## Next steps

- [Projects](/docs/api/projects) to create projects in an organization
- [Members](/docs/api/members) to invite and manage members
- [Roles and permissions](/docs/platform/roles-permissions) for the permission model