This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

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.