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 "Authorization: Bearer comvi_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 "Authorization: Bearer comvi_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 "Authorization: Bearer comvi_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 "Authorization: Bearer comvi_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 "Authorization: Bearer comvi_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 APICreate and manage projects within an organization.

Members APIInvite and manage team members in your organization.

API KeysCreate API keys for programmatic access.

Roles & PermissionsUnderstand the permission system for organization members.