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.

cURL

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

Query Parameters

name · string

Filter by project name

owner · string

Filter by owner username

assignee · string

Filter by assignee username

status · string

Filter by status: annotation, validation, or completed

search · string

Search projects by name, owner, assignee, or status

sort · string

Sort by: name, owner, assignee, status, id, updated_date

page · integer

Page number for pagination

page_size · integer

Number of results per page

filter · string

JSON Logic filter expression. Available fields: name, owner, assignee, status, id, updated_date

X-Organization · string

Organization unique slug

Response

count · integer

Total number of projects

next · string

URL for the next page of results

previous · string

URL for the previous page of results

results · array

Array of project objects

Create a Project

Create a new annotation project.

cURL

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

Request Body

name · string · required

Project name

labels · array

Array of label definitions for the project

owner_id · integer

User ID of the project owner

assignee_id · integer

User ID of the project assignee

bug_tracker · string

Bug tracker URL

source_storage · object

Source storage configuration

target_storage · object

Target storage configuration

Response

id · integer

Project ID

name · string

Project name

owner · object

Project owner details

assignee · object

Project assignee details

status · string

Project status: annotation, validation, or completed

labels · array

Array of label definitions

created_date · string

Project creation timestamp

updated_date · string

Project last update timestamp

Get Project Details

Retrieve details of a specific project.

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

Path Parameters

id · integer · required

Unique project identifier

Update a Project

Update project properties.

cURL

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"
  }'

Path Parameters

id · integer · required

Unique project identifier

Request Body

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

name · string

Project name

assignee_id · integer

User ID of the assignee

status · string

Project status: annotation, validation, or completed

labels · array

Updated label definitions

bug_tracker · string

Bug tracker URL

Delete a Project

Delete a project and all its associated tasks.

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

Deleting a project will permanently remove all associated tasks, jobs, and annotations.

Path Parameters

id · integer · required

Unique project identifier

Export Project Dataset

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

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

id · integer · required

Unique project identifier

Query Parameters

format · string · required

Export format name (e.g., “COCO 1.0”, “YOLO 1.1”, “Pascal VOC 1.1”)

filename · string

Desired output filename

save_images · boolean · default: false

Include images in the export

location · string

Export location: local or cloud_storage

cloud_storage_id · integer

Cloud storage ID (required if location is cloud_storage)

Response

rq_id · string

Request ID for tracking export status

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

Import Project Dataset

Import annotations into a project from a dataset file.

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

id · integer · required

Unique project identifier

Query Parameters

format · string

Import format name

filename · string

Dataset filename (for cloud storage imports)

location · string

Import location: local or cloud_storage

cloud_storage_id · integer

Cloud storage ID

Response

rq_id · string

Request ID for tracking import status

Backup a Project

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

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

Path Parameters

id · integer · required

Unique project identifier

Query Parameters

filename · string

Backup filename

location · string

Backup location: local or cloud_storage

cloud_storage_id · integer

Cloud storage ID

lightweight · boolean · default: true

Create lightweight backup (without media files for cloud-based tasks)

Response

rq_id · string

Request ID for tracking backup status

Restore Project from Backup

Restore a project from a backup file.

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

Query Parameters

filename · string

Backup filename (for cloud storage)

location · string · default: "local"

Backup location: local or cloud_storage

cloud_storage_id · integer

Cloud storage ID

Response

rq_id · string

Request ID for tracking restore status

Get Project Preview

Retrieve a preview image for a project.

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

Path Parameters

id · integer · required

Unique project identifier

Example: Complete Project Workflow

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)