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

# Projects

> Manage CVAT projects via the REST API

## Overview

Projects in CVAT are containers for related annotation tasks. They allow you to organize tasks, define shared labels, and manage team assignments.

## List Projects

Retrieve a list of all projects accessible to you.

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

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

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

### Query Parameters

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

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

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

<ParamField query="status" type="string">
  Filter by status: `annotation`, `validation`, or `completed`
</ParamField>

<ParamField query="search" type="string">
  Search projects by name, owner, assignee, or status
</ParamField>

<ParamField query="sort" type="string">
  Sort by: `name`, `owner`, `assignee`, `status`, `id`, `updated_date`
</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`, `assignee`, `status`, `id`, `updated_date`
</ParamField>

<ParamField header="X-Organization" type="string">
  Organization unique slug
</ParamField>

### Response

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

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

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

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

## Create a Project

Create a new annotation project.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.cvat.ai/api/projects" \
    -H "Authorization: Token <your_token>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Autonomous Vehicle Dataset",
      "labels": [
        {
          "name": "car",
          "color": "#ff0000",
          "attributes": []
        },
        {
          "name": "pedestrian",
          "color": "#00ff00",
          "attributes": []
        }
      ]
    }'
  ```

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

  response = requests.post(
      "https://app.cvat.ai/api/projects",
      headers={"Authorization": "Token <your_token>"},
      json={
          "name": "Autonomous Vehicle Dataset",
          "labels": [
              {
                  "name": "car",
                  "color": "#ff0000",
                  "attributes": []
              },
              {
                  "name": "pedestrian",
                  "color": "#00ff00",
                  "attributes": []
              }
          ]
      }
  )
  project = response.json()
  ```
</CodeGroup>

### Request Body

<ParamField body="name" type="string" required>
  Project name
</ParamField>

<ParamField body="labels" type="array">
  Array of label definitions for the project
</ParamField>

<ParamField body="owner_id" type="integer">
  User ID of the project owner
</ParamField>

<ParamField body="assignee_id" type="integer">
  User ID of the project assignee
</ParamField>

<ParamField body="bug_tracker" type="string">
  Bug tracker URL
</ParamField>

<ParamField body="source_storage" type="object">
  Source storage configuration
</ParamField>

<ParamField body="target_storage" type="object">
  Target storage configuration
</ParamField>

### Response

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

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

<ResponseField name="owner" type="object">
  Project owner details
</ResponseField>

<ResponseField name="assignee" type="object">
  Project assignee details
</ResponseField>

<ResponseField name="status" type="string">
  Project status: `annotation`, `validation`, or `completed`
</ResponseField>

<ResponseField name="labels" type="array">
  Array of label definitions
</ResponseField>

<ResponseField name="created_date" type="string">
  Project creation timestamp
</ResponseField>

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

## Get Project Details

Retrieve details of a specific project.

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

### Path Parameters

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

## Update a Project

Update project properties.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://app.cvat.ai/api/projects/{id}" \
    -H "Authorization: Token <your_token>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Updated Project Name",
      "status": "validation"
    }'
  ```

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

  response = requests.patch(
      f"https://app.cvat.ai/api/projects/{project_id}",
      headers={"Authorization": "Token <your_token>"},
      json={
          "name": "Updated Project Name",
          "status": "validation"
      }
  )
  updated_project = response.json()
  ```
</CodeGroup>

### Path Parameters

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

### Request Body

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

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

<ParamField body="assignee_id" type="integer">
  User ID of the assignee
</ParamField>

<ParamField body="status" type="string">
  Project status: `annotation`, `validation`, or `completed`
</ParamField>

<ParamField body="labels" type="array">
  Updated label definitions
</ParamField>

<ParamField body="bug_tracker" type="string">
  Bug tracker URL
</ParamField>

## Delete a Project

Delete a project and all its associated tasks.

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

<Warning>
  Deleting a project will permanently remove all associated tasks, jobs, and annotations.
</Warning>

### Path Parameters

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

## Export Project Dataset

Initiate an export of the project dataset in a specific format.

```bash theme={null}
curl -X POST "https://app.cvat.ai/api/projects/{id}/dataset/export?format=COCO%201.0&save_images=true" \
  -H "Authorization: Token <your_token>"
