Skip to main content
Skip table of contents

General description of API

API Handbook

API is a set of functions that help understand how to interact with a program, including:

  • Operation that can be performed

  • Data received as input

  • Data returned as output (data content or error message)

VSaaS product API is organized based on REST.

REST API handles almost all interactions between server and client applications (the server application provides access to its data to the client application through a specific URL).

The VMS product API has predictable URLs oriented towards resources, returns responses in JSON format, uses standard HTTP response codes, and authentication.

All requests must have the header: Accept: application/json

This is necessary for the backend to understand whether the client supports responses in JSON format. If this header is not included, errors will be returned as an HTML page.


Authentication in the API is done through a bearer token. It needs to be sent in the Authorization header.

Example: Authorization: Bearer eyJ0eXAiSUzI1NiJ9.eyJhdWQi.MHbBUJNRGEl2giGXN3uE

Requests that require authentication but don't provide a token or provide an incorrect one will result in an error with status 401.


VMS supports multilingualism (the Russian and English languages). To change the language of the received responses, such as errors or resources, the Hl header or the hl parameter in the request needs to be sent.


In the header - Hl: en

In the GET parameter - http://localhost/api/v1/items?hl=en


VMS uses standard HTTP response codes to indicate the success or failure of an API request.

  • Codes in the 2xx range indicate success.

  • Codes in the 4xx range indicate an error in the request that failed considering the provided information (e.g., a mandatory parameter was not specified).

  • Codes in the 5xx range indicate technical errors, mostly related to VSaaS servers (they are rarely encountered).

Example of a response with a 4xx status

    "message": "The given data was invalid.",
    "errors": {
        "title": [
            "The title field is required."

List of HTTP codes and their meanings

200, 201, 204 - OK

The process completed successfully.

400 - Bad Request

The request could not be completed. This is often related to the incorrect operation of external systems.

401 - Unauthorized

The API token provided is incorrect.

402 - Payment Required

The license limit for creating cameras has been exceeded, or there is a problem with the license.

422 - Unprocessable Entity

The data provided in the request is invalid.

403 - Forbidden

The API token does not have permission to execute the request.

404 - Not Found

The requested resource does not exist.

429 - Too Many Requests

Too many requests are being sent to the API too quickly.

500, 502, - Server Errors

Something went wrong on the VSaaS side (rare).

503 - Service unavailable

Technical work is being performed. The system is being updated or issues are being resolved.


All API resources support bulk retrieval using the list API methods. These API methods have a common structure, accepting at least two parameters: page and per_page.

    "data": [
    "links": {
        "first": "https://localhost/url?page=1",
        "last": "https://localhost/url?page=4",
        "prev": null,
        "next": "https://localhost/url?page=2"
    "meta": {
        "current_page": 1,
        "from": 1,
        "to": 25,
        "last_page": 4,
        "path": "https://localhost/url",
        "per_page": 25,
        "total": 86

Response format:

  • data – an array of requested objects

  • links (all links in this object contain data in the GET parameters that were sent for filtering/sorting on this request):

    • first – link to the first page

    • last – link to the last page

    • prev – link to the previous page

    • next – link to the next page

  • meta:

    • current_page – current page number

    • from – number of the element from which this page starts

    • to – number of the element at which this page ends

    • last_page – last page number

    • path – URL of the request without any parameters

    • per_page – number of items per page

    • total – total number of items corresponding to the request

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.