Annotations

Overview

Annotations in CVAT include shapes (rectangles, polygons, polylines, points, cuboids, ellipses, masks), tracks (objects tracked across frames), and tags (frame-level labels). Annotations can be managed at the project, task, or job level.

Annotation Format

CVAT uses a standardized JSON format for annotations:

{
  "version": 0,
  "tags": [
    {
      "frame": 0,
      "label_id": 1,
      "group": 0,
      "source": "manual",
      "attributes": []
    }
  ],
  "shapes": [
    {
      "type": "rectangle",
      "frame": 0,
      "label_id": 1,
      "group": 0,
      "source": "manual",
      "attributes": [],
      "points": [100, 100, 200, 200],
      "occluded": false
    }
  ],
  "tracks": [
    {
      "label_id": 1,
      "frame": 0,
      "group": 0,
      "source": "manual",
      "attributes": [],
      "shapes": [
        {
          "type": "rectangle",
          "frame": 0,
          "points": [100, 100, 200, 200],
          "occluded": false,
          "outside": false,
          "attributes": []
        }
      ]
    }
  ]
}

Shape Types

CVAT supports the following shape types:

Rectangle

Bounding boxes defined by two points (top-left and bottom-right):

{
  "type": "rectangle",
  "points": [x1, y1, x2, y2]
}

Polygon

Closed polygons defined by multiple points:

{
  "type": "polygon",
  "points": [x1, y1, x2, y2, x3, y3, ...]
}

Polyline

Open polylines:

{
  "type": "polyline",
  "points": [x1, y1, x2, y2, x3, y3, ...]
}

Points

Multiple individual points:

{
  "type": "points",
  "points": [x1, y1, x2, y2, ...]
}

Cuboid

3D bounding boxes (8 points):

{
  "type": "cuboid",
  "points": [x1, y1, x2, y2, x3, y3, x4, y4, x5, y5, x6, y6, x7, y7, x8, y8]
}

Ellipse

Ellipses defined by center and two radii:

{
  "type": "ellipse",
  "points": [cx, cy, rx, ry]
}

Mask

Binary masks (raster format):

{
  "type": "mask",
  "points": [left, top, right, bottom]
}

Get Annotations

Annotations can be retrieved at different levels:

Get Task Annotations

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

Get Job Annotations

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

Response Format

version

integer

Annotation format version

Create Annotations

Add new annotations using the PATCH endpoint with action=create.

curl -X PATCH "https://app.cvat.ai/api/tasks/{id}/annotations/?action=create" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "shapes": [
      {
        "type": "rectangle",
        "frame": 0,
        "label_id": 1,
        "group": 0,
        "source": "manual",
        "occluded": false,
        "points": [100, 100, 200, 200],
        "attributes": []
      }
    ]
  }'

Path Parameters

integer

required

Task or job identifier

Query Parameters

action

string

required

Must be create

Request Body

shapes

array

Array of shape objects to create

Update Annotations

Modify existing annotations using action=update.

curl -X PATCH "https://app.cvat.ai/api/tasks/{id}/annotations/?action=update" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "shapes": [
      {
        "id": 123,
        "frame": 0,
        "points": [150, 150, 250, 250],
        "occluded": true
      }
    ]
  }'

Query Parameters

action

string

required

Must be update

Request Body

Include the id field for each annotation to update, along with the fields to modify.

Delete Annotations

Remove specific annotations using action=delete.

curl -X PATCH "https://app.cvat.ai/api/tasks/{id}/annotations/?action=delete" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "shapes": [
      {"id": 123},
      {"id": 124}
    ]
  }'

Query Parameters

action

string

required

Must be delete

Replace All Annotations

Replace all annotations in a task or job.

curl -X PUT "https://app.cvat.ai/api/tasks/{id}/annotations/" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 0,
    "tags": [],
    "shapes": [
      {
        "type": "rectangle",
        "frame": 0,
        "label_id": 1,
        "points": [100, 100, 200, 200],
        "occluded": false,
        "group": 0,
        "source": "manual",
        "attributes": []
      }
    ],
    "tracks": []
  }'

This operation replaces ALL existing annotations. Use with caution.

Delete All Annotations

Remove all annotations from a task or job.

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

Import Annotations

Import annotations from various formats.

curl -X POST "https://app.cvat.ai/api/tasks/{id}/annotations/?format=COCO%201.0" \
  -H "Authorization: Token <your_token>" \
  -F "[email protected]"

Supported Import Formats

COCO 1.0
YOLO 1.1
Pascal VOC 1.1
CVAT 1.1
LabelMe 3.0
KITTI 1.0
MOT 1.1
And many more…

Get the full list at: /api/server/annotation/formats

Path Parameters

integer

required

Task or job identifier

Query Parameters

format

string

Import format name

filename

string

Annotation filename (for cloud storage)

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

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

Export Annotations

Export annotations in various formats.

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

Supported Export Formats

COCO 1.0
YOLO 1.1
Pascal VOC 1.1
CVAT 1.1
TFRecord 1.0
Segmentation mask 1.1
And many more…

Query Parameters

format

string

required

Export format name

filename

string

Output filename

save_images

boolean

default:false

Include images in export

location

string

Export location: local or cloud_storage

cloud_storage_id

integer

Cloud storage ID

Response

rq_id

string

Request ID for tracking export status

Working with Tracks

Tracks represent objects that persist across multiple frames.

Create a Track

track = {
    "label_id": 1,
    "frame": 0,
    "group": 0,
    "source": "manual",
    "attributes": [],
    "shapes": [
        {
            "type": "rectangle",
            "frame": 0,
            "points": [100, 100, 200, 200],
            "occluded": False,
            "outside": False,
            "attributes": []
        },
        {
            "type": "rectangle",
            "frame": 1,
            "points": [105, 105, 205, 205],
            "occluded": False,
            "outside": False,
            "attributes": []
        },
        {
            "type": "rectangle",
            "frame": 2,
            "points": [110, 110, 210, 210],
            "occluded": False,
            "outside": False,
            "attributes": []
        }
    ]
}

requests.patch(
    f"https://app.cvat.ai/api/tasks/{task_id}/annotations/",
    headers=headers,
    params={"action": "create"},
    json={"tracks": [track]}
)

Track Properties

outside

boolean

Whether the object is outside the frame (not visible but still tracked)

keyframe

boolean

Whether this frame is a keyframe for interpolation

Example: Batch Annotation

import requests
import json

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

# Create multiple annotations at once
annotations = {
    "shapes": [],
    "tracks": [],
    "tags": []
}

# Add rectangles on different frames
for frame in range(10):
    annotations["shapes"].append({
        "type": "rectangle",
        "frame": frame,
        "label_id": 1,
        "group": 0,
        "source": "auto",
        "occluded": False,
        "points": [100 + frame*10, 100, 200 + frame*10, 200],
        "attributes": []
    })

# Create all annotations
response = requests.patch(
    f"{BASE_URL}/tasks/{task_id}/annotations/",
    headers=HEADERS,
    params={"action": "create"},
    json=annotations
)

print(f"Created {len(annotations['shapes'])} annotations")

# Export to COCO format
export_response = requests.post(
    f"{BASE_URL}/tasks/{task_id}/dataset/export",
    headers=HEADERS,
    params={"format": "COCO 1.0", "save_images": False}
)

rq_id = export_response.json()["rq_id"]
print(f"Export request: {rq_id}")

Get Supported Formats

Retrieve a list of all supported annotation formats:

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

This returns importers and exporters with their specifications and options.

REST API

Python SDK

CLI Tool

​Overview

​Annotation Format

​Shape Types

​Rectangle

​Polygon

​Polyline

​Points

​Cuboid

​Ellipse

​Mask

​Get Annotations

​Get Task Annotations

​Get Job Annotations

​Response Format

​Create Annotations

​Path Parameters

​Query Parameters

​Request Body

​Update Annotations

​Query Parameters

​Request Body

​Delete Annotations

​Query Parameters

​Replace All Annotations

​Delete All Annotations

​Import Annotations

​Supported Import Formats

​Path Parameters

​Query Parameters

​Response

​Export Annotations

​Supported Export Formats

​Query Parameters

​Response

​Working with Tracks

​Create a Track

​Track Properties

​Example: Batch Annotation

​Get Supported Formats

Build docs developers (and LLMs) love

Overview

Annotation Format

Shape Types

Rectangle

Polygon

Polyline

Points

Cuboid

Ellipse

Mask

Get Annotations

Get Task Annotations

Get Job Annotations

Response Format

Create Annotations

Path Parameters

Query Parameters

Request Body

Update Annotations

Query Parameters

Request Body

Delete Annotations

Query Parameters

Replace All Annotations

Delete All Annotations

Import Annotations

Supported Import Formats

Path Parameters

Query Parameters

Response

Export Annotations

Supported Export Formats

Query Parameters

Response

Working with Tracks

Create a Track

Track Properties

Example: Batch Annotation

Get Supported Formats