Skip to content
Comvi

Organizations

View .md

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. Common errors: 401 AUTHENTICATION_REQUIRED, 403 READ_ONLY_MODE on writes. See Errors.

Organization object

Section titled “Organization object”
{ "id": 1, "name": "Acme Corp", "createdAt": "2025-01-10T08:00:00.000Z", "updatedAt": "2025-01-10T08:00:00.000Z" }

GET /v1/organizations

Section titled “GET /v1/organizations”

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

Terminal window
curl -b cookies.txt https://api.comvi.io/v1/organizations

Returns an array of organization objects.

GET /v1/organizations/{id}

Section titled “GET /v1/organizations/{id}”

Read one organization. The caller must be a member.

Parameter In Type Required Meaning
id path integer Yes Organization ID
Terminal window
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

Section titled “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
Terminal window
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}

Section titled “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
Terminal window
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}

Section titled “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
Terminal window
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

Section titled “Next steps”