Server API

Overview

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:

CVAT server interaction image

API schema

You can obtain schema for your server at <yourserver>/api/docs. For example, the official CVAT.ai application has API documentation here.

Examples

Here you can see how a task is created in CVAT:

Task creation example

  1. At first, we have to login
  2. Then we create a task from its configuration
  3. Then we send task data (images, videos etc.)
  4. We wait for data processing and finish

Design principles

Common pattern for our REST API is <VERB> [namespace] <objects> <id> <action>.

  • VERB can be POST, GET, PATCH, PUT, DELETE.
  • namespace should scope some specific functionality like auth, lambda. It is optional in the scheme.
  • Typical objects are tasks, projects, jobs.
  • When you want to extract a specific object from a collection, just specify its id.
  • An action can be used to simplify REST API or provide an endpoint for entities without objects endpoint like annotations, data, 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/tasks instead of POST /api/tasks/create.
  • Accept and respond with JSON whenever it is possible
  • Name collections with plural nouns (e.g. /tasks, /projects)
  • Try to keep the API structure flat. Prefer two separate endpoints for /projects and /tasks instead of /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 :id1 and :id2 to get information about the task. Note: for now we accept GET /tasks/:id2/jobs but it should be replaced by /jobs?task=:id2 in the future.
  • Handle errors gracefully and return standard error codes (e.g. 201, 400)
  • 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 Accept header with vendor media type.