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/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.

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:

TopicUTMStack v11UTMStack v12
Path prefix/api/.../api/v1/...
Log and alert storageOpenSearch indices (v11-log-, v11-alert-) read through /api/elasticsearch/...Two datasets, logs and alerts, read through /api/v1/log-analyzer/...
Text fieldsSeparate .keyword fields for exact matchesNo .keyword fields. Use the field name as it is.
Relative datesnow-24h and similar were accepted in search filtersSearch filters need absolute times (see Log Search API)
Alert status and severityNumbers (status 2, severity 3)Words ("Open", "high")
Incident idsNumbersUUIDs (36-character identifiers)
API keysAvailable on every editionEnterprise licence only
Postman collection and OpenAPI filePublished for v11The 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 -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.

Endpoint groupPage parameterFirst pagePage size parameterDefault sizeLargest sizeWhere the total is
Log and alert search (POST /log-analyzer/search)page (in the body)0size (in the body)50500total in the JSON answer
SQL search (POST /log-analyzer/search-sql)page (query)1size (query)50500total counts only the rows on this page
Incidents, incident alerts, incident notes, incident historypage1size20200X-Total-Count header
Alert echoes (GET /utm-alerts/{id}/echoes)page1size20100X-Total-Count header
Alert tags and tag rulespage1size20-X-Total-Count header
SOAR flows, executions and variables, saved queriespage0size20200X-Total-Count header
Data sources (GET /datasources)page_number1page_size50500total_items and total_pages in the JSON answer
API keys (GET /api-keys)page1page_size20-page_info in the JSON answer
Users (GET /users)page1page_size20200page_info in the JSON answer
Audit log (GET /audit)page_number1page_size50500total_items and total_pages in the JSON answer
Notifications, identity providers, integrations, User Auditor accountspage0size20200X-Total-Count header
Tenants (GET /tenants)page0size25-X-Total-Count header
Dashboards, widgets, dashboard filterspage0size20200X-Total-Count header
Correlation rules (GET /eventprocessing/correlation-rule/search-by-filters)page0sizeevery rule when size is left out-X-Total-Count header
Pipelines (GET /eventprocessing/pipelines)page1size50-X-Total-Count header
Grok patterns (GET /eventprocessing/regex-pattern)page0size20200X-Total-Count header
Compliance report schedulespage0size20-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 codeMeaningCommon cause
200Success
201CreatedA new record was created
202AcceptedWork was started and continues in the background (flow runs, SOC-AI analysis)
204Success, no bodyDeletes and some updates
400Bad requestMissing or invalid field, unknown filter operator, invalid field name, refused SQL
401Not signed inMissing, invalid or expired token or API key
403ForbiddenMissing permission, missing Enterprise licence, read-only shipped item, or the tenant is suspended
404Not foundUnknown id, or (multi-tenant installations) an address that belongs to no tenant
409ConflictName already in use, or alerts already linked to an incident
410GoneA password reset key that has expired
413, 415Too large, wrong typeAn uploaded image or file that is too large or of a type that is not accepted (branding, profile picture)
429Too many requestsToo many failed sign-ins, or the daily AI allowance is used up
500Server errorSee the message; in UTMStack v12.0.2 some invalid values are also answered with 500 (noted on each page)
502, 503, 504Service unavailable or gateway errorA 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:

RolePermissions
AdministratorEverything
AnalystEvery .read permission, plus alerts.write, incidents.write, soar.write, loganalyzer.write, dashboards.write and notifications.write
ViewerEvery .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, 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

PageWhat it covers
API Quick StartFirst calls, paging and error handling in ten minutes
Authentication and API KeysSigning in with a token or an API key, creating and rotating keys
Alerts APISearching alerts, changing status, notes, tags, assignment, echoes, related logs
Log Search APIDatasets, fields, search, SQL, top values, charts, saved queries
Incidents APICreating incidents, linking alerts, status, assignment, notes, history
Data Sources APIData sources and agents, data types, ingestion statistics
Integrations APIIntegration catalogue, cloud integration settings, Collector log types and certificates
Rules and Pipelines APICorrelation rules, pipelines, grok patterns, import and export, rule and pipeline tests
Dashboards APIDashboards, widgets, filters and widget queries
Compliance APIControls, frameworks, evaluations, verdicts, PDF reports and schedules
SOAR APIResponse flows, starting a flow by hand, execution history, variables, the command console
SOC-AI APIAssistant chat, alert analysis, AI provider configuration, daily usage
Threat Intelligence APIIndicator search and lookup, reports, feeds, AI Analyst
User Auditor APIDirectory accounts, statistics and identities
Users and Roles APIUsers, roles, permissions, your own profile, sessions and two-step sign-in
Identity Providers APISAML, OpenID Connect and LDAP providers and group mappings
Tenants APITenants and support access (multi-tenant licence)
Settings, Branding and Licence APIApplication settings, email test, branding, version and licence
Audit Log and Notifications APIAudit log entries and in-app notifications
Storage and Retention APIRetention periods, storage use and cold storage
Reference TablesStatus values, filter operators, alert fields, endpoint list, v11-to-v12 path map