Skip to main content

​
Introduction

The UTMStack API provides comprehensive access to security operations and alert management functionality. This documentation covers all available endpoints for integrating with UTMStack programmatically.
All API endpoints require authentication via Bearer tokens. See the Authentication section for details on obtaining access tokens.

​
API Base URL

The UTMStack API is available at: 
https://your-utmstack-instance.com/api
Replace your-utmstack-instance.com with your actual UTMStack instance URL.

​
Quick Start Guide

Get up and running with the UTMStack API in just a few steps:
1

Authenticate

Use your UTMStack credentials to obtain a JWT token
curl -X POST https://your-utmstack-instance.com/api/authenticate \
  -H "Content-Type: application/json" \
  -d '{"username":"your_username","password":"your_password"}'
2

Store Token

Save the returned id_token for use in subsequent requests
{
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "authenticated": true
}
3

Make API Calls

Use the token in the Authorization header for protected endpoints
curl -X POST "https://your-utmstack-instance.com/api/elasticsearch/search" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

​
Available Endpoints

Authentication

Obtain JWT tokens for API access

List Alerts

Search and retrieve alerts with filtering

Update Status

Change alert status (Open, In Review, Completed)

Update Tags

Add or modify alert tags and create rules

Update Notes

Add investigation notes to alerts

Convert to Incident

Convert alerts into security incidents

Count Alerts

Get count of open alerts for dashboards

Property Values

Analyze field values and their distributions

CSV Export

Export alert data to CSV for reporting

​
📦 Postman Collection

Get started quickly by importing our complete Postman collection that includes all API endpoints with pre-configured examples, authentication, and test scripts.

Download UTMStack Alerts API Collection

Complete Postman Collection (JSON)
Includes all 9 API endpoints with examples, authentication setup, and automated tests.
What’s included:
  • 🔐 JWT authentication with automatic token management
  • 📋 Pre-configured examples for all endpoints
  • 🧪 Automated test scripts for response validation
  • 📊 Multiple scenarios for each API call
  • 🔧 Environment variables for easy configuration
Download Tip: If your browser displays the JSON instead of downloading it, right-click the link above and select “Save link as…” to save the file to your computer.

​
How to Import

1

Download Collection

Click the download link above to get the JSON file
2

Open Postman

Launch Postman application or visit web.postman.co
3

Import Collection

  • Click “Import” button in Postman
  • Select “Upload Files”
  • Choose the downloaded JSON file
  • Click “Import”
4

Configure Environment

Set up collection variables:
  • baseUrl: Your UTMStack instance URL
  • bearerToken: Will be set automatically after authentication
  • alertId: Sample alert ID for testing
5

Start Testing

Run the “Authentication” request first, then explore other endpoints
Pro Tip: The collection includes pre-request scripts that automatically handle authentication token management. Just run the authentication request once, and all other requests will use the token automatically.

​
Authentication Overview

All API requests (except the authentication endpoint itself) require a valid Bearer token in the Authorization header: 
Authorization: Bearer <your_jwt_token>

​
Quick Start Example

curl -X POST https://your-utmstack-instance.com/api/authenticate \
  -H "Content-Type: application/json" \
  -d '{"username":"your_username","password":"your_password"}'

{
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VybmFtZSIsImF1dGgiOiJST0xFX0FETUlOIn0.signature",
  "authenticated": true
}

​
Additional Language Examples

# 1. Get authentication token
curl -X POST https://your-utmstack-instance.com/api/authenticate \
  -H "Content-Type: application/json" \
  -d '{"username":"your_username","password":"your_password"}'

# 2. Use token in requests
curl -X POST "https://your-utmstack-instance.com/api/elasticsearch/search?page=1&size=25&indexPattern=alert-*" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '[{"field":"status","operator":"IS","value":2}]'

​
Common Response Codes

  • 200 OK: Request completed successfully
  • 201 Created: Resource created successfully
  • 204 No Content: Request successful, no response body
  • 400 Bad Request: Invalid request format or parameters
  • 401 Unauthorized: Missing or invalid authentication token
  • 403 Forbidden: Insufficient permissions for the requested operation
  • 404 Not Found: Requested resource does not exist
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Unexpected server error
  • 502 Bad Gateway: Upstream service unavailable
  • 503 Service Unavailable: Service temporarily unavailable

​
Request/Response Format

​
Content Type

All API requests and responses use JSON format: 
Content-Type: application/json

​
Request Structure

Most endpoints expect JSON in the request body: 
{
  "field": "value",
  "array": ["item1", "item2"],
  "nested": {
    "property": "value"
  }
}

​
Response Structure

Successful responses typically return:
  • Search endpoints: Array of objects
  • Update endpoints: HTTP 200 with empty body
  • Error responses: JSON object with error details

​
Rate Limiting

UTMStack implements rate limiting to ensure API stability. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

​
Best Practices

  • Implement exponential backoff for retries
  • Cache authentication tokens instead of re-authenticating for each request
  • Batch operations when possible to reduce API calls
  • Use appropriate page sizes for search operations

​
Error Handling

​
Standard Error Response

{
  "error": "Error description",
  "message": "Detailed error message",
  "timestamp": "2024-10-16T10:30:00.000Z",
  "status": 400
}

​
Error Handling Example

try {
  const response = await fetch('/api/utm-alerts/status', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(`API Error ${response.status}: ${errorData.message}`);
  }

  console.log('Success!');
} catch (error) {
  console.error('Failed to update alert:', error.message);
  
  // Handle specific error codes
  if (error.message.includes('401')) {
    // Token expired, re-authenticate
    await refreshAuthToken();
  } else if (error.message.includes('429')) {
    // Rate limited, wait and retry
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

​
SDK and Libraries

Currently, UTMStack provides REST API endpoints. Community SDKs and libraries may be available for specific programming languages.
  • JavaScript: fetch, axios
  • Python: requests, httpx
  • Java: OkHttp, Apache HttpClient
  • C#: HttpClient
  • Go: net/http
  • PHP: Guzzle, cURL

​
Support and Resources

Support Portal

Get help with API integration and troubleshooting

Status Codes Reference

Complete list of HTTP status codes and meanings

Authentication Guide

Detailed authentication setup and token management

Examples Repository

Sample code and integration examples

​
Version Information

  • API Version: v1.0
  • Documentation Version: 2025.10
  • Last Updated: October 2025
This documentation is actively maintained. Check back regularly for updates and new endpoint additions.
⌘I