Huntress SIEM API

openapi: 3.2.0
info:
  title: Huntress API Reference SIEM API
  description: '© Huntress - All rights reserved


    Introduction


    Webhook event payloads are available via the dropdown menu above the search bar on this page.'
  version: 1.0.0
servers:
- url: https://api.huntress.io
security:
- basic:
  - basic_auth
tags:
- name: SIEM
  description: Query your SIEM logs programmatically using ES|QL (Elasticsearch Query Language).
paths:
  /v1/siem/query:
    post:
      summary: Execute ESQL Query
      description: 'Execute an ESQL query against your SIEM logs and receive paginated JSON results.


        This endpoint uses POST so that the ESQL query string can be sent in the request body

        rather than as a URL query parameter, avoiding URL length limits for complex queries.


        Queries must begin with `FROM logs`. Results are limited to 200 rows per page.

        If `next_page_token` is present, pass it as `page_token` in a subsequent request

        (with the same `range_start` and `range_end`) to retrieve the next page.


        **Response**


        Returns a JSON object with two top-level keys:


        - `logs` — Array of objects. Each object represents one log record. Keys are ECS field

        names (e.g. `event.provider`, `host.hostname`). The fields present depend on the columns

        selected by your ESQL query (e.g. a `KEEP` command). With no column selection, all

        available ECS fields are returned.


        - `pagination` — Object. Contains `next_page_token` (string) when additional results are

        available; empty object `{}` when all results have been returned. Pass `next_page_token`

        as `page_token` in your next request to retrieve the following page.'
      responses:
        '200':
          description: Query executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiemQueryResult'
        '400':
          description: Missing or invalid request parameters.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: SIEM query feature is not enabled for this account.
        '408':
          description: Query timed out.
        '413':
          description: Query exceeded memory limit.
        '422':
          description: Invalid ESQL query or query parameters.
      tags:
      - SIEM
      operationId: postV1SiemQuery
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postV1SiemQuery'
        required: true
components:
  schemas:
    SiemPagination:
      type: object
      properties:
        next_page_token:
          type: string
          example: 019612ab-1234-7000-8000-000000000001
          description: Token to retrieve the next page of results. Omitted when all results have been returned.
    SiemQueryResult:
      type: object
      properties:
        logs:
          type: array
          items:
            type: object
          example:
          - uuid: 019612ab-1234-7000-8000-000000000001
            event.provider: Microsoft-Windows-Security-Auditing
            host.hostname: DESKTOP-ABC123
            message: An account was successfully logged on.
          description: Array of log records. Keys are Elastic Common Schema (ECS) field names (e.g. `event.provider`, `host.hostname`). The fields present depend on the columns selected by your ESQL query. With no column selection, all available ECS fields are returned.
        pagination:
          $ref: '#/components/schemas/SiemPagination'
          example:
            next_page_token: 019612ab-1234-7000-8000-000000000002
          description: Pagination details. Contains `next_page_token` when additional results are available.
      description: SiemQueryResult model
    postV1SiemQuery:
      type: object
      properties:
        esql:
          type: string
          description: ESQL query string (must begin with FROM logs)
        range_start:
          type: string
          format: date-time
          description: Query range start (ISO 8601)
        range_end:
          type: string
          format: date-time
          description: Query range end (ISO 8601)
        page_token:
          type: string
          description: Pagination token from previous response
      required:
      - esql
      - range_start
      - range_end
      description: Execute ESQL Query
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic