> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cvat-ai/cvat/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.cvat.ai/api/organizations" \
    -H "Authorization: Token <your_token>"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://app.cvat.ai/api/organizations",
      headers={"Authorization": "Token <your_token>"}
  )
  organizations = response.json()
  ```
</CodeGroup>

### Query Parameters

<ParamField query="name" type="string">
  Filter by organization name
</ParamField>

<ParamField query="owner" type="string">
  Filter by owner username
</ParamField>

<ParamField query="slug" type="string">
  Filter by organization slug (unique identifier)
</ParamField>

<ParamField query="search" type="string">
  Search organizations by name, owner, or slug
</ParamField>

<ParamField query="sort" type="string">
  Sort by: `name`, `owner`, `slug`, `id`
</ParamField>

<ParamField query="page" type="integer">
  Page number for pagination
</ParamField>

<ParamField query="page_size" type="integer">
  Number of results per page
</ParamField>

<ParamField query="filter" type="string">
  JSON Logic filter expression. Available fields: `name`, `owner`, `slug`, `id`
</ParamField>

### Response

<ResponseField name="count" type="integer">
  Total number of organizations
</ResponseField>

<ResponseField name="next" type="string">
  URL for the next page
</ResponseField>

<ResponseField name="previous" type="string">
  URL for the previous page
</ResponseField>

<ResponseField name="results" type="array">
  Array of organization objects
</ResponseField>

## Create an Organization

Create a new organization.

<CodeGroup>
  ```bash cURL theme={null}
  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": "team@example.com"
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://app.cvat.ai/api/organizations",
      headers={"Authorization": "Token <your_token>"},
      json={
          "slug": "my-team",
          "name": "My Team",
          "description": "Computer vision annotation team",
          "contact": {
              "email": "team@example.com"
          }
      }
  )
  organization = response.json()
  ```
</CodeGroup>

### Request Body

<ParamField body="slug" type="string" required>
  Unique organization identifier (lowercase, hyphens allowed)
</ParamField>

<ParamField body="name" type="string" required>
  Organization display name
</ParamField>

<ParamField body="description" type="string">
  Organization description
</ParamField>

<ParamField body="contact" type="object">
  Contact information (email, phone, etc.)
</ParamField>

### Response

<ResponseField name="id" type="integer">
  Organization ID
</ResponseField>

<ResponseField name="slug" type="string">
  Organization slug
</ResponseField>

<ResponseField name="name" type="string">
  Organization name
</ResponseField>

<ResponseField name="description" type="string">
  Organization description
</ResponseField>

<ResponseField name="created_date" type="string">
  Creation timestamp
</ResponseField>

<ResponseField name="updated_date" type="string">
  Last update timestamp
</ResponseField>

<ResponseField name="owner" type="object">
  Owner user details
</ResponseField>

<ResponseField name="contact" type="object">
  Contact information
</ResponseField>

## Get Organization Details

Retrieve details of a specific organization.

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

### Path Parameters

<ParamField path="id" type="integer" required>
  Unique organization identifier
</ParamField>

## Update an Organization

Update organization properties.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      f"https://app.cvat.ai/api/organizations/{org_id}",
      headers={"Authorization": "Token <your_token>"},
      json={
          "name": "Updated Team Name",
          "description": "New description"
      }
  )
  updated_org = response.json()
  ```
</CodeGroup>

### Path Parameters

<ParamField path="id" type="integer" required>
  Unique organization identifier
</ParamField>

### Request Body

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

<ParamField body="name" type="string">
  Organization name
</ParamField>

<ParamField body="description" type="string">
  Organization description
</ParamField>

<ParamField body="contact" type="object">
  Contact information
</ParamField>

## Delete an Organization

Delete an organization.

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

<Warning>
  Deleting an organization will affect all associated projects, tasks, and memberships.
</Warning>

### Path Parameters

<ParamField path="id" type="integer" required>
  Unique organization identifier
</ParamField>

## Memberships

Manage organization members and their roles.

### List Members

List all members of an organization.

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

#### Query Parameters

<ParamField query="org" type="string">
  Organization slug
</ParamField>

<ParamField query="org_id" type="integer">
  Organization ID
</ParamField>

<ParamField query="user" type="string">
  Filter by username
</ParamField>

<ParamField query="role" type="string">
  Filter by role: `worker`, `supervisor`, `maintainer`, or `owner`
</ParamField>

<ParamField header="X-Organization" type="string">
  Organization slug (alternative to query parameter)
</ParamField>

### Get Membership Details

Retrieve details of a specific membership.

```bash theme={null}
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.

```bash theme={null}
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

<ParamField body="role" type="string">
  Member role: `worker`, `supervisor`, `maintainer`, or `owner`
</ParamField>

### Remove Member

Remove a member from the organization.

```bash theme={null}
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

```bash theme={null}
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": "newuser@example.com"
  }'
```

#### Request Body

<ParamField body="email" type="string" required>
  Email address of the user to invite
</ParamField>

<ParamField body="role" type="string" required>
  Role to assign: `worker`, `supervisor`, `maintainer`, or `owner`
</ParamField>

### List Invitations

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

### Get Invitation Details

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

### Accept an Invitation

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

### Decline an Invitation

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

### Delete an Invitation

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

### Resend an Invitation

```bash theme={null}
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

```bash theme={null}
curl -X GET "https://app.cvat.ai/api/projects" \
  -H "Authorization: Token <your_token>" \
  -H "X-Organization: my-team"
```

### Using Query Parameter

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

Or use the organization ID:

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

## Example: Organization Management

```python theme={null}
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": "team@example.com"}
}

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": "annotator1@example.com", "role": "worker"},
    {"email": "annotator2@example.com", "role": "worker"},
    {"email": "supervisor@example.com", "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']}")
```