> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insecureweb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Documentation Overview

> Complete guide to UTMStack's API endpoints for managing alerts, authentication, and security operations programmatically.

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

<Note>
  All API endpoints require authentication via Bearer tokens. See the [Authentication](/v10/apidoc/authentication) section for details on obtaining access tokens.
</Note>

***

## API Base URL

The UTMStack API is available at:

```
https://your-utmstack-instance.com/api
```

<Warning>
  Replace `your-utmstack-instance.com` with your actual UTMStack instance URL.
</Warning>

***

## Quick Start Guide

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

<Steps>
  <Step title="Authenticate">
    Use your UTMStack credentials to obtain a JWT token

    ```bash theme={null}
    curl -X POST https://your-utmstack-instance.com/api/authenticate \
      -H "Content-Type: application/json" \
      -d '{"username":"your_username","password":"your_password"}'
    ```
  </Step>

  <Step title="Store Token">
    Save the returned `id_token` for use in subsequent requests

    ```json theme={null}
    {
      "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "authenticated": true
    }
    ```
  </Step>

  <Step title="Make API Calls">
    Use the token in the Authorization header for protected endpoints

    ```bash theme={null}
    curl -X POST "https://your-utmstack-instance.com/api/elasticsearch/search" \
      -H "Authorization: Bearer YOUR_TOKEN_HERE" \
      -H "Content-Type: application/json"
    ```
  </Step>
</Steps>

***

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/v10/apidoc/authentication">
    Obtain JWT tokens for API access
  </Card>

  <Card title="List Alerts" icon="magnifying-glass" href="/v10/apidoc/alerts-list">
    Search and retrieve alerts with filtering
  </Card>

  <Card title="Update Status" icon="refresh" href="/v10/apidoc/update-status">
    Change alert status (Open, In Review, Completed)
  </Card>

  <Card title="Update Tags" icon="tags" href="/v10/apidoc/update-tags">
    Add or modify alert tags and create rules
  </Card>

  <Card title="Update Notes" icon="note-sticky" href="/v10/apidoc/update-notes">
    Add investigation notes to alerts
  </Card>

  <Card title="Convert to Incident" icon="exclamation-triangle" href="/v10/apidoc/convert-incident">
    Convert alerts into security incidents
  </Card>

  <Card title="Count Alerts" icon="calculator" href="/v10/apidoc/count-alerts">
    Get count of open alerts for dashboards
  </Card>

  <Card title="Property Values" icon="chart-bar" href="/v10/apidoc/property-values">
    Analyze field values and their distributions
  </Card>

  <Card title="CSV Export" icon="download" href="/v10/apidoc/csv-export">
    Export alert data to CSV for reporting
  </Card>
</CardGroup>

***

## 📦 Postman Collection

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

<Card title="Download UTMStack Alerts API Collection" icon="download" href="/images/downloads/postman.json">
  **Complete Postman Collection (JSON)**\
  Includes all 9 API endpoints with examples, authentication setup, and automated tests.

  <br />

  **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

  <Tip>
    **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.
  </Tip>
</Card>

### How to Import

