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

integer

Annotation format version

array

Array of image-level tags

integer

Frame number

integer

Label identifier

integer

Group identifier for related annotations

string

Annotation source: manual, auto, or file

array

Array of attribute values

array

Array of shape annotations

string

Shape type: rectangle, polygon, polyline, points, cuboid, ellipse, or mask

integer

Frame number

integer

Label identifier

array

Array of coordinate values

boolean

Whether the object is occluded

integer

Group identifier

string

Annotation source

array

Array of attribute values

array

Array of tracked objects across frames

integer

Label identifier

integer

Starting frame number

integer

Group identifier

string

Annotation source

array

Array of shape positions per frame

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

import requests

shapes = [{
    "type": "rectangle",
    "frame": 0,
    "label_id": 1,
    "group": 0,
    "source": "manual",
    "occluded": False,
    "points": [100, 100, 200, 200],
    "attributes": []
}]

response = requests.patch(
    f"https://app.cvat.ai/api/tasks/{task_id}/annotations/",
    headers={"Authorization": "Token <your_token>"},
    params={"action": "create"},
    json={"shapes": shapes}
)

Path Parameters

integer

required

Task or job identifier

Query Parameters

string

required

Must be create

Request Body

array

Array of shape objects to create

array

Array of tag objects to create

array

Array of track 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

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

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

curl -X DELETE "https://app.cvat.ai/api/jobs/{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 "annotation_file=@annotations.json"

import requests

with open('annotations.json', 'rb') as f:
    response = requests.post(
        f"https://app.cvat.ai/api/tasks/{task_id}/annotations/",
        headers={"Authorization": "Token <your_token>"},
        params={"format": "COCO 1.0"},
        files={"annotation_file": f}
    )
rq_id = response.json()["rq_id"]
print(f"Import started: {rq_id}")

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

string

Import format name

string

Annotation filename (for cloud storage)

string

Import location: local or cloud_storage

integer

Cloud storage ID

Response

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

string

required

Export format name

string

Output filename

boolean

default:false

Include images in export

string

Export location: local or cloud_storage

integer

Cloud storage ID

Response

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

boolean

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

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.

​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

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