UTMStack v12 has a REST API (a set of web addresses that programs call over HTTPS) for alerts, logs, incidents, data sources, automated response (SOAR) and the SOC-AI assistant. This page explains the base address, how requests and answers are shaped, how paging works and what the error codes mean. It does not apply to the old UTMStack Vulnerability Scanner, which is not part of UTMStack v12.

Base address

Every endpoint lives under /api/v1 on the same address and port (443) that you use for the web console:

https://<your-utmstack-address>/api/v1

All examples in this section use {{baseUrl}} for https://<your-utmstack-address> and {{apiKey}} for your API key. Replace them before you run a command.

What changed from UTMStack v11

If you are porting code written for UTMStack v11, these are the changes that affect almost every call:

Check that the API answers

The health endpoint needs no sign-in. Use it to test the address and the certificate before you set up a key.

curl -sk "{{baseUrl}}/api/v1/health"

Response (HTTP 200):

{"status":"ok"}

The old address {{baseUrl}}/api/ping still works. It is forwarded to /api/v1/health and returns the same JSON. In UTMStack v11 it returned the text OK.

To see the installed version and edition, call GET /api/v1/billing/version (any signed-in user):

curl -sk "{{baseUrl}}/api/v1/billing/version" 
  -H "Utm-Api-Key: {{apiKey}}"

Response (HTTP 200):

{
  "version": "<version>",
  "edition": "enterprise",
  "server": "<server-name>",
  "instanceId": "<instance-id>"
}

edition is community or enterprise.

Interactive reference

The server also publishes an interactive reference at {{baseUrl}}/swagger/index.html.

Request conventions

• Authentication. Every endpoint except /health needs a credential. See Authentication and API Keys.

• Request bodies are JSON. Send Content-Type: application/json. The one exception is alert notes, which take plain text (see Alerts API).

• Times are written in RFC 3339 format in UTC, for example 2026-11-10T14:30:00Z.

• Self-signed certificates. If your server uses a self-signed certificate, add -k to curl commands (the examples use -sk).

• Calls from web pages on other sites are refused. The server does not allow cross-site browser requests (CORS). Call the API from a script, a server or a command-line tool, not from JavaScript running on another website.

Paging

Paging is not the same for every group of endpoints. Each page in this section says which style its endpoints use.

Errors

Most errors come back as JSON with one field:

{"error": "missing required permission: alerts.write"}

The SOC-AI endpoints use a different shape:

{"status": "error", "message": "task is required"}

Roles and permissions

Each endpoint needs a permission. The pages in this section name it next to each endpoint. The three built-in roles get these permissions:

Some actions are limited further: starting a flow by hand (soar.execute) and creating API keys (apikey.write) are given to Administrator only.

Multi-tenant installations

On an installation with the multi-tenant licence, each tenant has its own address (domain).

• The tenant comes from your credential. Send the request to your tenant's own address. A credential sent to another tenant's address is refused with 401 and the message credential does not belong to this tenant.

• A request to an address that belongs to no tenant is answered with 404 unknown tenant.

• An administrator of the default (platform) tenant who signed in with a token can work inside another tenant that granted support access, by adding the header X-Tenant-Id: <tenant-id>. With read-only support access, only GET requests are allowed.

• API keys cannot switch tenant. A key always works inside its owner's tenant.

• When a tenant is suspended or terminated, its users' tokens and API keys stop working at once (403 this tenant has been suspended or terminated).

Pages in this section