<Steps>
  <Step title="Download Collection">
    Click the download link above to get the JSON file
  </Step>

  <Step title="Open Postman">
    Launch Postman application or visit [web.postman.co](https://web.postman.co)
  </Step>

  <Step title="Import Collection">
    * Click "Import" button in Postman
    * Select "Upload Files"
    * Choose the downloaded JSON file
    * Click "Import"
  </Step>

  <Step title="Configure Environment">
    Set up collection variables:

    * `baseUrl`: Your UTMStack instance URL
    * `bearerToken`: Will be set automatically after authentication
    * `alertId`: Sample alert ID for testing
  </Step>

  <Step title="Start Testing">
    Run the "Authentication" request first, then explore other endpoints
  </Step>
</Steps>

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

***

## Authentication Overview

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

```http theme={null}
Authorization: Bearer <your_jwt_token>
```

### Quick Start Example

<RequestExample>
  ```bash Authenticate theme={null}
  curl -X POST https://your-utmstack-instance.com/api/authenticate \
    -H "Content-Type: application/json" \
    -d '{"username":"your_username","password":"your_password"}'
  ```
</RequestExample>

<ResponseExample>
  ```json Authentication Response theme={null}
  {
    "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VybmFtZSIsImF1dGgiOiJST0xFX0FETUlOIn0.signature",
    "authenticated": true
  }
  ```
</ResponseExample>

### Additional Language Examples

<CodeGroup>
  ```bash curl theme={null}
  # 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}]'
  ```

  ```javascript JavaScript theme={null}
  // 1. Authenticate and get token
  const authResponse = await fetch('https://your-utmstack-instance.com/api/authenticate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      username: 'your_username',
      password: 'your_password'
    })
  });

  const { id_token } = await authResponse.json();

  // 2. Use token for API requests
  const alertsResponse = await fetch('https://your-utmstack-instance.com/api/elasticsearch/search?page=1&size=25&indexPattern=alert-*', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${id_token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify([
      { field: 'status', operator: 'IS', value: 2 }
    ])
  });
  ```
</CodeGroup>

***

## Common Response Codes

<AccordionGroup>
  <Accordion title="2xx Success Codes">
    * **200 OK**: Request completed successfully
    * **201 Created**: Resource created successfully
    * **204 No Content**: Request successful, no response body
  </Accordion>

  <Accordion title="4xx Client Error Codes">
    * **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
  </Accordion>

  <Accordion title="5xx Server Error Codes">
    * **500 Internal Server Error**: Unexpected server error
    * **502 Bad Gateway**: Upstream service unavailable
    * **503 Service Unavailable**: Service temporarily unavailable
  </Accordion>
</AccordionGroup>

***

## Request/Response Format

### Content Type

All API requests and responses use JSON format:

```http theme={null}
Content-Type: application/json
```

### Request Structure

Most endpoints expect JSON in the request body:

```json theme={null}
{
  "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

<Info>
  UTMStack implements rate limiting to ensure API stability. If you exceed the rate limit, you'll receive a `429 Too Many Requests` response.
</Info>

### 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

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

### Error Handling Example

<CodeGroup>
  ```javascript JavaScript theme={null}
  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));
    }
  }
  ```

  ```python Python theme={null}
  import requests
  import time

  def handle_api_request(url, payload, token):
      headers = {
          'Authorization': f'Bearer {token}',
          'Content-Type': 'application/json'
      }
      
      try:
          response = requests.post(url, json=payload, headers=headers)
          response.raise_for_status()
          return response
          
      except requests.exceptions.HTTPError as e:
          if e.response.status_code == 401:
              # Token expired, re-authenticate
              print("Token expired, please re-authenticate")
          elif e.response.status_code == 429:
              # Rate limited, wait and retry
              print("Rate limited, waiting before retry...")
              time.sleep(5)
          else:
              print(f"API Error {e.response.status_code}: {e.response.text}")
          raise e
  ```
</CodeGroup>

***

## SDK and Libraries

<Note>
  Currently, UTMStack provides REST API endpoints. Community SDKs and libraries may be available for specific programming languages.
</Note>

### Recommended HTTP Clients

* **JavaScript**: `fetch`, `axios`
* **Python**: `requests`, `httpx`
* **Java**: `OkHttp`, `Apache HttpClient`
* **C#**: `HttpClient`
* **Go**: `net/http`
* **PHP**: `Guzzle`, `cURL`

***

## Support and Resources

<CardGroup cols={2}>
  <Card title="Support Portal" icon="headset" href="https://support.utmstack.com">
    Get help with API integration and troubleshooting
  </Card>

  <Card title="Status Codes Reference" icon="list-check" href="#common-response-codes">
    Complete list of HTTP status codes and meanings
  </Card>

  <Card title="Authentication Guide" icon="key" href="/v10/apidoc/authentication">
    Detailed authentication setup and token management
  </Card>

  <Card title="Examples Repository" icon="code" href="#">
    Sample code and integration examples
  </Card>
</CardGroup>

***

## Version Information

* **API Version**: v1.0
* **Documentation Version**: 2025.10
* **Last Updated**: October 2025

<Tip>
  This documentation is actively maintained. Check back regularly for updates and new endpoint additions.
</Tip>