Skip to main content

​
Introduction

The CVAT REST API provides programmatic access to all Computer Vision Annotation Tool features. You can use the API to create and manage projects, tasks, jobs, annotations, and more.

​
Base URL

All API requests should be made to: 
https://app.cvat.ai/api
For self-hosted instances, replace the domain with your instance URL.

​
API Version

The current API version is 2.58.1. The API version follows semantic versioning and is included in the response headers and documentation.

​
Request Format

All requests should include the appropriate Content-Type header:
  • application/json for JSON payloads
  • multipart/form-data for file uploads
  • application/vnd.cvat+json for CVAT-specific content

​
Response Format

All API responses use the application/vnd.cvat+json content type and return JSON-formatted data.

​
Success Responses

  • 200 OK - Request succeeded
  • 201 Created - Resource created successfully
  • 202 Accepted - Request accepted, processing asynchronously
  • 204 No Content - Request succeeded with no response body

​
Error Responses

  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Authentication required
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 405 Method Not Allowed - HTTP method not supported
  • 409 Conflict - Request conflicts with current state
  • 410 Gone - Resource no longer available

​
Example Response

{
  "id": 1,
  "name": "My Project",
  "owner": {
    "id": 1,
    "username": "admin"
  },
  "created_date": "2024-01-15T10:30:00Z",
  "updated_date": "2024-01-15T10:30:00Z"
}

​
Pagination

List endpoints support pagination with the following query parameters:
​
page
integer
Page number within the paginated result set
​
page_size
integer
Number of results to return per page

​
Paginated Response Format

{
  "count": 100,
  "next": "https://app.cvat.ai/api/projects?page=2",
  "previous": null,
  "results": [
    // Array of resources
  ]
}

​
Filtering

Many endpoints support advanced filtering using JSON Logic syntax:
​
filter
string
JSON Logic filter expression for complex queries

​
Example Filter

Get all resources created by a specific user: 
{"and":[{"==":[{"var":"owner"},"username"]}]}

​
Sorting

List endpoints support sorting with the sort parameter:
​
sort
string
Field name to sort by (prefix with - for descending order)

​
Example

/api/projects?sort=-updated_date
Many endpoints support text search:
​
search
string
Search term to filter results

​
Organizations

When working within an organization context, include the organization identifier:
​
X-Organization
string
Organization unique slug
Alternatively, use query parameters:
​
org
string
Organization unique slug
​
org_id
integer
Organization identifier

​
Asynchronous Operations

Some operations (imports, exports, backups) are processed asynchronously and return a request ID: 
{
  "rq_id": "abc123-def456"
}
Check the operation status: 
curl -X GET "https://app.cvat.ai/api/requests/abc123-def456" \
  -H "Authorization: Token <your_token>"

​
Rate Limiting

API requests may be subject to rate limiting. Check response headers for rate limit information:
  • X-RateLimit-Limit - Maximum requests allowed
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - Time when limit resets

​
Next Steps

Authentication

Learn how to authenticate API requests

Projects

Manage annotation projects

Tasks

Create and manage annotation tasks

Annotations

Work with annotation data

Build docs developers (and LLMs) love

Get started for freeTalk to us