Introduction
UTMStack v12 has a REST API (a set of web addresses that programs call over HTTPS) for almost everything the web console does: alerts, logs, incidents, data sources, rules and pipelines, automated response (SOAR), the SOC-AI assistant, dashboards, compliance, integrations, users and roles, settings, storage and, on multi-tenant installations, tenants. 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/v1All examples in this section use {{baseUrl}} for https://<your-utmstack-address> and {{apiKey}} for your API key. Replace them before you run a command.
UTMStack v11 endpoints had no version in the path (for example /api/utm-alerts/status). In UTMStack v12 every path starts with /api/v1. See Reference Tables for a full map from v11 paths to v12 paths.
What changed from UTMStack v11
If you are porting code written for UTMStack v11, these are the changes that affect almost every call:
| Topic | UTMStack v11 | UTMStack v12 |
|---|---|---|
| Path prefix | /api/... | /api/v1/... |
| Log and alert storage | OpenSearch indices (v11-log-, v11-alert-) read through /api/elasticsearch/... | Two datasets, logs and alerts, read through /api/v1/log-analyzer/... |
| Text fields | Separate .keyword fields for exact matches | No .keyword fields. Use the field name as it is. |
| Relative dates | now-24h and similar were accepted in search filters | Search filters need absolute times (see Log Search API) |
| Alert status and severity | Numbers (status 2, severity 3) | Words ("Open", "high") |
| Incident ids | Numbers | UUIDs (36-character identifiers) |
| API keys | Available on every edition | Enterprise licence only |
| Postman collection and OpenAPI file | Published for v11 | The v11 files do not apply to UTMStack v12 |
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.
In UTMStack v12.0.2 the interactive reference is incomplete and partly out of date. Some live endpoints are missing from it, for example starting a flow by hand (POST /soar/rules/{relPath}/trigger), assigning an alert (POST /utm-alerts/assignee) and listing data sources (GET /datasources). It also still lists an endpoint that no longer exists. Where it differs from these pages, these pages describe how the server behaves.
Request conventions
Authentication. Every endpoint needs a credential, except
/health, the sign-in and password-reset endpoints, and the few that the sign-in page reads before anyone signs in (branding, date format, the list of sign-in providers). See Authentication and API Keys.Request bodies are JSON. Send
Content-Type: application/json. The exceptions are alert notes, which take plain text (see Alerts API), and file uploads (licence, branding images, profile picture), which are sent as a multipart form.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
-kto 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.
| Endpoint group | Page parameter | First page | Page size parameter | Default size | Largest size | Where the total is |
|---|---|---|---|---|---|---|
Log and alert search (POST /log-analyzer/search) | page (in the body) | 0 | size (in the body) | 50 | 500 | total in the JSON answer |
SQL search (POST /log-analyzer/search-sql) | page (query) | 1 | size (query) | 50 | 500 | total counts only the rows on this page |
| Incidents, incident alerts, incident notes, incident history | page | 1 | size | 20 | 200 | X-Total-Count header |
Alert echoes (GET /utm-alerts/{id}/echoes) | page | 1 | size | 20 | 100 | X-Total-Count header |
| Alert tags and tag rules | page | 1 | size | 20 | - | X-Total-Count header |
| SOAR flows, executions and variables, saved queries | page | 0 | size | 20 | 200 | X-Total-Count header |
Data sources (GET /datasources) | page_number | 1 | page_size | 50 | 500 | total_items and total_pages in the JSON answer |
API keys (GET /api-keys) | page | 1 | page_size | 20 | - | page_info in the JSON answer |
Users (GET /users) | page | 1 | page_size | 20 | 200 | page_info in the JSON answer |
Audit log (GET /audit) | page_number | 1 | page_size | 50 | 500 | total_items and total_pages in the JSON answer |
| Notifications, identity providers, integrations, User Auditor accounts | page | 0 | size | 20 | 200 | X-Total-Count header |
Tenants (GET /tenants) | page | 0 | size | 25 | - | X-Total-Count header |
| Dashboards, widgets, dashboard filters | page | 0 | size | 20 | 200 | X-Total-Count header |
Correlation rules (GET /eventprocessing/correlation-rule/search-by-filters) | page | 0 | size | every rule when size is left out | - | X-Total-Count header |
Pipelines (GET /eventprocessing/pipelines) | page | 1 | size | 50 | - | X-Total-Count header |
Grok patterns (GET /eventprocessing/regex-pattern) | page | 0 | size | 20 | 200 | X-Total-Count header |
| Compliance report schedules | page | 0 | size | 20 | - | X-Total-Count header |
Compliance controls, frameworks and reports, roles, settings, configuration groups, identities, retention and storage use return the whole list without paging.
For incident lists, users, grok patterns and some other lists, a size larger than the maximum is not reduced to the maximum: the server falls back to the default of 20. Ask for the maximum or less.
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"}| HTTP code | Meaning | Common cause |
|---|---|---|
| 200 | Success | |
| 201 | Created | A new record was created |
| 202 | Accepted | Work was started and continues in the background (flow runs, SOC-AI analysis) |
| 204 | Success, no body | Deletes and some updates |
| 400 | Bad request | Missing or invalid field, unknown filter operator, invalid field name, refused SQL |
| 401 | Not signed in | Missing, invalid or expired token or API key |
| 403 | Forbidden | Missing permission, missing Enterprise licence, read-only shipped item, or the tenant is suspended |
| 404 | Not found | Unknown id, or (multi-tenant installations) an address that belongs to no tenant |
| 409 | Conflict | Name already in use, or alerts already linked to an incident |
| 410 | Gone | A password reset key that has expired |
| 413, 415 | Too large, wrong type | An uploaded image or file that is too large or of a type that is not accepted (branding, profile picture) |
| 429 | Too many requests | Too many failed sign-ins, or the daily AI allowance is used up |
| 500 | Server error | See the message; in UTMStack v12.0.2 some invalid values are also answered with 500 (noted on each page) |
| 502, 503, 504 | Service unavailable or gateway error | A service behind the API could not be reached or timed out: SOC-AI, the agent manager, ThreatWinds, the mail server, or a rule test that waited for the busy test engine |
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:
| Role | Permissions |
|---|---|
| Administrator | Everything |
| Analyst | Every .read permission, plus alerts.write, incidents.write, soar.write, loganalyzer.write, dashboards.write and notifications.write |
| Viewer | Every .read permission |
Some actions are limited further: starting a flow by hand (soar.execute) and creating API keys (apikey.write) are given to Administrator only. Some endpoints also need a licence (Enterprise or multi-tenant) or an Administrator of the default tenant (called "platform" on these pages). API Quick Start has a summary, and Users and Roles API lists every permission.
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, onlyGETrequests 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
| Page | What it covers |
|---|---|
| API Quick Start | First calls, paging and error handling in ten minutes |
| Authentication and API Keys | Signing in with a token or an API key, creating and rotating keys |
| Alerts API | Searching alerts, changing status, notes, tags, assignment, echoes, related logs |
| Log Search API | Datasets, fields, search, SQL, top values, charts, saved queries |
| Incidents API | Creating incidents, linking alerts, status, assignment, notes, history |
| Data Sources API | Data sources and agents, data types, ingestion statistics |
| Integrations API | Integration catalogue, cloud integration settings, Collector log types and certificates |
| Rules and Pipelines API | Correlation rules, pipelines, grok patterns, import and export, rule and pipeline tests |
| Dashboards API | Dashboards, widgets, filters and widget queries |
| Compliance API | Controls, frameworks, evaluations, verdicts, PDF reports and schedules |
| SOAR API | Response flows, starting a flow by hand, execution history, variables, the command console |
| SOC-AI API | Assistant chat, alert analysis, AI provider configuration, daily usage |
| Threat Intelligence API | Indicator search and lookup, reports, feeds, AI Analyst |
| User Auditor API | Directory accounts, statistics and identities |
| Users and Roles API | Users, roles, permissions, your own profile, sessions and two-step sign-in |
| Identity Providers API | SAML, OpenID Connect and LDAP providers and group mappings |
| Tenants API | Tenants and support access (multi-tenant licence) |
| Settings, Branding and Licence API | Application settings, email test, branding, version and licence |
| Audit Log and Notifications API | Audit log entries and in-app notifications |
| Storage and Retention API | Retention periods, storage use and cold storage |
| Reference Tables | Status values, filter operators, alert fields, endpoint list, v11-to-v12 path map |