Your first API request

The external API lets your own program manage data collection: create sites and scenarios, start runs, set schedules, configure proxies, and prepare exports. It uses the same permissions and limits as the interface.

Base URL and headers

The base path is /api/v1 on your installation's domain. Locally it is http://localhost:8701/api/v1. Use HTTPS on a public installation.

1. Open Tokens → API keys in the relevant workspace.
2. Create a key. Leave write access disabled if you only need to read data.
3. Copy the secret: its full value is shown only once, when created.
4. Send it in the Authorization: Bearer … header. Never put it in a URL.

curl "$BASE/api/v1/sites" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Accept: application/json'

BASE is the installation URL without a trailing slash; API_KEY is your key. Store both in protected environment variables. You do not need a browser cookie, user password, or CSRF token.

For JSON requests, add Content-Type: application/json. Use IDs from your own installation's responses, not from these examples.

UUIDs and compatibility

For a new integration use /api/v2: it returns public UUIDs by default. Existing v1 clients keep numeric responses without an additional header. Send X-Identifier-Format: uuid to select UUIDs in v1. Resource references also accept short ~Base58 values. Identifier formats and migration.

OpenAPI and Postman

Select Download next to the documentation version, or Open in the banner. The dialog offers the complete OpenAPI 3.1 JSON specification, a Postman collection, and an optional environment template for the selected release. Choose a format: follow the download percentage. When it completes, the standard file save opens automatically. You can dismiss the banner; Download remains available next to the version. This English page downloads English files. The Russian page downloads Russian files. The numeric v1 contract without the new header is preserved. Downloads also include v2 methods with UUID schemas.

Postman groups requests into folders and creates collection variables during import. Set base_url, api_key, export_token, and the resource IDs you need. Keys and passwords are empty in the files; enter them only in your local tools. The environment template is imported separately and marks secrets accordingly. OpenAPI uses topic tags and server variables protocol and host.

Query parameters without an example are initially disabled. JSON body variables have the prefix of their operation and body_; arrays and objects use a JSON value. Before sending, a script builds the body with correct escaping and types, omits empty optional variables, and requires mandatory values. Use null for a nullable field and "" for an empty string. Requests run only when you send them. Review the request before sending a mutating operation.

Two different tokens

An export token does not grant management access. An API key does not replace the token for a direct catalog endpoint.

Next: permissions and security, complete collection workflow.