CVAT server provides HTTP REST API for interaction. Each client application - be it a command line tool, browser or a script - all interact with CVAT via HTTP requests and responses:
You can obtain schema for your server at
<yourserver>/api/docs. For example,
the official CVAT.ai application has API documentation here.
Here you can see how a task is created in CVAT:
- At first, we have to login
- Then we create a task from its configuration
- Then we send task data (images, videos etc.)
- We wait for data processing and finish
Common pattern for our REST API is
<VERB> [namespace] <objects> <id> <action>.
namespaceshould scope some specific functionality like
lambda. It is optional in the scheme.
- When you want to extract a specific object from a collection, just specify its
actioncan be used to simplify REST API or provide an endpoint for entities without
data/meta. Note: action should not duplicate other endpoints without a reason.
When you’re developing new endpoints, follow these guidelines:
- Use nouns instead of verbs in endpoint paths. For example,
POST /api/tasksinstead of
- Accept and respond with JSON whenever it is possible
- Name collections with plural nouns (e.g.
- Try to keep the API structure flat. Prefer two separate endpoints
/projects/:id1/tasks/:id2. Use filters to extract necessary information like
/tasks/:id2?project=:id1. In some cases it is useful to get all
tasks. If the structure is hierarchical, it cannot be done easily. Also you have to know both
:id2to get information about the task. Note: for now we accept
GET /tasks/:id2/jobsbut it should be replaced by
/jobs?task=:id2in the future.
- Handle errors gracefully and return standard error codes (e.g.
- Allow filtering, sorting, and pagination
- Maintain good security practices
- Cache data to improve performance
- Versioning our APIs. It should be done when you delete an endpoint or modify
its behaviors. Versioning uses a schema with
Acceptheader with vendor media type.
- Best practices for REST API design
- Flat vs. nested resources
- REST API Design Best Practices for Sub and Nested Resources
- A specification for building APIs in JSON