Organizations

Manage organizations via the REST API

Overview

Organizations in CVAT allow teams to collaborate on projects and tasks. Each organization has members with different roles and permissions.

List Organizations

Retrieve a list of all organizations you have access to.

cURL

curl -X GET "https://app.cvat.ai/api/organizations" \
  -H "Authorization: Token <your_token>"

Query Parameters

name · string

Filter by organization name

owner · string

Filter by owner username

slug · string

Filter by organization slug (unique identifier)

search · string

Search organizations by name, owner, or slug

sort · string

Sort by: name, owner, slug, id

page · integer

Page number for pagination

page_size · integer

Number of results per page

filter · string

JSON Logic filter expression. Available fields: name, owner, slug, id

Response

count · integer

Total number of organizations

next · string

URL for the next page

previous · string

URL for the previous page

results · array

Array of organization objects

Create an Organization

Create a new organization.

cURL

curl -X POST "https://app.cvat.ai/api/organizations" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-team",
    "name": "My Team",
    "description": "Computer vision annotation team",
    "contact": {
      "email": "[e-mail]"
    }
  }'

Request Body

slug · string · required

Unique organization identifier (lowercase, hyphens allowed)

name · string · required

Organization display name

description · string

Organization description

contact · object

Contact information (email, phone, etc.)

Response

id · integer

Organization ID

slug · string

Organization slug

name · string

Organization name

description · string

Organization description

created_date · string

Creation timestamp

updated_date · string

Last update timestamp

owner · object

Owner user details

contact · object

Contact information

Get Organization Details

Retrieve details of a specific organization.

curl -X GET "https://app.cvat.ai/api/organizations/{id}" \
  -H "Authorization: Token <your_token>"

Path Parameters

id · integer · required

Unique organization identifier

Update an Organization

Update organization properties.

cURL

curl -X PATCH "https://app.cvat.ai/api/organizations/{id}" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Team Name",
    "description": "New description"
  }'

Path Parameters

id · integer · required

Unique organization identifier

Request Body

All fields are optional. Only include fields you want to update.

name · string

Organization name

description · string

Organization description

contact · object

Contact information

Delete an Organization

Delete an organization.

curl -X DELETE "https://app.cvat.ai/api/organizations/{id}" \
  -H "Authorization: Token <your_token>"

Deleting an organization will affect all associated projects, tasks, and memberships.

Path Parameters

id · integer · required

Unique organization identifier

Memberships

Manage organization members and their roles.

List Members

List all members of an organization.

curl -X GET "https://app.cvat.ai/api/memberships?org=my-team" \
  -H "Authorization: Token <your_token>"

Query Parameters

org · string

Organization slug

org_id · integer

Organization ID

user · string

Filter by username

role · string

Filter by role: worker, supervisor, maintainer, or owner

X-Organization · string

Organization slug (alternative to query parameter)

Get Membership Details

Retrieve details of a specific membership.

curl -X GET "https://app.cvat.ai/api/memberships/{id}" \
  -H "Authorization: Token <your_token>"

Update Member Role

Change a member’s role within the organization.

curl -X PATCH "https://app.cvat.ai/api/memberships/{id}" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "supervisor"
  }'

Request Body

role · string

Member role: worker, supervisor, maintainer, or owner

Remove Member

Remove a member from the organization.

curl -X DELETE "https://app.cvat.ai/api/memberships/{id}" \
  -H "Authorization: Token <your_token>"

Organization Roles

Organizations support four roles with different permission levels:

Worker

Basic annotator role:

• View assigned tasks and jobs
• Create and edit annotations
• Cannot manage projects or invite users

Supervisor

Project oversight role:

• All worker permissions
• Create and manage projects
• Assign tasks to workers
• Review annotations

Maintainer

Administrative role:

• All supervisor permissions
• Manage organization members
• Configure organization settings
• Manage cloud storages

Owner

Full control:

• All maintainer permissions
• Delete the organization
• Transfer ownership
• Billing management

Invitations

Invite users to join your organization.

Create an Invitation

curl -X POST "https://app.cvat.ai/api/invitations" \
  -H "Authorization: Token <your_token>" \
  -H "X-Organization: my-team" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "worker",
    "email": "[e-mail]"
  }'

Request Body

email · string · required

Email address of the user to invite

role · string · required

Role to assign: worker, supervisor, maintainer, or owner

List Invitations

curl -X GET "https://app.cvat.ai/api/invitations?org=my-team" \
  -H "Authorization: Token <your_token>"

Get Invitation Details

curl -X GET "https://app.cvat.ai/api/invitations/{key}" \
  -H "Authorization: Token <your_token>"

Accept an Invitation

curl -X POST "https://app.cvat.ai/api/invitations/{key}/accept" \
  -H "Authorization: Token <your_token>"

Decline an Invitation

curl -X POST "https://app.cvat.ai/api/invitations/{key}/decline" \
  -H "Authorization: Token <your_token>"

Delete an Invitation

curl -X DELETE "https://app.cvat.ai/api/invitations/{key}" \
  -H "Authorization: Token <your_token>"

Resend an Invitation

curl -X POST "https://app.cvat.ai/api/invitations/{key}/resend" \
  -H "Authorization: Token <your_token>"

Working with Organization Context

When making API calls within an organization context, include the organization identifier:

Using Header

curl -X GET "https://app.cvat.ai/api/projects" \
  -H "Authorization: Token <your_token>" \
  -H "X-Organization: my-team"

Using Query Parameter

curl -X GET "https://app.cvat.ai/api/projects?org=my-team" \
  -H "Authorization: Token <your_token>"

Or use the organization ID:

curl -X GET "https://app.cvat.ai/api/projects?org_id=1" \
  -H "Authorization: Token <your_token>"

Example: Organization Management

import requests

BASE_URL = "https://app.cvat.ai/api"
HEADERS = {"Authorization": "Token <your_token>"}

# Create organization
org_data = {
    "slug": "ml-annotation-team",
    "name": "ML Annotation Team",
    "description": "Team for machine learning dataset annotation",
    "contact": {"email": "[e-mail]"}
}

org = requests.post(
    f"{BASE_URL}/organizations",
    headers=HEADERS,
    json=org_data
).json()

org_slug = org["slug"]
print(f"Created organization: {org_slug}")

# Invite team members
team_members = [
    {"email": "[e-mail]", "role": "worker"},
    {"email": "[e-mail]", "role": "worker"},
    {"email": "[e-mail]", "role": "supervisor"}
]

for member in team_members:
    invitation = requests.post(
        f"{BASE_URL}/invitations",
        headers={**HEADERS, "X-Organization": org_slug},
        json=member
    ).json()
    print(f"Invited {member['email']} as {member['role']}")

# Create project in organization context
project = requests.post(
    f"{BASE_URL}/projects",
    headers={**HEADERS, "X-Organization": org_slug},
    json={
        "name": "Autonomous Vehicle Detection",
        "labels": [{"name": "car", "color": "#ff0000"}]
    }
).json()

print(f"Created project {project['id']} in organization {org_slug}")

# List organization members
members = requests.get(
    f"{BASE_URL}/memberships",
    headers=HEADERS,
    params={"org": org_slug}
).json()

print(f"\nOrganization has {members['count']} members:")
for member in members["results"]:
    print(f"  - {member['user']['username']}: {member['role']}")