Skip to main content

​
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 -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 -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": "[email protected]"
    }
  }'

​
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 -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": "[email protected]"
  }'

​
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": "[email protected]"}
}

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": "[email protected]", "role": "worker"},
    {"email": "[email protected]", "role": "worker"},
    {"email": "[email protected]", "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']}")

Build docs developers (and LLMs) love

Get started for freeTalk to us