```

### Path Parameters

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

### Query Parameters

<ParamField query="format" type="string" required>
  Export format name (e.g., "COCO 1.0", "YOLO 1.1", "Pascal VOC 1.1")
</ParamField>

<ParamField query="filename" type="string">
  Desired output filename
</ParamField>

<ParamField query="save_images" type="boolean" default={false}>
  Include images in the export
</ParamField>

<ParamField query="location" type="string">
  Export location: `local` or `cloud_storage`
</ParamField>

<ParamField query="cloud_storage_id" type="integer">
  Cloud storage ID (required if location is `cloud_storage`)
</ParamField>

### Response

<ResponseField name="rq_id" type="string">
  Request ID for tracking export status
</ResponseField>

Check export status using: `GET /api/requests/{rq_id}`

## Import Project Dataset

Import annotations into a project from a dataset file.

```bash theme={null}
curl -X POST "https://app.cvat.ai/api/projects/{id}/dataset/?format=COCO%201.0" \
  -H "Authorization: Token <your_token>" \
  -F "dataset_file=@annotations.json"
```

### Path Parameters

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

### Query Parameters

<ParamField query="format" type="string">
  Import format name
</ParamField>

<ParamField query="filename" type="string">
  Dataset filename (for cloud storage imports)
</ParamField>

<ParamField query="location" type="string">
  Import location: `local` or `cloud_storage`
</ParamField>

<ParamField query="cloud_storage_id" type="integer">
  Cloud storage ID
</ParamField>

### Response

<ResponseField name="rq_id" type="string">
  Request ID for tracking import status
</ResponseField>

## Backup a Project

Create a backup of a project including all tasks and annotations.

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

### Path Parameters

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

### Query Parameters

<ParamField query="filename" type="string">
  Backup filename
</ParamField>

<ParamField query="location" type="string">
  Backup location: `local` or `cloud_storage`
</ParamField>

<ParamField query="cloud_storage_id" type="integer">
  Cloud storage ID
</ParamField>

<ParamField query="lightweight" type="boolean" default={true}>
  Create lightweight backup (without media files for cloud-based tasks)
</ParamField>

### Response

<ResponseField name="rq_id" type="string">
  Request ID for tracking backup status
</ResponseField>

## Restore Project from Backup

Restore a project from a backup file.

```bash theme={null}
curl -X POST "https://app.cvat.ai/api/projects/backup/" \
  -H "Authorization: Token <your_token>" \
  -F "backup_file=@project_backup.zip"
```

### Query Parameters

<ParamField query="filename" type="string">
  Backup filename (for cloud storage)
</ParamField>

<ParamField query="location" type="string" default="local">
  Backup location: `local` or `cloud_storage`
</ParamField>

<ParamField query="cloud_storage_id" type="integer">
  Cloud storage ID
</ParamField>

### Response

<ResponseField name="rq_id" type="string">
  Request ID for tracking restore status
</ResponseField>

## Get Project Preview

Retrieve a preview image for a project.

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

### Path Parameters

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

## Example: Complete Project Workflow

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

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

# Create a project
project_data = {
    "name": "Traffic Sign Detection",
    "labels": [
        {"name": "stop_sign", "color": "#ff0000"},
        {"name": "yield_sign", "color": "#ffff00"},
        {"name": "speed_limit", "color": "#00ff00"}
    ]
}

response = requests.post(
    f"{BASE_URL}/projects",
    headers=HEADERS,
    json=project_data
)
project = response.json()
project_id = project["id"]
print(f"Created project: {project_id}")

# Export project dataset
response = requests.post(
    f"{BASE_URL}/projects/{project_id}/dataset/export",
    headers=HEADERS,
    params={"format": "COCO 1.0", "save_images": True}
)
rq_id = response.json()["rq_id"]

# Check export status
while True:
    status = requests.get(
        f"{BASE_URL}/requests/{rq_id}",
        headers=HEADERS
    ).json()
    
    if status["status"] == "finished":
        download_url = status["result_url"]
        print(f"Export ready: {download_url}")
        break
    elif status["status"] == "failed":
        print(f"Export failed: {status['message']}")
        break
    
    time.sleep(2)
```