Skip to main content

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

​
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)

Build docs developers (and LLMs) love

Get started for freeTalk to us