Organizations API

Organizations are the top-level entity in Comvi. Every project, team member, and billing plan belongs to an organization. Users can belong to multiple organizations.

List organizations

Retrieve all organizations the authenticated user belongs to.

GET /api/v1/organizations

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/organizations

Example response

[
  {
    "id": 1,
    "name": "Acme Corp",
    "createdAt": "2025-01-10T08:00:00.000Z",
    "updatedAt": "2025-01-10T08:00:00.000Z"
  },
  {
    "id": 2,
    "name": "Side Project",
    "createdAt": "2025-02-01T12:00:00.000Z",
    "updatedAt": "2025-02-01T12:00:00.000Z"
  }
]

Error codes

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid authentication

Get organization

Retrieve a single organization by its ID. The caller must be a member of the organization.

GET /api/v1/organizations/:id

Path parameters

Parameter	Type	Required	Description
`id`	`integer`	Yes	Organization ID

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/organizations/1

Example response

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

Error codes

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`404`	`ORGANIZATION_NOT_FOUND`	Organization does not exist, or the caller is not a member

Create organization

Create a new organization. The authenticated user is automatically assigned as the owner.

POST /api/v1/organizations

Request body

Field	Type	Required	Description
`name`	`string`	Yes	Organization name (1-255 characters)

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp"}' \
  https://api.comvi.io/api/v1/organizations

Example response

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

Error codes

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid authentication

Update organization

Update an organization’s name. Requires the org.edit permission.

PATCH /api/v1/organizations/:id

Path parameters

Parameter	Type	Required	Description
`id`	`integer`	Yes	Organization ID

Request body

Field	Type	Required	Description
`name`	`string`	No	Updated organization name (1-255 characters)

Example request

curl -X PATCH \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corporation"}' \
  https://api.comvi.io/api/v1/organizations/1

Example response

{
  "id": 1,
  "name": "Acme Corporation",
  "createdAt": "2025-01-10T08:00:00.000Z",
  "updatedAt": "2025-01-15T14:30:00.000Z"
}

Error codes

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to edit this organization

Delete organization

Permanently delete an organization and all its data. Requires the org.delete permission.

DELETE /api/v1/organizations/:id

Path parameters

Parameter	Type	Required	Description
`id`	`integer`	Yes	Organization ID

Example request

curl -X DELETE \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/organizations/1

Example response

Returns 204 No Content with an empty body on success.

Error codes

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to delete this organization

Next steps

Projects API Create and manage projects within an organization.

Members API Invite and manage team members in your organization.

API Keys Create API keys for programmatic access.

Roles & Permissions Understand the permission system for organization members.