openapi: 3.0.3
info:
  title: Logmind API Documentation
  version: '2.0'
  x-logo:
    url: static/images/logo_long.png
    altText: Logmind logo
    href: '#'
  description: |2-

    The Logmind Web API is how the Logmind platform is driven programmatically.
    Through it you can sign users in and manage their roles, search raw logs,
    read and act on the insights the platform generates, describe your infrastructure
    as services and entities, build dashboards, and configure alerting and notifications.

    The API follows REST conventions and has a predictable URL structure. It uses the
    standard HTTP methods (**GET**, **POST**, **PUT**, **PATCH**, **DELETE**) and standard
    response codes. Every call is made against  *https://app.logmind.com/api/*  and every
    response is JSON.

    ### The services behind the API

    Logmind is a set of services sitting behind one gateway. Each one owns a prefix of the
    API, and every call is authenticated by the gateway before it reaches the service.

      - **Account** — `/api/account/`, `/api/saml/`
        *Sign-on and access control.* Issues and verifies the JWT tokens every other call
        carries, handles SAML single sign-on, invitations and password flows, and holds the
        users, roles, rights and per-source access of an environment.

      - **Insights** — `/api/insights/`
        *What the platform found.* Insights are the objects the analysis pipeline produces
        from alerts and anomalies in your logs; related insights are gathered into **insight
        groups**, each carrying an AI generated title, root cause and remediation procedures.
        The service also serves the insight dashboard, the filters, the comment threads, the
        notification recipients, and the Jira, ServiceNow and PagerDuty integrations that turn
        an insight group into a ticket.

      - **Search** — `/api/search/`
        *Raw logs and everything built directly on them.* Runs Logmind Query Language (LQL)
        queries against Elasticsearch, extracts message patterns, exports reports, and serves
        the dashboards, visualizations, alert rules and the hosts, sources and tags of the
        boards page.

      - **Components** — `/api/components/`
        *What your infrastructure is made of.* Services, service groups, entities (hosts,
        devices, nodes, endpoints, users), sources and the parsing pipelines that turn raw
        lines into structured documents, along with the tags, dynamic filters and saved
        filters that organise them.

      - **Activities** — `/api/activities/`
        *Who did what.* Records user actions in real time and serves the notification feed
        of the application.

    ### Conventions

      - **Filters travel in the body.** Listings that take a structured filter — insights,
        insight groups, boards, search — are **POST** endpoints. The filter carries objects
        and lists that do not survive a query string, and pagination (`page`, `limit`) travels
        with it.
      - **Pagination.** Listings answer with `results` plus `total`, `count` and the `page` to
        request next — `null` when the last page has been reached. The components service
        answers instead with `documents`, `total` and `page_count`, and takes zero-based `page`
        and `size` query parameters.
      - **Periods.** A period is given as an `interval` object: a named period
        (`{"value": "Last 7 days"}`, `{"value": "All time"}`) or an explicit range in
        milliseconds (`{"start": …, "end": …}`). Search uses `times`, which additionally accepts
        Elasticsearch date math such as `now-1w/d`.
      - **Access is scoped to the environment.** Every call is answered within the environment
        of the signed-in user, and narrowed further by the sources their roles grant them.

    ****Standard response codes and definitions****:

      - **code**: `200`
        *description*:  **Success.** *The request was successful.*
      - **code**: `201`
        *description*:  **New resource created.** *The request has led to the creation of a new resource.*
      - **code**: `204`
        *description*:  **No Content.** *There is no content to send for this request.*
      - **code**: `400`
        *description*:  **Bad Request.** *Default code for invalid requests. For example, it is missing a mandatory field. Check the error message and ensure that the JSON includes the correct parameters.*
      - **code**: `401`
        *description*:  **Unauthorized.** *Token is invalid or missing. Check that the request includes the correct HTTP headers.*
      - **code**: `403`
        *description*:  **Forbidden.** Access *denied — the user is signed in but their roles do not carry the required right.*
      - **code**: `404`
        *description*:  **Not Found.** *Requested endpoint isn't available. Ensure that the request uses one of the API endpoints specified in the documentation.*
      - **code**: `422`
        *description*:  **Unprocessable Entity.** *Returned by the components service when the request body fails validation; the answer names the field and the reason.*
      - **code**: `500`
        *description*:  **Internal Server Error.** *Default code for errors that occur due to problems on Logmind servers. Retry the request after some time.*
      - **code**: `501`
        *description*:  **Not Implemented.** *Unsupported method.*
servers:
- url: https://app.logmind.com
  description: Production
- url: https://classic.app.logmind.com
  description: Production, previous interface
- url: /
  description: |-
    The host serving these docs. Only pick this when the docs are reached
    through the application itself, at `/docs` — a documentation host of its
    own does not proxy the API, and calls to it will not reach a service.
tags:
- name: Authentication
  description: |
    Every request to the Logmind API carries an HTTP header with an authentication token. You will usually also state the content type of the payload and the response you expect. All calls to Logmind use Bearer-type authentication.


      For example:

        - Authorization: "Bearer ${token}"
        - Accept: "application/json"
        - Content-Type: "application/json; charset=utf-8"

    ### JWT tokens
    `POST /api/account/login/` exchanges an email address and a password for an `access` and a `refresh` token. The email goes in the `username` field, not `email`; both are valid for 30 days. Send the access token on every subsequent call, refresh it through `/api/account/token/refresh/` when it expires, and check it with `/api/account/token/verify/`.
    The API gateway verifies the token on every proxied call, through nginx `auth_request` against `/api/account/user-verify/`. When the token is valid, the gateway sets the `X-User` and `X-User-Env` headers on the request it forwards, and the service behind it resolves the caller and their environment from those. `user-verify` is not reachable from outside: only the gateway may call it.
    ### SAML single sign-on
    An environment can delegate authentication to its own identity provider. `/api/saml/login/` returns the URL to send the browser to, and the provider posts its assertion back to `/api/saml/acs/`, which answers with the same JWT pair a password login would produce. A user signing in this way for the first time is created with the environment's default SAML role.
    ### Authentication types
    - **Org token:**
      Each environment possesses a unique bearer token for authenticating API requests through
      integrations. The org bearer token appears in the example headers for any integration
      using the Logmind API.

    - **User API key:**
      API keys in Logmind are managed on a user-specific basis within the API Keys settings
      menu. Each key is associated with a specific user and is constrained by the permissions
      assigned to that user's roles.

    ### Supported content types
    Check the API reference documentation for the supported content types of each request.
- name: Access Control
  description: |
    Manage who may use Logmind, and what they may do with it.

    Access is granted through **roles**. A role bundles a set of **rights** — `view`, `add`, `edit` and `delete` on each module of the product (`discover`, `dashboards`, `visualisations`, `insights`, `alerts`, `hosts_and_sources`, `access_control`) — together with the list of **sources** the role may read. A user holds one or more roles, and every request they make is answered within the union of what those roles allow; `*` as a source grants access to the whole environment.

    These endpoints invite users, resend and complete invitations, reset and change passwords, create and edit roles, attach rights and sources to them, and assign them to users. Most of them require a right of the `access_control` module, and some are restricted to administrators.
- name: Insights
  description: |
    An **insight** is what the analysis pipeline makes of your logs: an alert or an anomaly, with the events behind it, the entities it concerns, the period it covers and a severity. Anomalies come with the timeline that shows how far the behaviour departed from what was expected; pattern anomalies come with the message pattern they were found on, whose placeholders can be expanded into the values that actually occurred.

    These endpoints list insights against a filter, open one of them, replay its events or return the Elasticsearch query that reproduces them, break its occurrences down by field or over time, and override the severity the pipeline computed.
- name: Insight Groups
  description: |
    Insights that describe one and the same incident are gathered into an **insight group**. The group is what a user works with: it carries the AI generated title, root cause and remediation procedures for the incident, the services, sources and entities it touches, its severity, its status, its assignees and its comment thread.

    A group moves through two states. `status` is what the pipeline computed — `active` or `unhandled`; `assigned_status` is what a person decided — `resolved` or `ignored`. Together they drive the status filter and the summary widgets.

    Three views of the same data are served, for three different consumers:

      - `/api/insights/groups/` — the classic listing and detail, with the group's insights
        inline.
      - `/api/insights/v3/groups/` — the Overview page: a leaner listing, plus detail endpoints
        that return the group's events, fields, entities, alerts and anomalies, and the service
        topology around it.
      - `/api/insights/chatbot/groups/` — the raw stored fields, unshaped, for the chatbot.

    Comments and the summary widgets live here too. The summaries report one timeline per severity and per status over a period, and accept the same filter as the group listing, so a filtered list and the widgets above it always agree.
- name: Insight Filters
  description: |
    Everything the insights page needs to build its filter bar — the sources that carry insights, the severity levels, the states, the predefined periods, the users insights are assigned to, and the label-tag fields an environment chose to surface — together with the filters a user has saved.

    A saved filter can be marked as the favourite one, applied when the page opens, and pinned to the tab bar, in which case its position in that bar is maintained as tabs are added, moved and removed.
- name: Insight Dashboard
  description: |
    The charts of the insights page. Each user has a dashboard of their own, created with a default set of charts on first access; the layout, the period each chart reports on, and the sources the dashboard shows are all stored per user.

    The same set of endpoints exists twice: under `/api/insights/dashboard/charts/` for the insights page and under `/api/insights/v3/dashboard/charts/` for the Overview page, which keeps a dashboard of its own.
- name: Insight Notifications
  description: |
    Notification recipients decide what leaves Logmind, and where it goes. A recipient binds a channel — email, Slack, Microsoft Teams, Jira, ServiceNow or PagerDuty — to one or more filter groups; an insight is delivered when it matches any of them.

    Filters are expressed as `filter_groups`, each combining services, service groups, sources, entities and severities. The older flat fields are still accepted and are returned folded into a single equivalent group, so old and new recipients read the same.
- name: Integrations
  description: |
    Logmind connects to the ticketing and on-call tools a team already uses. Jira, ServiceNow and PagerDuty are connected per user through OAuth, and once connected an insight group can be turned into an issue or an incident — either by hand, or automatically through a notification recipient with an `automatic` trigger.

    A group is only ever sent once per tool: a second send returns the ticket that already exists. The ticket endpoints read the live state back from the provider, with its history, comments and current assignee, so the group detail can show what has happened to it since.

    The lookup endpoints under each `overview/` prefix serve the values a send form needs — Jira projects, boards, sprints, issue types, priorities and assignees; ServiceNow choice and reference fields; PagerDuty services, users, escalation policies, priorities, urgencies and statuses.
- name: Search
  description: |
    The Search page looks for events across the sources a user has access to. Queries are written in `Logmind Query Language` (`LQL`), whose syntax is close to SQL.

    For example:
      - `*;` (searches for everything within the selected period)
      - `SELECT "example" FROM source="source";` (searches for events from a given source)
      - `"example event";` (searches for a specific event across all sources)
      - `SELECT * FROM service="payments" WHERE level="error";` (a query built on a service
        rather than on a raw source)


    For more examples, please visit: [Logmind Query Language.](https://paper.dropbox.com/doc/Logmind-Query-Language-htsDGW39BG1fPiH52PDMU)

    A query is parsed, optimised into an Elasticsearch query and executed. Alongside the events, the answer carries the fields they hold, the aggregations the query asked for and, when a timeline was requested, the distribution of the hits over time. From there the same result can be narrowed to a single field, expanded into its **message patterns**, opened on the log lines surrounding one event, or exported as a report.

    With **AI mode** a question in plain language is turned into a query first; the generated query is returned with the results, and feedback on it can be sent back through `/api/search/search/smart_search/feedback/`.

    By default, Logmind searches the last 7 days.
- name: Patterns
  description: |
    A pattern stands for a family of near-identical log lines: the parsing pipeline folds them into one, replacing the parts that vary with placeholders. Patterns sit between raw log lines and insights — they are what makes a million lines readable at a glance.

    These endpoints list the stored patterns, find the patterns present in the result of a query, expand a placeholder back into the values that occur behind it, and mark a pattern as critical so that new occurrences of it are surfaced with priority.
- name: Dashboards
  description: |
    Dashboards gather **visualizations** — charts built on a saved query — into a layout a user can arrange, share with the roles of their environment, mark as their favourite, or leave running live.

    Each visualization stores its query configuration and its rendered state, and can have anomaly detection turned on: the platform then computes the band a series is expected to stay within and records the points that fall outside it.
- name: Alerts
  description: |
    An alert **rule** runs a query on a schedule, looks back over a period, and raises an **alert** when the number of hits satisfies its condition — above or below a threshold, risen or dropped by an amount. Every raised alert keeps the rows that triggered it, and can be delivered through the channels configured on the rule.

    These endpoints create and schedule rules, list the alerts they have raised together with the charts of the alerts page, replay the recent activity of a rule, and serve the option lists — conditions, severities, intervals, channels — a rule form is built from.
- name: Boards
  description: |
    The Boards page is where the hosts and sources behind the incoming logs are managed. Hosts and sources are discovered from what clients send; **tags** are what you add on top, to group them the way your organisation actually works.

    A listing answers in two ways: on its own it returns the stored hosts or sources, paginated, sorted and searchable by name, source or tag; given a list of identifiers in `stats` it goes to Elasticsearch instead and returns the event counts and last activity of exactly those objects over a period. Tagging, untagging and removal are done in bulk, and an object that is still receiving logs cannot be removed.
- name: Services
  description: |
    A **service** is a named slice of the log stream: everything matching its filters is attributed to it. It carries a class (`Network`, `Storage`, `Compute`, `Application`), a criticality, the sources it reads from, the entities seen on it, its tags, and its upstream and downstream relationships to other services — which is what the topology on an insight group is drawn from.

    Filters are stored as a tree, so a service can be defined by a nested boolean expression rather than a flat list of values, and can be written and checked as a query string (`(level=error OR level=warn) AND host=server1`) through the validate and preview endpoints. A service keeps two pairs of filters: one selecting what belongs to it, and one narrowing that further for insight generation only.

    **Service groups** gather services that belong together — a business application, a platform, a location — and carry their own criticality and status.
- name: Entities
  description: |
    An **entity** is a thing that produces logs: a host, a device, a node, an endpoint or a user. Entities are discovered automatically from the field a source is keyed on, and keep the sources they were seen on, the services they belong to, their tags, their event total and their activity status.

    Activity can be served either from the stored value or, with `fresh_activity`, read live from Elasticsearch — which is also what the `get-elastic-datetimes` and `entity-activity` endpoints do in bulk, for the sparklines of the entities board.
- name: Sources
  description: |
    A **source** is where logs come from: the Kafka topic they arrive on, the index they are written to, the timezone they are stamped in, the field a host name is read from, and the pipeline that parses them.

    These endpoints register and configure sources, read their raw messages straight from Kafka before any parsing, and show what parsing produced — including the lines it failed on, through the log-monitoring endpoints. Live streams of the same data are served over WebSocket at `/api/components/kafka/topics/{topic_name}/stream`, `/api/components/kafka/sources/{source_name}/stream` and `/api/components/kafka/sources/stream`.
- name: Pipelines
  description: |
    A **pipeline** is the ordered list of steps a raw log line goes through before it is indexed: parsing, extraction, renaming, dropping. Each step calls one of the functions the platform provides, and the pipeline says what to do when a step fails — raise, skip the step, or drop the line.

    A pipeline can be tried before it is saved, against pasted sample lines, against real messages pulled from the Kafka topics of its sources, or against an uploaded JSON file; the answer shows what each line turned into, and which ones failed or were dropped. A live preview is also served over WebSocket at `/api/components/pipelines/live-preview/stream` and `/api/components/pipelines/live-preview/{source_name}/stream`.
- name: Component Filters
  description: |
    The machinery that keeps the components boards organised.

    **Tags** are free-form labels attached to services, entities and service groups, with the counters that say how much each one covers. **Dynamic filters** generate services automatically: point one at a field of a source and every value it finds becomes a service of its own, named through prefixes, suffixes, patterns or explicit mappings, and maintained as new values appear. **Saved filters** remember the grouping, search and sorting a user left a board in. The **autocomplete** endpoints feed the filter editor with the indices, fields and values it can offer.
- name: Chatbot
  description: |
    The Logmind assistant. A question arrives in plain language and an agent answers it by reaching into the platform itself: the components service for sources, entities and services, the insights service for insight groups, and a generated Elasticsearch query when the answer is in the logs. The fields the environment actually holds are put in front of the model first, so the queries it writes are queries that run.

    Each caller has one conversation, kept per user, which is what lets a follow-up question stand on its own — ask about a service, then ask "and yesterday?" and the agent still knows what you meant. It can be read back with `retrieve-conversation` and forgotten with `clear-conversation`.

    Beside the free-form endpoint there are one-click prompts: the application sends `entity-prompt`, `source-prompt`, `service-prompt` or `insight-group-prompt` with the identifier of the object the user is looking at, and the service supplies the wording. `retrieve-prompts` returns exactly those texts, so an interface can show what it is about to ask.

    Every call is authenticated by the gateway, which resolves the caller into the `X-User` and `X-User-Env` headers the service reads; answers never leave the caller's environment.
- name: Notifications
  description: |-
    The activities service records what people do in Logmind — state and severity
    changes, assignments, comments, invitations — and serves them back as one
    feed. `/api/activities/` is the full feed; `/api/activities/notification` is
    the unseen slice of it that the bell in the navigation bar reads.

    Reading and clearing the feed are gated on the `activities_view`,
    `activities_edit` and `activities_delete` rights; administrators and
    superusers bypass the check. `/api/activities/datetime_intervals` is the one
    endpoint that needs no right beyond being signed in.

    Errors from this service report their reason under `message`, where the other
    services use `detail`.

    Live updates arrive over a WebSocket at `/api/activities/ws/notify/{token}`,
    which pushes a notification as soon as one is recorded. It carries the access
    token in the path rather than in a header, and is not described below —
    OpenAPI 3.0 has no way to express a WebSocket.
- name: Help
  description: Help and feedback
x-tagGroups:
- name: Account Service
  tags:
  - Authentication
  - Access Control
- name: Insights Service
  tags:
  - Insights
  - Insight Groups
  - Insight Filters
  - Insight Dashboard
  - Insight Notifications
  - Integrations
- name: Search Service
  tags:
  - Search
  - Patterns
  - Dashboards
  - Alerts
  - Boards
  - Help
- name: Components Service
  tags:
  - Services
  - Entities
  - Sources
  - Pipelines
  - Component Filters
- name: Chatbot Service
  tags:
  - Chatbot
- name: Activities Service
  tags:
  - Notifications
security:
- bearerAuth: []
paths:
  /api/account/login/:
    post:
      tags:
      - Authentication
      operationId: Log In
      description: |-
        HTTP METHOD: POST
        Exchange user credentials for a JWT pair. The returned `access` token is
        the token every other Logmind endpoint expects in the
        `Authorization: Bearer <access>` header. Both tokens are valid for 30 days.
      security: []
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogInResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogInBody'
        required: true
  /api/account/token/refresh/:
    post:
      tags:
      - Authentication
      operationId: Refresh Token
      description: |-
        HTTP METHOD: POST
        Issue a new access token from a valid refresh token, without asking the
        user for credentials again.
      security: []
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshTokenResponse'
        '401':
          description: Token is invalid or expired
          content:
            application/json:
              schema:
                title: response
                required:
                - message
                type: object
                properties:
                  message:
                    title: Message
                    description: Denial reason
                    type: string
              example:
                message: Token is invalid or expired
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshTokenBody'
        required: true
  /api/account/token/verify/:
    post:
      tags:
      - Authentication
      operationId: Verify Token
      description: |-
        HTTP METHOD: POST
        Check that an access token is well formed, correctly signed and not expired.
      security: []
      responses:
        '200':
          description: The token is valid
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyToken'
        required: true
  /api/account/user-verify/:
    post:
      tags:
      - Authentication
      operationId: Verify User
      description: |-
        HTTP METHOD: POST
        Internal endpoint used by the API gateway (`nginx auth_request`) to
        authenticate every proxied call. On success it answers `200` with the
        `X-User` and `X-User-Env` headers that the downstream services read to
        resolve the caller and their environment.

        It is not reachable from outside the cluster: the gateway rejects direct
        calls that do not carry its internal identifier.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserVerifyResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/account/users/:
    get:
      tags:
      - Access Control
      operationId: List Users
      description: |-
        HTTP METHOD: GET
        Returns every user of the caller's environment, together with the roles
        assigned to them. Requires the `access_control_view` right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/account/users/by-source/:
    get:
      tags:
      - Access Control
      operationId: List Users By Source
      description: |-
        HTTP METHOD: GET
        Returns the users whose roles grant access to a given source (index).
        Used to offer a meaningful list of assignees for an insight that belongs
        to that source.
      parameters:
      - name: source
        in: query
        required: true
        description: Source (index) name the users must have access to.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserResult'
        '400':
          description: No user has access to the given source
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: No users with app-logs
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/account/users/{id}/:
    get:
      tags:
      - Access Control
      operationId: Retrieve User
      description: |-
        HTTP METHOD: GET
        Returns a single user with their roles and rights.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Access Control
      operationId: Update User
      description: |-
        HTTP METHOD: PUT
        Updates a user's name, password or active state. Passwords are validated
        against the password-strength policy before they are stored.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUser'
        required: true
    delete:
      tags:
      - Access Control
      operationId: Delete User
      description: |-
        HTTP METHOD: DELETE
        Deletes a user. Requires the `access_control_delete` right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: user has been successfully deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the user.
      schema:
        type: string
  /api/account/users/{id}/roles/:
    post:
      tags:
      - Access Control
      operationId: Assign Roles To User
      description: |-
        HTTP METHOD: POST
        Assigns one or more roles to a user. Requires the `access_control_add` right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRolesBody'
        required: true
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the user.
      schema:
        type: string
  /api/account/users/{id}/roles/{role_id}/:
    delete:
      tags:
      - Access Control
      operationId: Unassign Role From User
      description: |-
        HTTP METHOD: DELETE
        Removes one role from a user. Requires the `access_control_delete` right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: role has been successfully unassigned
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the user.
      schema:
        type: string
    - name: role_id
      in: path
      required: true
      description: Identifier of the role to unassign.
      schema:
        type: string
  /api/account/roles/:
    get:
      tags:
      - Access Control
      operationId: List Roles
      description: |-
        HTTP METHOD: GET
        Returns every role defined in the caller's environment.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RolesResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Access Control
      operationId: Create Role
      description: |-
        HTTP METHOD: POST
        Creates a role: a named set of rights plus the list of sources (indices)
        the role may read. Requires the `access_control_add` right.
      responses:
        '201':
          description: Role created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolesResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoleBody'
        required: true
  /api/account/roles/{id}/:
    get:
      tags:
      - Access Control
      operationId: Retrieve Role
      description: |-
        HTTP METHOD: GET
        Returns a single role with its structured rights and its indices.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolesResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Access Control
      operationId: Update Role
      description: |-
        HTTP METHOD: PUT
        Updates the name, description or rights of a role.
        Requires the `access_control_edit` right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolesResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRoleBody'
        required: true
    patch:
      tags:
      - Access Control
      operationId: Partially Update Role
      description: |-
        HTTP METHOD: PATCH
        A partial update of the role: the body of `PUT` on this path, with every
        field optional. Only the fields present are changed.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolesResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRoleBody'
        required: true
    delete:
      tags:
      - Access Control
      operationId: Delete Role
      description: |-
        HTTP METHOD: DELETE
        Deletes a role. A role that is still assigned to a user, or a built-in
        role, cannot be deleted. Requires the `access_control_delete` right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: role has been successfully deleted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the role.
      schema:
        type: string
  /api/account/roles/{id}/rights/:
    post:
      tags:
      - Access Control
      operationId: Add Rights To Role
      description: |-
        HTTP METHOD: POST
        Grants one or more rights to a role. Requires the `access_control_add` right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolesResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RightsBody'
        required: true
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the role.
      schema:
        type: string
  /api/account/roles/{id}/rights/{right_id}/:
    delete:
      tags:
      - Access Control
      operationId: Remove Right From Role
      description: |-
        HTTP METHOD: DELETE
        Revokes a single right from a role.
        Requires the `access_control_delete` right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: right has been successfully removed
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the role.
      schema:
        type: string
    - name: right_id
      in: path
      required: true
      description: Identifier of the right to revoke.
      schema:
        type: string
  /api/account/roles/{id}/indices/:
    put:
      tags:
      - Access Control
      operationId: Add Indices To Role
      description: |-
        HTTP METHOD: PUT
        Replaces the list of sources (indices) a role gives access to. `*` grants
        access to every source of the environment.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolesResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRoleIndexBody'
        required: true
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the role.
      schema:
        type: string
  /api/account/roles/{id}/indices/{index}/:
    delete:
      tags:
      - Access Control
      operationId: Remove Index From Role
      description: |-
        HTTP METHOD: DELETE
        Removes one source (index) from a role.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: index has been successfully removed
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the role.
      schema:
        type: string
    - name: index
      in: path
      required: true
      description: Name of the source (index) to remove.
      schema:
        type: string
  /api/account/rights/:
    get:
      tags:
      - Access Control
      operationId: List Rights
      description: |-
        HTTP METHOD: GET
        Returns every right the platform knows about, grouped by module
        (`discover`, `dashboards`, `visualisations`, `insights`, `alerts`,
        `hosts_and_sources`, `access_control`) with the `view` / `add` / `edit` /
        `delete` permissions each module supports.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RightResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/account/additional/roles/:
    get:
      tags:
      - Access Control
      operationId: List Role Names
      description: |-
        HTTP METHOD: GET
        Returns a lightweight list of roles (id, name, description, rights) used
        to populate role pickers, for example when inviting a user.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RolesResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/account/user_available_menus/:
    get:
      tags:
      - Access Control
      operationId: List Available Menus
      description: |-
        HTTP METHOD: GET
        Returns the navigation menus the current user is allowed to open, solved
        from the rights of their roles. A superuser receives the full menu tree.
        The web application uses this to build its sidebar.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    properties:
                      id:
                        type: string
                      email:
                        type: string
                      username:
                        type: string
                  user_menus:
                    type: array
                    description: Menu tree the user may access.
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/account/saml_role/:
    get:
      tags:
      - Access Control
      operationId: Retrieve Default SAML Role
      description: |-
        HTTP METHOD: GET
        Returns the role that is assigned automatically to users who sign in
        through SAML for the first time, or `null` when the environment has no
        SAML configuration.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  saml_role:
                    type: string
                    nullable: true
              example:
                saml_role: Viewer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/account/invitation/:
    post:
      tags:
      - Access Control
      operationId: Invite User
      description: |-
        HTTP METHOD: POST
        Invites a new user to the environment with a set of roles. The invitation
        email carries an activation key the invitee uses to set their password.
        Administrator only.
      responses:
        '201':
          description: Invitation sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvitationBody'
        required: true
  /api/account/resend_invitation/:
    post:
      tags:
      - Access Control
      operationId: Resend Invitation
      description: |-
        HTTP METHOD: POST
        Sends a fresh invitation email, with a new activation key, to a user who
        has not activated their account yet. Administrator only.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: invitation has been successfully sent
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReSendInvitationBody'
        required: true
  /api/account/activation/{activation_key}/:
    put:
      tags:
      - Authentication
      operationId: Activate User
      description: |-
        HTTP METHOD: PUT
        Completes an invitation: the invitee supplies their name and a password,
        and the account becomes active. The activation key expires, after which
        a new invitation has to be sent.
      security: []
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResult'
        '400':
          description: Invalid or expired activation key
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Invalid or expired activation key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserActivation'
        required: true
    parameters:
    - name: activation_key
      in: path
      required: true
      description: Activation key sent in the invitation email.
      schema:
        type: string
  /api/account/password_reset/:
    post:
      tags:
      - Authentication
      operationId: Request Password Reset
      description: |-
        HTTP METHOD: POST
        Sends a password-reset email containing a single-use key to the given
        address. No authentication is required.
      security: []
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordReset'
        required: true
  /api/account/password_reset_done/:
    post:
      tags:
      - Authentication
      operationId: Confirm Password Reset
      description: |-
        HTTP METHOD: POST
        Sets a new password using the key from the reset email.
      security: []
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordResetDone'
        required: true
  /api/account/password_change/:
    post:
      tags:
      - Authentication
      operationId: Change Password
      description: |-
        HTTP METHOD: POST
        Changes the password of the signed-in user. The current password must be
        supplied, and the new one must satisfy the password-strength policy.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordChange'
        required: true
  /api/saml/login/:
    get:
      tags:
      - Authentication
      operationId: Start SAML Login
      description: |-
        HTTP METHOD: GET
        Starts a SAML single sign-on flow and returns the identity provider URL
        the browser has to be redirected to.
      security: []
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: Identity provider URL to redirect the user to.
        '400':
          $ref: '#/components/responses/BadRequest'
    post:
      tags:
      - Authentication
      operationId: Resolve SAML Provider
      description: |-
        HTTP METHOD: POST
        Resolves the SAML configuration for an email domain and returns the
        identity provider URL for that environment.
      security: []
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SamlLoginBody'
        required: true
  /api/saml/acs/:
    post:
      tags:
      - Authentication
      operationId: SAML Assertion Consumer
      description: |-
        HTTP METHOD: POST
        Assertion Consumer Service. The identity provider posts its SAML response
        here; Logmind validates the assertion, creates the user on first sign-in
        with the environment's default SAML role, and answers with a JWT pair.
      security: []
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogInResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ACSBody'
        required: true
  /api/insights/:
    post:
      tags:
      - Insights
      operationId: List Insights
      description: |-
        HTTP METHOD: POST
        Returns the insights that match a filter. The filter travels in the body
        (and not in the query string) because it carries structured objects —
        source lists, severity lists, a time interval.

        Results are paginated with `page` and `limit`, both read from the body;
        the response echoes the next `page` to request, or `null` on the last page.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListInsightsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightsFilterBody'
  /api/insights/{id}/:
    get:
      tags:
      - Insights
      operationId: Retrieve Insight
      description: |-
        HTTP METHOD: GET
        Returns a single insight: its title, severity, source, service, the
        entities it concerns, its custom fields and the Elasticsearch query that
        reproduces its events.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight.
      schema:
        type: string
  /api/insights/{id}/stats/:
    post:
      tags:
      - Insights
      operationId: Retrieve Insight Occurrences
      description: |-
        HTTP METHOD: POST
        Returns occurrence statistics for an insight: how its events break down
        over the requested fields, and — when `is_timeline` is set — how they are
        distributed over time.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightsOccurrences'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                field:
                  type: string
                  description: Field to break the occurrences down by.
                fields:
                  type: array
                  description: Several fields to break the occurrences down by.
                  items:
                    type: string
                is_timeline:
                  type: boolean
                  description: Return a time distribution instead of field buckets.
                time_filter:
                  type: object
                  description: Narrows the statistics to a sub-range of the insight.
                previous_positions:
                  type: array
                  description: Placeholder positions already pinned by the caller.
                  items:
                    type: object
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight.
      schema:
        type: string
  /api/insights/{id}/alerts/:
    get:
      tags:
      - Insights
      operationId: List Insight Alerts
      description: |-
        HTTP METHOD: GET
        Returns the alert objects an insight was built from, each with the
        severity spans (`clear`, `minor`, `major`, `critical`) recorded for its
        sensor and device over the life of the insight.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightAlertsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight.
      schema:
        type: string
  /api/insights/{id}/anomalies/:
    get:
      tags:
      - Insights
      operationId: List Insight Anomalies
      description: |-
        HTTP METHOD: GET
        Returns the anomalies an insight was built from. Every anomaly carries its
        severity, its entities, the tracked field and value, the total number of
        events and a timeline in which each sample is flagged as anomalous or not.

        For a *pattern* anomaly the title is returned as `field_value` with each
        variable part rendered as `*`; the positions of those placeholders are
        listed in `placeholders` and can be expanded through
        `/api/insights/{id}/placeholder_tokens/`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InsightAnomaly'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight.
      schema:
        type: string
  /api/insights/{id}/placeholder_tokens/:
    post:
      tags:
      - Insights
      operationId: Expand Pattern Placeholder
      description: |-
        HTTP METHOD: POST
        Returns the distinct values behind one placeholder (`*`) of a pattern
        anomaly's title, scoped to the time window of that anomaly. Already
        pinned placeholders can be passed in `selected` to narrow the result
        progressively.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceholderTokensResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaceholderTokensBody'
        required: true
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight.
      schema:
        type: string
  /api/insights/{id}/levels/:
    get:
      tags:
      - Insights
      operationId: Retrieve Insight Level
      description: |-
        HTTP METHOD: GET
        Returns the severity levels an insight can be set to, and the one it
        currently carries.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightLevelResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Insights
      operationId: Update Insight Level
      description: |-
        HTTP METHOD: POST
        Overrides the severity of an insight. The override is stored separately
        from the level the pipeline computed, so the original stays recoverable.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LevelUpdatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightLevelBody'
        required: true
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight.
      schema:
        type: string
  /api/insights/{id}/event_date/:
    post:
      tags:
      - Insights
      operationId: Retrieve Insight Event Date
      description: |-
        HTTP METHOD: POST
        Returns the period an insight covers, as a human readable string plus its
        length in seconds. When `tokens` or `hostnames` are supplied the period is
        recomputed for that subset of events only.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  event_date:
                    type: string
                    example: Mar 12, 2026 09:00 - Mar 12, 2026 17:30
                  range:
                    type: number
                    description: Length of the period, in seconds.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tokens:
                  type: array
                  description: Pattern tokens to narrow the events by.
                  items:
                    type: string
                hostnames:
                  type: array
                  description: Hostnames to narrow the events by.
                  items:
                    type: string
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight.
      schema:
        type: string
  /api/insights/{id}/get_events/:
    post:
      tags:
      - Insights
      operationId: List Insight Events
      description: |-
        HTTP METHOD: POST
        Runs the insight's Elasticsearch query and returns the raw events behind
        it. `time_filter` narrows the search to a sub-range of the insight.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  source:
                    type: array
                    items:
                      type: object
                      properties:
                        event:
                          type: string
                          description: The log message.
                        entity:
                          type: string
                          description: Entities the event belongs to, comma separated.
                        timestamp:
                          type: string
                          description: Present for sources that carry no timestamp of their own.
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                time_filter:
                  type: object
                  description: Sub-range of the insight period to search in.
                  properties:
                    gte:
                      type: string
                    lte:
                      type: string
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight.
      schema:
        type: string
  /api/insights/{id}/get_insights_query/:
    get:
      tags:
      - Insights
      operationId: Retrieve Insight Query
      description: |-
        HTTP METHOD: GET
        Returns the Elasticsearch query that `get_events` would run, without
        running it. Useful to reproduce an insight's events in Search or in an
        external tool.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: object
                    description: Elasticsearch query body.
                  metadata:
                    type: object
                    properties:
                      insight_id:
                        type: string
                      index:
                        type: string
                      start_date:
                        type: string
                        format: date-time
                      end_date:
                        type: string
                        format: date-time
                      entity_fields:
                        type: array
                        items:
                          type: string
                      has_filters:
                        type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight.
      schema:
        type: string
  /api/insights/groups/:
    get:
      tags:
      - Insight Groups
      operationId: Search Insight Groups
      description: |-
        HTTP METHOD: GET
        Returns visible insight groups as `id` / `ai_title` pairs, for pickers and
        type-ahead. `q` matches the AI generated title; results are returned in
        pages of 500.
      parameters:
      - name: q
        in: query
        required: false
        description: Case-insensitive match on the group title.
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number, starting at 1.
        schema:
          type: integer
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        ai_title:
                          type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Insight Groups
      operationId: List Insight Groups
      description: |-
        HTTP METHOD: POST
        Returns the insight groups that match a filter. A group gathers the
        insights that describe one and the same incident, and carries the AI
        generated title, root cause and procedures for it.

        The filter travels in the body and accepts the whole set of group
        criteria — sources, services, service groups, entities, severities,
        statuses, assigned users, free text. Paginated through `page` and `limit`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListInsightGroupsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightGroupsFilterBody'
  /api/insights/groups/severity_counts/:
    post:
      tags:
      - Insight Groups
      operationId: Retrieve Severity Counts
      description: |-
        HTTP METHOD: POST
        Returns, per service, per service group and per entity, how many insight
        groups of each severity are open over the requested period. At least one
        of `services`, `service_groups` or `entities` must be supplied; each takes
        a list of identifiers, or the keyword `All` or `Active`.

        Answers are cached per environment and filter for a short period.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeverityCountsResponse'
        '400':
          description: No target supplied, or a target of the wrong shape
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: At least one of 'services', 'service_groups', or 'entities' must be provided.
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                services:
                  description: Service ids, or `All` / `Active`.
                  type: array
                  items:
                    type: string
                service_groups:
                  description: Service group ids, or `All` / `Active`.
                  type: array
                  items:
                    type: string
                entities:
                  description: Entity ids, or `All` / `Active`.
                  type: array
                  items:
                    type: string
                time_filter:
                  type: object
                  description: Period to count over.
        required: true
  /api/insights/groups/{id}/:
    get:
      tags:
      - Insight Groups
      operationId: Retrieve Insight Group
      description: |-
        HTTP METHOD: GET
        Returns one insight group with its insights, its assigned users, its
        comment count and the AI generated summary, root cause and procedures.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    $ref: '#/components/schemas/InsightGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/groups/{id}/state/:
    get:
      tags:
      - Insight Groups
      operationId: Retrieve Insight Group State
      description: |-
        HTTP METHOD: GET
        Returns both states a group carries: `state`, computed by the pipeline
        (`active`, `unhandled`), and `assigned_state`, set by a user
        (`resolved`, `ignored`).
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: string
                    example: active
                  assigned_state:
                    type: string
                    example: resolved
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Insight Groups
      operationId: Update Insight Group State
      description: |-
        HTTP METHOD: PUT
        Sets the user-assigned state of a group. `state` is the numeric code of
        the state: `0` active, `1` unhandled, `2` resolved, `3` ignored.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Insights group state has been successfully updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - state
              properties:
                state:
                  type: integer
                  description: 0 active, 1 unhandled, 2 resolved, 3 ignored
                  enum:
                  - 0
                  - 1
                  - 2
                  - 3
                set_for_all:
                  type: boolean
                  description: Record the change for every user the group is assigned to.
        required: true
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/groups/{id}/levels/:
    get:
      tags:
      - Insight Groups
      operationId: Retrieve Insight Group Level
      description: |-
        HTTP METHOD: GET
        Returns the severity levels a group can be set to, and the one it
        currently carries.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightLevelResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Insight Groups
      operationId: Update Insight Group Level
      description: |-
        HTTP METHOD: POST
        Overrides the severity of an insight group.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LevelUpdatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightLevelBody'
        required: true
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/groups/{id}/assign_user/:
    post:
      tags:
      - Insight Groups
      operationId: Assign User To Insight Group
      description: |-
        HTTP METHOD: POST
        Assigns a user to an insight group. The assignee is notified through the
        activities service.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          description: '`user_id` missing or malformed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: '`user_id` is required parameter'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - user_id
              properties:
                user_id:
                  type: string
                  description: Identifier of the user to assign.
        required: true
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/groups/{id}/assign_user/{user_id}/:
    delete:
      tags:
      - Insight Groups
      operationId: Unassign User From Insight Group
      description: |-
        HTTP METHOD: DELETE
        Removes a user from the assignees of an insight group. The full name of
        the user has to be passed as the `name` query parameter, so the activity
        record can name them.
      parameters:
      - name: name
        in: query
        required: true
        description: Full name of the user being unassigned.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
    - name: user_id
      in: path
      required: true
      description: Identifier of the assigned user.
      schema:
        type: string
  /api/insights/groups/{id}/delete_insight/:
    delete:
      tags:
      - Insight Groups
      operationId: Delete Insight Group
      description: |-
        HTTP METHOD: DELETE
        Soft-deletes an insight group: it stops being listed, but the underlying
        insights and their events are preserved.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
              example:
                message: Issue has been successfully deleted
                status: success
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/v3/groups/:
    post:
      tags:
      - Insight Groups
      operationId: List Insight Groups (v3)
      description: |-
        HTTP METHOD: POST
        The v3 listing of insight groups. It takes exactly the same filter body as
        `POST /api/insights/groups/` but returns the leaner row the Overview page
        draws: title, last seen, event count, status, severity, service group,
        services, sources, assignees, entities, custom fields and the covered range.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/InsightGroupV3'
                  page:
                    type: integer
                    nullable: true
                  total:
                    type: integer
                  count:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightGroupsFilterBody'
  /api/insights/v3/groups/{id}/:
    get:
      tags:
      - Insight Groups
      operationId: Retrieve Insight Group (v3)
      description: |-
        HTTP METHOD: GET
        The v3 detail of an insight group: everything the listing carries plus the
        AI model that produced the summary, the root cause, the recommended
        procedures, the total event count, the tickets already opened for the group
        and the Elasticsearch query behind its events.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    $ref: '#/components/schemas/InsightGroupV3Detail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/v3/groups/{id}/get_events/:
    post:
      tags:
      - Insight Groups
      operationId: List Insight Group Events
      description: |-
        HTTP METHOD: POST
        Returns the raw events of every insight in the group, from Elasticsearch.
        `time_filter` narrows the search to a sub-range of the group period.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  source:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                time_filter:
                  type: object
                  properties:
                    gte:
                      type: string
                    lte:
                      type: string
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/v3/groups/{id}/get_insight_groups_query/:
    get:
      tags:
      - Insight Groups
      operationId: Retrieve Insight Group Query
      description: |-
        HTTP METHOD: GET
        Returns the Elasticsearch query that `get_events` would run for the whole
        group, without running it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: object
                  metadata:
                    type: object
                    properties:
                      insight_group_id:
                        type: string
                      indices:
                        type: array
                        items:
                          type: string
                      start_date:
                        type: string
                        format: date-time
                      end_date:
                        type: string
                        format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/v3/groups/{id}/get_fields/:
    post:
      tags:
      - Insight Groups
      operationId: List Insight Group Fields
      description: |-
        HTTP METHOD: POST
        Returns the fields present on the group's events together with the
        distribution of their values, so the detail page can offer a breakdown.
        Entity fields are excluded — they are served by `get_entities`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        type:
                          type: string
                        values:
                          type: array
                          items:
                            type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                time_filter:
                  type: object
                  description: Sub-range of the group period.
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/v3/groups/{id}/get_entities/:
    post:
      tags:
      - Insight Groups
      operationId: List Insight Group Entities
      description: |-
        HTTP METHOD: POST
        Returns every entity (host, device, node, endpoint, user) the group's
        alerts and anomalies concern, with the service and the source each entity
        was seen on, and its event count.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  entities:
                    type: array
                    items:
                      type: object
                      properties:
                        field_name:
                          type: string
                        field_value:
                          type: string
                        service:
                          type: string
                        source:
                          type: string
                        count:
                          type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                time_filter:
                  type: object
                  description: Sub-range of the group period.
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/v3/groups/{id}/get_components/:
    post:
      tags:
      - Insight Groups
      operationId: List Insight Group Components
      description: |-
        HTTP METHOD: POST
        Returns every alert and every anomaly across all insights of the group.
        Anomalies come with their timeline, entities, tracked field and — for
        pattern anomalies — the placeholder positions of their title.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  anomalies:
                    type: array
                    items:
                      $ref: '#/components/schemas/InsightAnomaly'
                  alerts:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/v3/groups/{id}/placeholder_tokens/:
    post:
      tags:
      - Insight Groups
      operationId: Expand Group Pattern Placeholder
      description: |-
        HTTP METHOD: POST
        Same as the insight-level endpoint, but the anomaly is looked up across
        every insight of the group. Returns the distinct values behind one
        placeholder (`*`) of a pattern anomaly's title.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceholderTokensResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaceholderTokensBody'
        required: true
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/v3/groups/{id}/service_topology/:
    get:
      tags:
      - Insight Groups
      operationId: Retrieve Service Topology
      description: |-
        HTTP METHOD: GET
        Returns the service topology of a group as `nodes` and `edges`. A node is
        a service, carrying its class, criticality, status, sources, worst
        severity, anomaly counts and entity count; services the group does not
        reach are still drawn, for context, with `in_group: false`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceTopologyResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/chatbot/groups/:
    get:
      tags:
      - Insight Groups
      operationId: List Insight Groups (chatbot)
      description: |-
        HTTP METHOD: GET
        Lists insight groups by title and start date so the chatbot can resolve a
        conversation to a group id. Groups without an AI generated title are left
        out. Results are returned in pages of 500.
      parameters:
      - name: q
        in: query
        required: false
        description: Case-insensitive match on the group title.
        schema:
          type: string
      - name: start_after
        in: query
        required: false
        description: Only groups that started at or after this ISO-8601 datetime.
        schema:
          type: string
      - name: start_before
        in: query
        required: false
        description: Only groups that started at or before this ISO-8601 datetime.
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number, starting at 1.
        schema:
          type: integer
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        ai_title:
                          type: string
                        start_date:
                          type: string
                          format: date-time
                        end_date:
                          type: string
                          format: date-time
                        service_names:
                          type: array
                          items:
                            type: string
                        indices:
                          type: array
                          items:
                            type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/chatbot/groups/{id}/:
    get:
      tags:
      - Insight Groups
      operationId: Retrieve Insight Group (chatbot)
      description: |-
        HTTP METHOD: GET
        Returns the raw stored fields of an insight group — including every nested
        insight, its anomalies and its alerts — for chatbot consumption. No field
        is reshaped for display.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    $ref: '#/components/schemas/InsightGroupChatbot'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/summary/groups/:
    get:
      tags:
      - Insight Groups
      operationId: Retrieve Groups Summary
      description: |-
        HTTP METHOD: GET, POST
        Returns one timeline per severity — Critical, Major, Minor, Unknown —
        over the requested period, each with its count and the progress against
        the preceding period of the same length.

        The widget sits next to the group list and has to agree with it, so it
        accepts the same filter keys (`index`, `service`, `host`, `level`,
        `status`, `service_group`, `dynamic_components_filter`, `assigned_users`,
        `hasAssignedTo`, `comments`, `q`). On a GET they arrive JSON-encoded in
        the query string, on a POST in the body. `interval` selects the period;
        `{"value": "All time"}` reports on everything.
      parameters:
      - name: interval
        in: query
        required: false
        description: JSON encoded period, e.g. `{"value":"Last 30 days"}` or `{"start":1710000000000,"end":1712592000000}`.
        schema:
          type: string
      - name: level
        in: query
        required: false
        description: JSON encoded severity list, e.g. `["critical"]`.
        schema:
          type: string
      - name: status
        in: query
        required: false
        description: JSON encoded status code list, e.g. `[0,1]`.
        schema:
          type: string
      - name: q
        in: query
        required: false
        description: Free text search, taken as-is.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummaryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Insight Groups
      operationId: Retrieve Groups Summary (POST)
      description: |-
        HTTP METHOD: POST
        Same as the GET form, with the filter supplied as a JSON body instead of
        query parameters.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummaryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightGroupsFilterBody'
  /api/insights/summary/insights/:
    get:
      tags:
      - Insight Groups
      operationId: Retrieve Status Summary
      description: |-
        HTTP METHOD: GET, POST
        Returns one timeline per status — Active, Unhandled, Resolved, Ignored —
        over the requested period, each with its count and the progress against
        the preceding period. Takes the same filter keys as the groups summary.
      parameters:
      - name: interval
        in: query
        required: false
        description: JSON encoded period.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusSummaryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Insight Groups
      operationId: Retrieve Status Summary (POST)
      description: |-
        HTTP METHOD: POST
        Same as the GET form, with the filter supplied as a JSON body.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusSummaryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightGroupsFilterBody'
  /api/insights/groups/{id}/send-jira-notification/:
    post:
      tags:
      - Integrations
      operationId: Send Insight Group To Jira
      description: |-
        HTTP METHOD: POST
        Opens a Jira issue for an insight group, using the Jira integration
        connected by the caller. The issue summary and description are built from
        the group's AI title, root cause and procedures.

        A group can only be sent once: if an issue already exists the endpoint
        answers `200` with the existing issue key and URL instead of creating a
        second one.

        The same action is available under `/api/insights/v3/groups/{id}/` and
        `/api/insights/chatbot/groups/{id}/`.
      responses:
        '200':
          description: Issue created, or already existing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JiraSendResult'
        '400':
          description: Project id missing, or Jira not connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JiraNotificationBody'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/groups/{id}/send-servicenow-notification/:
    post:
      tags:
      - Integrations
      operationId: Send Insight Group To ServiceNow
      description: |-
        HTTP METHOD: POST
        Opens a ServiceNow incident for an insight group. Urgency is derived from
        the group's severity unless it is given explicitly. Choice fields
        (`state`, `category`, `subcategory`, `contact_type`) take
        `{"value": "..."}` and reference fields (`assignment_group`,
        `assigned_to`, `business_service`) take `{"sys_id": "..."}` — both shapes
        are what `/api/insights/integrations/servicenow/fields/` returns.

        A group can only be sent once; a second call answers `200` with the
        existing incident.

        The same action is available under `/api/insights/v3/groups/{id}/` and
        `/api/insights/chatbot/groups/{id}/`.
      responses:
        '200':
          description: Incident created, or already existing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceNowSendResult'
        '400':
          description: ServiceNow not connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceNowNotificationBody'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/groups/{id}/send-pagerduty-notification/:
    post:
      tags:
      - Integrations
      operationId: Send Insight Group To PagerDuty
      description: |-
        HTTP METHOD: POST
        Creates a PagerDuty incident for an insight group. `service_id` is
        required; assignee, escalation policy, priority, urgency and status are
        optional per-send overrides that can be looked up through the
        `/api/insights/integrations/pagerduty/overview/*` endpoints. Urgency
        defaults to the mapping of the group's severity.

        A group can only be sent once; a second call answers `200` with the
        existing incident.

        The same action is available under `/api/insights/v3/groups/{id}/` and
        `/api/insights/chatbot/groups/{id}/`.
      responses:
        '200':
          description: Incident created, or already existing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagerDutySendResult'
        '400':
          description: '`service_id` missing, or PagerDuty not connected'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PagerDutyNotificationBody'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/groups/{id}/get_jira_ticket/:
    get:
      tags:
      - Integrations
      operationId: Retrieve Jira Ticket Of Insight Group
      description: |-
        HTTP METHOD: GET
        Returns the Jira issue opened for a group, refreshed from Jira: current
        status, assignee, priority and resolution, the full change history and the
        comments. When the group has never been sent, `ticket` and `jira_data` are
        `null`.

        Also available under `/api/insights/v3/groups/{id}/` and
        `/api/insights/chatbot/groups/{id}/`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JiraTicket'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/groups/{id}/get-servicenow-ticket/:
    get:
      tags:
      - Integrations
      operationId: Retrieve ServiceNow Ticket Of Insight Group
      description: |-
        HTTP METHOD: GET
        Returns the ServiceNow incident opened for a group, refreshed from the
        connected instance, with its work notes and comments. `null` when the
        group has never been sent.

        Also available under `/api/insights/v3/groups/{id}/` and
        `/api/insights/chatbot/groups/{id}/`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceNowTicket'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/groups/{id}/get-pagerduty-ticket/:
    get:
      tags:
      - Integrations
      operationId: Retrieve PagerDuty Ticket Of Insight Group
      description: |-
        HTTP METHOD: GET
        Returns the PagerDuty incident created for a group, refreshed from
        PagerDuty, with its log entries and notes. `null` when the group has never
        been sent.

        Also available under `/api/insights/v3/groups/{id}/` and
        `/api/insights/chatbot/groups/{id}/`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagerDutyTicket'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/v3/groups/{id}/send-jira-notification/:
    post:
      tags:
      - Integrations
      operationId: Send V3 Insight Group To Jira
      description: |-
        HTTP METHOD: POST
        Opens a Jira issue for an insight group, using the Jira integration
        connected by the caller. The issue summary and description are built from
        the group's AI title, root cause and procedures.

        A group can only be sent once: if an issue already exists the endpoint
        answers `200` with the existing issue key and URL instead of creating a
        second one.

        This is the same action as `/api/insights/groups/{id}/…`, reached
        through the v3 group listing.
      responses:
        '200':
          description: Issue created, or already existing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JiraSendResult'
        '400':
          description: Project id missing, or Jira not connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JiraNotificationBody'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/v3/groups/{id}/send-servicenow-notification/:
    post:
      tags:
      - Integrations
      operationId: Send V3 Insight Group To ServiceNow
      description: |-
        HTTP METHOD: POST
        Opens a ServiceNow incident for an insight group. Urgency is derived from
        the group's severity unless it is given explicitly. Choice fields
        (`state`, `category`, `subcategory`, `contact_type`) take
        `{"value": "..."}` and reference fields (`assignment_group`,
        `assigned_to`, `business_service`) take `{"sys_id": "..."}` — both shapes
        are what `/api/insights/integrations/servicenow/fields/` returns.

        A group can only be sent once; a second call answers `200` with the
        existing incident.

        This is the same action as `/api/insights/groups/{id}/…`, reached
        through the v3 group listing.
      responses:
        '200':
          description: Incident created, or already existing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceNowSendResult'
        '400':
          description: ServiceNow not connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceNowNotificationBody'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/v3/groups/{id}/send-pagerduty-notification/:
    post:
      tags:
      - Integrations
      operationId: Send V3 Insight Group To PagerDuty
      description: |-
        HTTP METHOD: POST
        Creates a PagerDuty incident for an insight group. `service_id` is
        required; assignee, escalation policy, priority, urgency and status are
        optional per-send overrides that can be looked up through the
        `/api/insights/integrations/pagerduty/overview/*` endpoints. Urgency
        defaults to the mapping of the group's severity.

        A group can only be sent once; a second call answers `200` with the
        existing incident.

        This is the same action as `/api/insights/groups/{id}/…`, reached
        through the v3 group listing.
      responses:
        '200':
          description: Incident created, or already existing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagerDutySendResult'
        '400':
          description: '`service_id` missing, or PagerDuty not connected'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PagerDutyNotificationBody'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/v3/groups/{id}/get_jira_ticket/:
    get:
      tags:
      - Integrations
      operationId: Retrieve Jira Ticket Of V3 Insight Group
      description: |-
        HTTP METHOD: GET
        Returns the Jira issue opened for a group, refreshed from Jira: current
        status, assignee, priority and resolution, the full change history and the
        comments. When the group has never been sent, `ticket` and `jira_data` are
        `null`.

        This is the same action as `/api/insights/groups/{id}/…`, reached
        through the v3 group listing.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JiraTicket'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/v3/groups/{id}/get-servicenow-ticket/:
    get:
      tags:
      - Integrations
      operationId: Retrieve ServiceNow Ticket Of V3 Insight Group
      description: |-
        HTTP METHOD: GET
        Returns the ServiceNow incident opened for a group, refreshed from the
        connected instance, with its work notes and comments. `null` when the
        group has never been sent.

        This is the same action as `/api/insights/groups/{id}/…`, reached
        through the v3 group listing.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceNowTicket'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/v3/groups/{id}/get-pagerduty-ticket/:
    get:
      tags:
      - Integrations
      operationId: Retrieve PagerDuty Ticket Of V3 Insight Group
      description: |-
        HTTP METHOD: GET
        Returns the PagerDuty incident created for a group, refreshed from
        PagerDuty, with its log entries and notes. `null` when the group has never
        been sent.

        This is the same action as `/api/insights/groups/{id}/…`, reached
        through the v3 group listing.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagerDutyTicket'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/chatbot/groups/{id}/send-jira-notification/:
    post:
      tags:
      - Integrations
      operationId: Send Chatbot Insight Group To Jira
      description: |-
        HTTP METHOD: POST
        Opens a Jira issue for an insight group, using the Jira integration
        connected by the caller. The issue summary and description are built from
        the group's AI title, root cause and procedures.

        A group can only be sent once: if an issue already exists the endpoint
        answers `200` with the existing issue key and URL instead of creating a
        second one.

        This is the same action as `/api/insights/groups/{id}/…`, reached
        through the chatbot group listing.
      responses:
        '200':
          description: Issue created, or already existing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JiraSendResult'
        '400':
          description: Project id missing, or Jira not connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JiraNotificationBody'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/chatbot/groups/{id}/send-servicenow-notification/:
    post:
      tags:
      - Integrations
      operationId: Send Chatbot Insight Group To ServiceNow
      description: |-
        HTTP METHOD: POST
        Opens a ServiceNow incident for an insight group. Urgency is derived from
        the group's severity unless it is given explicitly. Choice fields
        (`state`, `category`, `subcategory`, `contact_type`) take
        `{"value": "..."}` and reference fields (`assignment_group`,
        `assigned_to`, `business_service`) take `{"sys_id": "..."}` — both shapes
        are what `/api/insights/integrations/servicenow/fields/` returns.

        A group can only be sent once; a second call answers `200` with the
        existing incident.

        This is the same action as `/api/insights/groups/{id}/…`, reached
        through the chatbot group listing.
      responses:
        '200':
          description: Incident created, or already existing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceNowSendResult'
        '400':
          description: ServiceNow not connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceNowNotificationBody'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/chatbot/groups/{id}/send-pagerduty-notification/:
    post:
      tags:
      - Integrations
      operationId: Send Chatbot Insight Group To PagerDuty
      description: |-
        HTTP METHOD: POST
        Creates a PagerDuty incident for an insight group. `service_id` is
        required; assignee, escalation policy, priority, urgency and status are
        optional per-send overrides that can be looked up through the
        `/api/insights/integrations/pagerduty/overview/*` endpoints. Urgency
        defaults to the mapping of the group's severity.

        A group can only be sent once; a second call answers `200` with the
        existing incident.

        This is the same action as `/api/insights/groups/{id}/…`, reached
        through the chatbot group listing.
      responses:
        '200':
          description: Incident created, or already existing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagerDutySendResult'
        '400':
          description: '`service_id` missing, or PagerDuty not connected'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PagerDutyNotificationBody'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/chatbot/groups/{id}/get_jira_ticket/:
    get:
      tags:
      - Integrations
      operationId: Retrieve Jira Ticket Of Chatbot Insight Group
      description: |-
        HTTP METHOD: GET
        Returns the Jira issue opened for a group, refreshed from Jira: current
        status, assignee, priority and resolution, the full change history and the
        comments. When the group has never been sent, `ticket` and `jira_data` are
        `null`.

        This is the same action as `/api/insights/groups/{id}/…`, reached
        through the chatbot group listing.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JiraTicket'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/chatbot/groups/{id}/get-servicenow-ticket/:
    get:
      tags:
      - Integrations
      operationId: Retrieve ServiceNow Ticket Of Chatbot Insight Group
      description: |-
        HTTP METHOD: GET
        Returns the ServiceNow incident opened for a group, refreshed from the
        connected instance, with its work notes and comments. `null` when the
        group has never been sent.

        This is the same action as `/api/insights/groups/{id}/…`, reached
        through the chatbot group listing.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceNowTicket'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/chatbot/groups/{id}/get-pagerduty-ticket/:
    get:
      tags:
      - Integrations
      operationId: Retrieve PagerDuty Ticket Of Chatbot Insight Group
      description: |-
        HTTP METHOD: GET
        Returns the PagerDuty incident created for a group, refreshed from
        PagerDuty, with its log entries and notes. `null` when the group has never
        been sent.

        This is the same action as `/api/insights/groups/{id}/…`, reached
        through the chatbot group listing.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagerDutyTicket'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/insights/comments/data/:
    get:
      tags:
      - Insight Groups
      operationId: List Comments
      description: |-
        HTTP METHOD: GET
        Returns the comment thread of one insight group, oldest first. Every
        comment carries its replies, the relative age of the post (`2 hours ago`)
        and `has_right`, which tells the client whether the caller may edit or
        delete it.
      parameters:
      - name: group_id
        in: query
        required: true
        description: Identifier of the insight group the thread belongs to.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  comments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Comment'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Insight Groups
      operationId: Create Comment
      description: |-
        HTTP METHOD: POST
        Posts a comment on an insight group. The group is named by the `group_id`
        query parameter, the text by the body.
      parameters:
      - name: group_id
        in: query
        required: true
        description: Identifier of the insight group.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
              example:
                message: Comment successfully created
                status: success
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - text
              properties:
                text:
                  type: string
        required: true
  /api/insights/comments/data/{id}/:
    put:
      tags:
      - Insight Groups
      operationId: Update Comment
      description: |-
        HTTP METHOD: PUT
        Edits the text of a comment. The comment is marked as edited.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - text
              properties:
                text:
                  type: string
        required: true
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the comment.
      schema:
        type: string
  /api/insights/comments/data/reply/:
    post:
      tags:
      - Insight Groups
      operationId: Create Reply
      description: |-
        HTTP METHOD: POST
        Replies to a comment.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Reply successfully created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - parent_id
              - text
              properties:
                parent_id:
                  type: string
                  description: Identifier of the comment being replied to.
                text:
                  type: string
        required: true
    put:
      tags:
      - Insight Groups
      operationId: Update Reply
      description: |-
        HTTP METHOD: PUT
        Edits the text of a reply.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - reply_id
              - text
              properties:
                reply_id:
                  type: string
                text:
                  type: string
        required: true
  /api/insights/comments/data/reply/{reply_id}/:
    delete:
      tags:
      - Insight Groups
      operationId: Delete Reply
      description: |-
        HTTP METHOD: DELETE
        Deletes a reply.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Reply successfully deleted
        '204':
          description: No reply with this identifier
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: reply_id
      in: path
      required: true
      description: Identifier of the reply.
      schema:
        type: string
  /api/insights/filter/sources/:
    post:
      tags:
      - Insight Filters
      operationId: List Insight Sources
      description: |-
        HTTP METHOD: POST
        Returns the sources (indices) that currently carry insights the caller may
        read — the values the source filter of the insights page offers.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  sources:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
  /api/insights/filter/levels/:
    get:
      tags:
      - Insight Filters
      operationId: List Insight Levels
      description: |-
        HTTP METHOD: GET
        Returns the severity levels the insights page can filter on, in display
        order.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  levels:
                    type: array
                    items:
                      type: string
              example:
                levels:
                - critical
                - major
                - minor
                - unknown
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/filter/states/:
    get:
      tags:
      - Insight Filters
      operationId: List Insight States
      description: |-
        HTTP METHOD: GET
        Returns the states an insight group can be in, as code and title pairs.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  states:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: integer
                        title:
                          type: string
              example:
                states:
                - code: 0
                  title: active
                - code: 1
                  title: unhandled
                - code: 2
                  title: resolved
                - code: 3
                  title: ignored
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/filter/interval/:
    get:
      tags:
      - Insight Filters
      operationId: List Insight Intervals
      description: |-
        HTTP METHOD: GET
        Returns the predefined periods the insights page offers, for example
        `Last 24 hours` or `Last 30 days`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  interval:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/filter/assigned-users/:
    get:
      tags:
      - Insight Filters
      operationId: List Assigned Users
      description: |-
        HTTP METHOD: GET
        Returns the identifiers of every user who is assigned to at least one
        insight group, so the assignee filter can be populated.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  assigned_users:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/filter/label_tag_fields/:
    post:
      tags:
      - Insight Filters
      operationId: List Label Tag Fields
      description: |-
        HTTP METHOD: POST
        Returns the label-tag fields configured for the given sources — the extra
        fields an environment chose to surface on the insights listing.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: array
                    items:
                      type: string
        '400':
          description: '`sources` missing'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Sources are missing
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - sources
              properties:
                sources:
                  type: array
                  items:
                    type: string
        required: true
  /api/insights/filter/label_tag_values/:
    post:
      tags:
      - Insight Filters
      operationId: List Label Tag Values
      description: |-
        HTTP METHOD: POST
        Returns the distinct values insights carry for the given label-tag fields.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  values:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - fields
              properties:
                fields:
                  type: array
                  items:
                    type: string
        required: true
  /api/insights/filter/object/:
    get:
      tags:
      - Insight Filters
      operationId: List Saved Filters
      description: |-
        HTTP METHOD: GET
        Returns the filters the caller has saved. A saved filter can be marked as
        the favourite one (applied on page load) and/or pinned as a tab, in which
        case `position` gives its place in the tab bar.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/SavedInsightFilter'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Insight Filters
      operationId: Create Saved Filter
      description: |-
        HTTP METHOD: POST
        Saves a filter for the caller. Marking it as favourite clears the flag on
        the previously favourite filter; pinning it as a tab without a `position`
        appends it to the end of the tab bar, and with one inserts it there,
        shifting the tabs on its right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: User filter been successfully created
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedInsightFilterBody'
        required: true
  /api/insights/filter/object/{id}/:
    put:
      tags:
      - Insight Filters
      operationId: Update Saved Filter
      description: |-
        HTTP METHOD: PUT
        Updates a saved filter. Moving a pinned tab to another position swaps it
        with the tab already there; unpinning it closes the gap it leaves behind.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: User filter been successfully updated
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedInsightFilterBody'
        required: true
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the saved filter.
      schema:
        type: string
  /api/insights/dashboard/charts/:
    get:
      tags:
      - Insight Dashboard
      operationId: List Insight Charts
      description: |-
        HTTP METHOD: GET
        Returns the caller's insights dashboard: its grid layout and the charts on
        it. The dashboard, with its default set of charts, is created on first
        access.

        The same set of endpoints exists under `/api/insights/v3/dashboard/charts/`
        for the Overview page, which keeps a dashboard of its own.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightDashboard'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/dashboard/charts/{id}/:
    get:
      tags:
      - Insight Dashboard
      operationId: Retrieve Insight Chart
      description: |-
        HTTP METHOD: GET
        Computes and returns the data of one chart of the insights dashboard.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: object
                    description: Chart data, shaped after the chart type.
        '400':
          description: The chart produced no data
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: No results found
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Insight Dashboard
      operationId: Update Insight Dashboard
      description: |-
        HTTP METHOD: PUT
        Stores the grid layout of the insights dashboard after the user has moved
        or resized its charts.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                grid_layout:
                  type: object
                  description: Layout description, stored as given.
        required: true
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the chart.
      schema:
        type: string
  /api/insights/dashboard/charts/update_chart/:
    put:
      tags:
      - Insight Dashboard
      operationId: Update Insight Chart
      description: |-
        HTTP METHOD: PUT
        Changes the period a chart reports on, or turns it off.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
        '404':
          description: Malformed interval
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: Identifier of the chart.
                interval:
                  type: string
                  description: JSON encoded period object.
                is_active:
                  type: boolean
        required: true
  /api/insights/dashboard/charts/sources/:
    get:
      tags:
      - Insight Dashboard
      operationId: List Dashboard Sources
      description: |-
        HTTP METHOD: GET
        Returns every source the caller may read, each flagged with whether the
        insights dashboard currently shows it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    source:
                      type: string
                    visible:
                      type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/dashboard/charts/update_sources/:
    put:
      tags:
      - Insight Dashboard
      operationId: Update Dashboard Sources
      description: |-
        HTTP METHOD: PUT
        Sets the sources the insights dashboard hides.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          description: '`hidden_indices` missing'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - hidden_indices
              properties:
                hidden_indices:
                  type: array
                  items:
                    type: string
        required: true
  /api/insights/dashboard/charts/date/:
    get:
      tags:
      - Insight Dashboard
      operationId: List Chart Date Options
      description: |-
        HTTP METHOD: GET
        Returns the periods a dashboard chart can report on, split into the
        `last …` options and the predefined named ranges.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: object
                    properties:
                      last:
                        type: array
                        items:
                          type: object
                      predefined:
                        type: array
                        items:
                          type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/v3/dashboard/charts/:
    get:
      tags:
      - Insight Dashboard
      operationId: List Overview Charts
      description: |-
        HTTP METHOD: GET
        Returns the caller's Overview dashboard: its grid layout and the charts on
        it. The dashboard, with its default set of charts, is created on first
        access.

        These endpoints mirror `/api/insights/dashboard/charts/` one for one; the
        two pages keep separate dashboards, so a chart moved on one does not move
        on the other.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightDashboard'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/v3/dashboard/charts/{id}/:
    get:
      tags:
      - Insight Dashboard
      operationId: Retrieve Overview Chart
      description: |-
        HTTP METHOD: GET
        Computes and returns the data of one chart of the Overview dashboard.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: object
                    description: Chart data, shaped after the chart type.
        '400':
          description: The chart produced no data
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: No results found
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Insight Dashboard
      operationId: Update Overview Dashboard
      description: |-
        HTTP METHOD: PUT
        Stores the grid layout of the Overview dashboard after the user has moved
        or resized its charts.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                grid_layout:
                  type: object
                  description: Layout description, stored as given.
        required: true
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the chart.
      schema:
        type: string
  /api/insights/v3/dashboard/charts/update_chart/:
    put:
      tags:
      - Insight Dashboard
      operationId: Update Overview Chart
      description: |-
        HTTP METHOD: PUT
        Changes the period a chart reports on, or turns it off.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
        '404':
          description: Malformed interval
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: Identifier of the chart.
                interval:
                  type: string
                  description: JSON encoded period object.
                is_active:
                  type: boolean
        required: true
  /api/insights/v3/dashboard/charts/sources/:
    get:
      tags:
      - Insight Dashboard
      operationId: List Overview Dashboard Sources
      description: |-
        HTTP METHOD: GET
        Returns every source the caller may read, each flagged with whether the
        Overview dashboard currently shows it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    source:
                      type: string
                    visible:
                      type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/v3/dashboard/charts/update_sources/:
    put:
      tags:
      - Insight Dashboard
      operationId: Update Overview Dashboard Sources
      description: |-
        HTTP METHOD: PUT
        Sets the sources the Overview dashboard hides.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          description: '`hidden_indices` missing'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - hidden_indices
              properties:
                hidden_indices:
                  type: array
                  items:
                    type: string
        required: true
  /api/insights/v3/dashboard/charts/date/:
    get:
      tags:
      - Insight Dashboard
      operationId: List Overview Chart Date Options
      description: |-
        HTTP METHOD: GET
        Returns the periods a dashboard chart can report on, split into the
        `last …` options and the predefined named ranges.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: object
                    properties:
                      last:
                        type: array
                        items:
                          type: object
                      predefined:
                        type: array
                        items:
                          type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/notifications/data/:
    get:
      tags:
      - Insight Notifications
      operationId: List Notification Recipients
      description: |-
        HTTP METHOD: GET
        Returns the notification recipients the caller has configured. A recipient
        binds a channel — email, Slack, Microsoft Teams, Jira, ServiceNow,
        PagerDuty — to one or more filter groups; an insight is delivered when it
        matches any of them.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  recipients:
                    type: array
                    items:
                      $ref: '#/components/schemas/NotificationRecipient'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Insight Notifications
      operationId: Create Notification Recipient
      description: |-
        HTTP METHOD: POST
        Registers a notification recipient. The fields required next to `channel`
        depend on the channel:

          - `email` — `email`; one recipient per address.
          - `slack`, `microsoftteams` — `webhook_url`, validated against the
            provider before it is stored.
          - `jira` — an existing Jira integration plus `project_id`; optional
            `board_id`, `sprint_id`, `issue_type` and `trigger` (`manual` or
            `automatic`). One recipient per trigger.
          - `servicenow` — an existing ServiceNow integration, optional `trigger`.
            One recipient in total.
          - `pagerduty` — an existing PagerDuty integration plus `service_id`,
            optional `service_name` and `trigger`.

        `filter_groups` decides what is delivered; the legacy flat fields
        (`sources`, `severities`, `services`, `service_groups`, `entities`) are
        still accepted and are returned folded into a single group.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
              example:
                message: Email notification successfully added for ops@example.com
        '400':
          description: Channel unknown, integration missing, or recipient already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationRecipientBody'
        required: true
  /api/insights/notifications/data/{id}/:
    put:
      tags:
      - Insight Notifications
      operationId: Update Notification Recipient
      description: |-
        HTTP METHOD: PUT
        Updates the title, the filter groups or the channel settings of a
        notification recipient.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationRecipientBody'
        required: true
    delete:
      tags:
      - Insight Notifications
      operationId: Delete Notification Recipient
      description: |-
        HTTP METHOD: DELETE
        Removes a notification recipient.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the notification recipient.
      schema:
        type: string
  /api/insights/notifications/data/filter/:
    post:
      tags:
      - Insight Notifications
      operationId: List Notification Filter Options
      description: |-
        HTTP METHOD: POST
        Returns everything the notification form needs to be built: the sources
        that carry insights, the severity levels, and the channels the platform
        supports.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: object
                    properties:
                      sources:
                        type: array
                        items:
                          type: string
                      levels:
                        type: array
                        items:
                          type: string
                      channels:
                        type: array
                        items:
                          type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
  /api/insights/notifications/data/check_creds/:
    post:
      tags:
      - Insight Notifications
      operationId: Check ServiceNow Credentials
      description: |-
        HTTP METHOD: POST
        Tests a ServiceNow instance and basic-auth credentials by reading a single
        incident from it, and reports whether the call succeeded.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - webhook
              - username
              - password
              properties:
                webhook:
                  type: string
                  description: Base URL of the ServiceNow instance.
                username:
                  type: string
                password:
                  type: string
        required: true
  /api/insights/notifications/data/sources/:
    post:
      tags:
      - Insight Notifications
      operationId: List Notification Sources
      description: |-
        HTTP METHOD: POST
        The sources a notification can be filtered on. Mirrors
        `/api/insights/filter/sources/`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  sources:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
  /api/insights/notifications/data/levels/:
    get:
      tags:
      - Insight Notifications
      operationId: List Notification Levels
      description: |-
        HTTP METHOD: GET
        Returns the severity levels the insights page can filter on, in display
        order.

        Same data as `/api/insights/filter/levels/`, served under the
        notification prefix so the notification form can read it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  levels:
                    type: array
                    items:
                      type: string
              example:
                levels:
                - critical
                - major
                - minor
                - unknown
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/notifications/data/states/:
    get:
      tags:
      - Insight Notifications
      operationId: List Notification States
      description: |-
        HTTP METHOD: GET
        Returns the states an insight group can be in, as code and title pairs.

        Same data as `/api/insights/filter/states/`, served under the
        notification prefix so the notification form can read it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  states:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: integer
                        title:
                          type: string
              example:
                states:
                - code: 0
                  title: active
                - code: 1
                  title: unhandled
                - code: 2
                  title: resolved
                - code: 3
                  title: ignored
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/notifications/data/interval/:
    get:
      tags:
      - Insight Notifications
      operationId: List Notification Intervals
      description: |-
        HTTP METHOD: GET
        Returns the predefined periods the insights page offers, for example
        `Last 24 hours` or `Last 30 days`.

        Same data as `/api/insights/filter/interval/`, served under the
        notification prefix so the notification form can read it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  interval:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/notifications/data/assigned-users/:
    get:
      tags:
      - Insight Notifications
      operationId: List Notification Assigned Users
      description: |-
        HTTP METHOD: GET
        Returns the identifiers of every user who is assigned to at least one
        insight group, so the assignee filter can be populated.

        Same data as `/api/insights/filter/assigned-users/`, served under the
        notification prefix so the notification form can read it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  assigned_users:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/notifications/data/label_tag_fields/:
    post:
      tags:
      - Insight Notifications
      operationId: List Notification Label Tag Fields
      description: |-
        HTTP METHOD: POST
        Returns the label-tag fields configured for the given sources — the extra
        fields an environment chose to surface on the insights listing.

        Same data as `/api/insights/filter/label_tag_fields/`, served under the
        notification prefix so the notification form can read it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: array
                    items:
                      type: string
        '400':
          description: '`sources` missing'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Sources are missing
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - sources
              properties:
                sources:
                  type: array
                  items:
                    type: string
        required: true
  /api/insights/notifications/data/label_tag_values/:
    post:
      tags:
      - Insight Notifications
      operationId: List Notification Label Tag Values
      description: |-
        HTTP METHOD: POST
        Returns the distinct values insights carry for the given label-tag fields.

        Same data as `/api/insights/filter/label_tag_values/`, served under the
        notification prefix so the notification form can read it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  values:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - fields
              properties:
                fields:
                  type: array
                  items:
                    type: string
        required: true
  /api/insights/integrations/jira/:
    post:
      tags:
      - Integrations
      operationId: Connect Jira
      description: |-
        HTTP METHOD: POST
        Starts the Jira OAuth flow and returns the Atlassian URL the user has to
        be sent to. `return_url` is where the browser lands once consent is given.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  auth_url:
                    type: string
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                return_url:
                  type: string
                  description: Page to return to after authorization.
  /api/insights/integrations/jira/callback/:
    get:
      tags:
      - Integrations
      operationId: Jira OAuth Callback
      description: |-
        HTTP METHOD: GET
        Redirect target of the Jira OAuth flow. Atlassian calls it with `code` and
        `state`; Logmind exchanges the code for tokens, stores the integration and
        redirects the browser back to the page the flow started from. It is not
        meant to be called directly.
      parameters:
      - name: code
        in: query
        required: false
        description: Authorization code issued by Atlassian.
        schema:
          type: string
      - name: state
        in: query
        required: false
        description: Opaque state carried through the flow.
        schema:
          type: string
      security: []
      responses:
        '302':
          description: Redirect back to the application
  /api/insights/integrations/jira/status/:
    get:
      tags:
      - Integrations
      operationId: Retrieve Jira Status
      description: |-
        HTTP METHOD: GET
        Returns the Jira integration of the caller — the connected site, the
        account, and whether a manual notification is configured on it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/integrations/jira/disconnect/:
    post:
      tags:
      - Integrations
      operationId: Disconnect Jira
      description: |-
        HTTP METHOD: POST
        Removes the Jira integration together with the notification recipients
        that depend on it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: JIRA integration disconnected successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/integrations/jira/overview/projects/:
    get:
      tags:
      - Integrations
      operationId: List Jira Projects
      description: |-
        HTTP METHOD: GET
        Returns the Jira projects reachable with the connected account, each
        flagged with whether it is the one the manual notification uses.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  projects:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/integrations/jira/overview/boards/:
    post:
      tags:
      - Integrations
      operationId: List Jira Boards
      description: |-
        HTTP METHOD: POST
        Returns the boards of a Jira project.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  boards:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
  /api/insights/integrations/jira/overview/sprints/:
    post:
      tags:
      - Integrations
      operationId: List Jira Sprints
      description: |-
        HTTP METHOD: POST
        Returns the active sprints of a board.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  active_sprints:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                board_id:
                  type: string
                project_id:
                  type: string
                board_name:
                  type: string
        required: true
  /api/insights/integrations/jira/overview/issue-types/:
    post:
      tags:
      - Integrations
      operationId: List Jira Issue Types
      description: |-
        HTTP METHOD: POST
        Returns the issue types available in a Jira project.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  issue_types:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
        required: true
  /api/insights/integrations/jira/overview/priorities/:
    get:
      tags:
      - Integrations
      operationId: List Jira Priorities
      description: |-
        HTTP METHOD: GET
        Returns the priorities defined in the connected Jira site.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  priorities:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/integrations/jira/overview/get-users/:
    post:
      tags:
      - Integrations
      operationId: List Jira Assignees
      description: |-
        HTTP METHOD: POST
        Returns the users an issue of the given project can be assigned to.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
        required: true
  /api/insights/integrations/servicenow/:
    post:
      tags:
      - Integrations
      operationId: Connect ServiceNow
      description: |-
        HTTP METHOD: POST
        Starts the ServiceNow OAuth flow and returns the URL to send the user to.
        Customers supply their own instance and OAuth application credentials;
        when they are omitted the configured development instance is used.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  auth_url:
                    type: string
                  message:
                    type: string
        '400':
          description: '`instance_url` or `client_id` missing'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                instance_url:
                  type: string
                  description: https://<your-instance>.service-now.com
                client_id:
                  type: string
                client_secret:
                  type: string
                return_url:
                  type: string
  /api/insights/integrations/servicenow/callback/:
    get:
      tags:
      - Integrations
      operationId: ServiceNow OAuth Callback
      description: |-
        HTTP METHOD: GET
        Redirect target of the ServiceNow OAuth flow. Not meant to be called
        directly.
      security: []
      responses:
        '302':
          description: Redirect back to the application
  /api/insights/integrations/servicenow/status/:
    get:
      tags:
      - Integrations
      operationId: Retrieve ServiceNow Status
      description: |-
        HTTP METHOD: GET
        Returns the ServiceNow integration of the caller: the instance, the
        display name and the caller email incidents are opened with.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/integrations/servicenow/disconnect/:
    post:
      tags:
      - Integrations
      operationId: Disconnect ServiceNow
      description: |-
        HTTP METHOD: POST
        Removes the ServiceNow integration together with the notification
        recipients that depend on it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/integrations/servicenow/fields/:
    get:
      tags:
      - Integrations
      operationId: List ServiceNow Fields
      description: |-
        HTTP METHOD: GET
        Returns the field choices an incident form needs, read live from the
        connected instance: the choice lists (`state`, `category`, `subcategory`,
        `contact_type`, `impact`, `urgency`) and the reference lists
        (`assignment_groups`, `users`, `business_services`). `search` filters the
        reference lists by name.
      parameters:
      - name: search
        in: query
        required: false
        description: Filters the reference lists by name.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: array
                    items:
                      type: object
                  category:
                    type: array
                    items:
                      type: object
                  subcategory:
                    type: array
                    items:
                      type: object
                  contact_type:
                    type: array
                    items:
                      type: object
                  impact:
                    type: array
                    items:
                      type: object
                  urgency:
                    type: array
                    items:
                      type: object
                  assignment_groups:
                    type: array
                    items:
                      type: object
                  users:
                    type: array
                    items:
                      type: object
                  business_services:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/integrations/pagerduty/:
    post:
      tags:
      - Integrations
      operationId: Connect PagerDuty
      description: |-
        HTTP METHOD: POST
        Starts the PagerDuty OAuth flow and returns the URL to send the user to.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  auth_url:
                    type: string
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                return_url:
                  type: string
  /api/insights/integrations/pagerduty/callback/:
    get:
      tags:
      - Integrations
      operationId: PagerDuty OAuth Callback
      description: |-
        HTTP METHOD: GET
        Redirect target of the PagerDuty OAuth flow. Not meant to be called
        directly.
      security: []
      responses:
        '302':
          description: Redirect back to the application
  /api/insights/integrations/pagerduty/status/:
    get:
      tags:
      - Integrations
      operationId: Retrieve PagerDuty Status
      description: |-
        HTTP METHOD: GET
        Returns the PagerDuty integration of the caller.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/integrations/pagerduty/disconnect/:
    post:
      tags:
      - Integrations
      operationId: Disconnect PagerDuty
      description: |-
        HTTP METHOD: POST
        Removes the PagerDuty integration together with the notification
        recipients that depend on it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/integrations/pagerduty/services/:
    get:
      tags:
      - Integrations
      operationId: List PagerDuty Services
      description: |-
        HTTP METHOD: GET
        Returns the services of the connected PagerDuty account, each flagged with
        whether it is the one the notification recipient uses.
      parameters:
      - name: search
        in: query
        required: false
        description: Filters the services by name.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  services:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        status:
                          type: string
                        is_selected:
                          type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/integrations/pagerduty/overview/users/:
    get:
      tags:
      - Integrations
      operationId: List PagerDuty Users
      description: |-
        HTTP METHOD: GET
        Returns the account users an incident can be assigned to.
      parameters:
      - name: search
        in: query
        required: false
        description: Filters the users by name.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        email:
                          type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/integrations/pagerduty/overview/escalation-policies/:
    get:
      tags:
      - Integrations
      operationId: List PagerDuty Escalation Policies
      description: |-
        HTTP METHOD: GET
        Returns the escalation policies of the connected account.
      parameters:
      - name: search
        in: query
        required: false
        description: Filters the policies by name.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  escalation_policies:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/integrations/pagerduty/overview/priorities/:
    get:
      tags:
      - Integrations
      operationId: List PagerDuty Priorities
      description: |-
        HTTP METHOD: GET
        Returns the incident priorities of the connected account; the list is
        empty when priorities are not enabled on it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  priorities:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/integrations/pagerduty/overview/urgencies/:
    get:
      tags:
      - Integrations
      operationId: List PagerDuty Urgencies
      description: |-
        HTTP METHOD: GET
        Returns the urgency values an incident can be created with.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  urgencies:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/insights/integrations/pagerduty/overview/statuses/:
    get:
      tags:
      - Integrations
      operationId: List PagerDuty Statuses
      description: |-
        HTTP METHOD: GET
        Returns the status values an incident can be created with.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  statuses:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/search/query/:
    post:
      tags:
      - Search
      operationId: Run Search
      description: |-
        HTTP METHOD: POST
        Runs a Logmind Query Language (LQL) query and returns the matching events,
        the fields they carry, the aggregations the query asked for and — when
        `timeline` is set — the distribution of the hits over time.

        The query is parsed, translated into an Elasticsearch query and executed
        against the sources the caller has access to. When no `times` is given the
        last 7 days are searched. `limit` is capped by the platform maximum page
        size, and paging further into a result set is done with `offset` or, for
        deep pages, with `search_after` / `after`.

        With `ai_mode` enabled the natural-language text in `q` is turned into a
        query first, and the generated query is returned alongside the results.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchQueryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchQueryBody'
        required: true
  /api/search/search/query/update/:
    post:
      tags:
      - Search
      operationId: Update Query String
      description: |-
        HTTP METHOD: POST
        Rewrites an LQL query string for the user interface: adds or removes a
        filter or an order-by clause, adds a field to the selection, or narrows the
        selection to a single field. Returns the new query string; nothing is
        executed.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryUpdateBody'
        required: true
  /api/search/search/vs/query/:
    post:
      tags:
      - Search
      operationId: Run Visualization Query
      description: |-
        HTTP METHOD: POST
        Runs the query behind a visualization and returns its aggregation buckets.
        Unlike the search endpoint it is built for charts: it supports composite
        aggregation paging through `after` / `prevs` / `is_prev`, and a
        `max_results` ceiling on the number of buckets.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  aggs:
                    type: object
                  total:
                    type: integer
                  query:
                    type: object
                  after:
                    type: object
                    nullable: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VisualizationQueryBody'
        required: true
  /api/search/search/report/:
    post:
      tags:
      - Search
      operationId: Create Report
      description: |-
        HTTP METHOD: POST
        Schedules the export of a search result. The file is produced in the
        background and a download link is emailed to the caller. A filename that
        is already taken by a pending report is suffixed with a counter.
      responses:
        '201':
          description: Report scheduled
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: report created successfully, we will sent link in email
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportBody'
        required: true
  /api/search/search/sources/:
    post:
      tags:
      - Search
      operationId: List Sources
      description: |-
        HTTP METHOD: POST
        Returns every source known to the environment as `label` / `value` pairs,
        for the source picker of the search bar.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    label:
                      type: string
                    value:
                      type: string
                    type:
                      type: string
                      nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
  /api/search/search/fields/:
    post:
      tags:
      - Search
      operationId: List Fields
      description: |-
        HTTP METHOD: POST
        Returns the fields of the sources the caller has access to, with their
        type and whether they are displayed by default. This is the field list the
        search sidebar is built from.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SearchField'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                sources:
                  type: array
                  description: Restrict the fields to these sources.
                  items:
                    type: string
  /api/search/search/available_fields/:
    post:
      tags:
      - Search
      operationId: List Available Fields
      description: |-
        HTTP METHOD: POST
        Returns the fields that actually occur in the result of a given query —
        the fields a timeline or a breakdown can be built on. Paginated with
        `limit` and `offset`, and searchable with `field_name`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchField'
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - q
              - times
              properties:
                q:
                  type: string
                  description: The LQL query the fields are collected for.
                times:
                  type: object
                  description: Period of the query.
                field_name:
                  type: string
                  description: Case-insensitive match on the field name.
                exclude_fields:
                  type: array
                  items:
                    type: string
                ai_mode:
                  type: boolean
                timeline_fields:
                  type: boolean
                  description: Include the fields a timeline can be broken down by.
                limit:
                  type: integer
                offset:
                  type: integer
        required: true
  /api/search/search/fields_data/:
    post:
      tags:
      - Search
      operationId: Retrieve Fields Data
      description: |-
        HTTP METHOD: POST
        Returns, for one query, the distribution of the displayed, context and
        hidden fields — the small value bars the search sidebar draws next to each
        field. Answers are cached per environment and query for a short period.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  aggs:
                    type: object
                    properties:
                      stats:
                        type: object
                        properties:
                          DisplayFields:
                            type: array
                            items:
                              type: object
                          ContextFields:
                            type: array
                            items:
                              type: object
                          HiddenFields:
                            type: array
                            items:
                              type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: object
                  description: Elasticsearch query the fields are summarised over.
                indices:
                  type: array
                  items:
                    type: string
                display_fields:
                  type: array
                  items:
                    type: string
                hidden_fields:
                  type: array
                  items:
                    type: string
        required: true
  /api/search/search/field_details/:
    post:
      tags:
      - Search
      operationId: Retrieve Field Details
      description: |-
        HTTP METHOD: POST
        Returns the top values of one field within the result of a query, with
        their document counts, paginated through `page` and `size`. Passing
        `pattern_id` scopes the values to a single message pattern.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  buckets:
                    type: array
                    items:
                      type: object
                      properties:
                        value:
                          type: string
                        count:
                          type: integer
                  total:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - field
              properties:
                field:
                  type: string
                size:
                  type: integer
                page:
                  type: integer
                indices:
                  type: array
                  items:
                    type: string
                query:
                  type: object
                pattern_id:
                  type: string
                query_filter:
                  type: object
        required: true
  /api/search/search/patterns/:
    post:
      tags:
      - Search
      operationId: List Query Patterns
      description: |-
        HTTP METHOD: POST
        Returns the message patterns found in the result of a query. A pattern
        stands for a family of near-identical log lines, with the variable parts
        replaced by placeholders.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: object
                    properties:
                      total:
                        type: array
                        items:
                          type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: object
                indices:
                  type: array
                  items:
                    type: string
        required: true
  /api/search/search/patterns/placeholders/:
    post:
      tags:
      - Search
      operationId: List Pattern Placeholders
      description: |-
        HTTP METHOD: POST
        Returns the values that occur behind the placeholders of a message
        pattern, so a pattern can be expanded back into the concrete lines it
        stands for.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceholdersResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaceholdersBody'
        required: true
  /api/search/search/surrounding_logs/:
    post:
      tags:
      - Search
      operationId: List Surrounding Logs
      description: |-
        HTTP METHOD: POST
        Returns the log lines recorded around one event — half of `size` before it
        and half after — with the event itself in the middle, flagged as
        `main_event`. `filtering_fields` narrows the context to the lines that
        share those field values, for example the same host or the same service.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      type: object
                  total:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - event
              properties:
                event:
                  type: object
                  description: The event to center the context on, as returned by search.
                filtering_fields:
                  type: array
                  description: Fields whose values the surrounding lines must share.
                  items:
                    type: string
                size:
                  type: integer
                  description: Total number of surrounding lines to return.
        required: true
  /api/search/search/query_keywords/:
    get:
      tags:
      - Search
      operationId: List Query Keywords
      description: |-
        HTTP METHOD: GET
        Returns the reserved words of the Logmind Query Language, for syntax
        highlighting and auto-completion in the search bar.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  keywords:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/search/source_types/:
    get:
      tags:
      - Search
      operationId: List Source Types
      description: |-
        HTTP METHOD: GET
        Returns the Elasticsearch source types of the environment.

        **Deprecated.** Use `/api/search/search/sources/` or
        `/api/components/sources/` instead.
      deprecated: true
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/search/query/recent/:
    get:
      tags:
      - Search
      operationId: List Recent Queries
      description: |-
        HTTP METHOD: GET
        Returns the queries the caller ran most recently, newest first. The list
        is bounded: once it is full, saving a new one drops the oldest.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecentQuery'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Search
      operationId: Create Recent Query
      description: |-
        HTTP METHOD: POST
        Records a query in the caller's recent list.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                times:
                  type: object
                display_query:
                  type: string
                ai_mode:
                  type: boolean
        required: true
  /api/search/search/query/recent/{id}/:
    get:
      tags:
      - Search
      operationId: Retrieve Recent Query
      description: |-
        HTTP METHOD: GET
        Returns one entry of the recent queries list.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    $ref: '#/components/schemas/RecentQuery'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Search
      operationId: Delete Recent Query
      description: |-
        HTTP METHOD: DELETE
        Removes one entry from the recent queries list.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: successfully deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the recent query.
      schema:
        type: string
  /api/search/search/query/saved/:
    get:
      tags:
      - Search
      operationId: List Saved Queries
      description: |-
        HTTP METHOD: GET
        Returns the queries the caller has saved, with their title, period and the
        visualizations attached to them.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/SavedQuery'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Search
      operationId: Create Saved Query
      description: |-
        HTTP METHOD: POST
        Saves a query under a title. Marking it as `is_default` clears the flag on
        the query that held it before.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Your query has been saved successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedQueryBody'
        required: true
  /api/search/search/query/saved/{id}/:
    get:
      tags:
      - Search
      operationId: Retrieve Saved Query
      description: |-
        HTTP METHOD: GET
        Returns one saved query.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    $ref: '#/components/schemas/SavedQuery'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Search
      operationId: Update Saved Query
      description: |-
        HTTP METHOD: PUT
        Updates a saved query.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedQueryBody'
        required: true
    patch:
      tags:
      - Search
      operationId: Partially Update Saved Query
      description: |-
        HTTP METHOD: PATCH
        A partial update of the saved query: the body of `PUT` on this path, with every
        field optional. Only the fields present are changed.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedQueryBody'
        required: true
    delete:
      tags:
      - Search
      operationId: Delete Saved Query
      description: |-
        HTTP METHOD: DELETE
        Deletes a saved query. Requires the `discover_delete` right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the saved query.
      schema:
        type: string
  /api/search/search/smart_search/feedback/:
    get:
      tags:
      - Search
      operationId: List Smart Search Feedback
      description: |-
        HTTP METHOD: GET
        Returns the feedback recorded on AI generated queries.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Search
      operationId: Send Smart Search Feedback
      description: |-
        HTTP METHOD: POST
        Records whether an AI generated query answered what the user asked for.
        The natural-language input, the generated Elasticsearch query and the
        sources it ran against are stored with the verdict, and are used to improve
        the model behind AI search.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: feedback successfully sent
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_input:
                  type: string
                  description: The natural-language question the user typed.
                query:
                  type: object
                  description: The Elasticsearch query that was generated.
                indices:
                  type: array
                  items:
                    type: string
                modugpt_feedback:
                  type: string
                  description: The verdict on the generated query.
                is_aggs:
                  type: boolean
        required: true
  /api/search/search/smart_search/feedback/{id}/:
    get:
      tags:
      - Search
      operationId: Retrieve Smart Search Feedback
      description: |-
        HTTP METHOD: GET
        Returns one recorded piece of feedback on an AI generated query.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Search
      operationId: Update Smart Search Feedback
      description: |-
        HTTP METHOD: PUT
        Replaces a recorded piece of feedback.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
        required: true
    patch:
      tags:
      - Search
      operationId: Partially Update Smart Search Feedback
      description: |-
        HTTP METHOD: PATCH
        A partial update of the feedback record: the body of `PUT` on this path, with every
        field optional. Only the fields present are changed.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
        required: true
    delete:
      tags:
      - Search
      operationId: Delete Smart Search Feedback
      description: |-
        HTTP METHOD: DELETE
        Removes a recorded piece of feedback.
      responses:
        '204':
          description: Feedback deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the feedback entry.
      schema:
        type: string
  /api/search/lpl/builder/:
    post:
      tags:
      - Search
      operationId: Build Query
      description: |-
        HTTP METHOD: POST
        Rebuilds an LQL query string from what the query builder has selected —
        sources, services, service groups and entities — keeping the rest of the
        statement the user has typed intact. Returns the resulting query string
        together with its validation state.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - current_query_string
              - query_builder
              properties:
                current_query_string:
                  type: string
                ai_mode:
                  type: boolean
                query_builder:
                  type: object
                  required:
                  - services
                  - groups
                  - entities
                  - data_source
                  properties:
                    services:
                      type: array
                      items:
                        type: string
                    groups:
                      type: array
                      items:
                        type: string
                    entities:
                      type: array
                      items:
                        type: string
                    data_source:
                      type: object
                      properties:
                        sources:
                          type: array
                          items:
                            type: string
        required: true
  /api/search/lpl/operators/:
    get:
      tags:
      - Search
      operationId: List Query Operators
      description: |-
        HTTP METHOD: GET
        Returns the comparison and boolean operators the Logmind Query Language
        supports, with the label the query builder shows for each.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/lpl/functions/:
    get:
      tags:
      - Search
      operationId: List Query Functions
      description: |-
        HTTP METHOD: GET
        Returns the aggregation functions available in the Logmind Query Language,
        such as `count`, `avg`, `min`, `max` or `sum`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/lpl/bucket_units/:
    get:
      tags:
      - Search
      operationId: List Bucket Units
      description: |-
        HTTP METHOD: GET
        Returns the time units a `GROUP BY` over time can bucket on.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/time_builder/quick_list/:
    get:
      tags:
      - Search
      operationId: List Quick Ranges
      description: |-
        HTTP METHOD: GET
        Returns the quick date ranges the time picker offers, such as
        `Last 15 minutes` or `Today`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DateTimeQuickResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/time_builder/range_types/:
    get:
      tags:
      - Search
      operationId: List Range Types
      description: |-
        HTTP METHOD: GET
        Returns the kinds of range the time picker can build: relative, absolute
        or now.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DateTimeRangeResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/time_builder/time_units/:
    get:
      tags:
      - Search
      operationId: List Time Units
      description: |-
        HTTP METHOD: GET
        Returns the units a relative range can be expressed in — seconds, minutes,
        hours, days, weeks, months, years.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DateTimeUnitResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/time_builder/timeline_intervals/:
    get:
      tags:
      - Search
      operationId: List Timeline Intervals
      description: |-
        HTTP METHOD: GET
        Returns the bucket sizes a search timeline can be drawn with, for example
        `1m`, `1h` or `1d`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/elastic/indices/:
    get:
      tags:
      - Search
      operationId: List Indices
      description: |-
        HTTP METHOD: GET
        Returns the distinct Elasticsearch sources registered in the environment.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/patterns/:
    get:
      tags:
      - Patterns
      operationId: List Patterns
      description: |-
        HTTP METHOD: GET
        Returns the stored message patterns, most recently seen first, with their
        first and last occurrence and their occurrence count. Patterns sit between
        raw log lines and insights: near-identical lines are folded into one
        pattern by the parsing pipeline.
      parameters:
      - name: limit
        in: query
        required: false
        description: Page size.
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: Page number.
        schema:
          type: integer
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPatternsResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Patterns
      operationId: Search Patterns
      description: |-
        HTTP METHOD: POST
        Returns the patterns that occur in the result of a query, ordered by
        occurrence count or by last occurrence, with the entity values attached to
        each. Paginated through `after_key`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePatternsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePattersBody'
        required: true
  /api/search/patterns/critical/mark_pattern/{id}/:
    post:
      tags:
      - Patterns
      operationId: Mark Pattern Critical
      description: |-
        HTTP METHOD: POST
        Marks a pattern as critical, so that new occurrences of it are surfaced
        with priority.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: pattern marked as critical  successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCriticalPatternBody'
        required: true
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier (uuid) of the pattern.
      schema:
        type: string
  /api/search/patterns/critical/unmark_pattern/{id}/:
    post:
      tags:
      - Patterns
      operationId: Unmark Pattern Critical
      description: |-
        HTTP METHOD: POST
        Clears the critical mark of a pattern.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Pattern Unmarked as critical  successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier (uuid) of the pattern.
      schema:
        type: string
  /api/search/feedback/:
    post:
      tags:
      - Help
      operationId: Send Feedback
      description: |-
        HTTP METHOD: POST
        Sends feedback to the Logmind team. The caller's name, environment and
        email address are appended to the message. Screenshots can be attached as
        base64 data URLs in `file`; an attachment above 20 MB is rejected.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedBackSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - subject
              - body
              properties:
                subject:
                  type: string
                body:
                  type: string
                file:
                  type: array
                  description: Attachments, as base64 data URLs.
                  items:
                    type: string
        required: true
  /api/search/dashboards/:
    get:
      tags:
      - Dashboards
      operationId: List Dashboards
      description: |-
        HTTP METHOD: GET
        Returns the dashboards the caller may read — those bound to a source they
        have access to — with their grid layout and their live flag.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Dashboard'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Dashboards
      operationId: Create Dashboard
      description: |-
        HTTP METHOD: POST
        Creates a dashboard. The roles and the sources of the caller are attached
        to it, which is what decides who may open it afterwards. Requires the
        `dashboards_add` right.
      responses:
        '201':
          description: Dashboard created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dashboard'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - title
              properties:
                title:
                  type: string
                status:
                  type: boolean
                is_live:
                  type: boolean
                  description: Refresh the dashboard continuously.
                grid_layout:
                  type: object
                  description: Placement of the visualizations on the grid.
        required: true
  /api/search/dashboards/{id}/:
    get:
      tags:
      - Dashboards
      operationId: Retrieve Dashboard
      description: |-
        HTTP METHOD: GET
        Returns one dashboard with its grid layout.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    $ref: '#/components/schemas/Dashboard'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Dashboards
      operationId: Update Dashboard
      description: |-
        HTTP METHOD: PUT
        Updates a dashboard. Sending `is_favourite` also marks the dashboard as
        the caller's favourite — the one opened by default — or clears that mark.
        Requires the `dashboards_edit` right.
      responses:
        '201':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Dashboard has been successfully updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                status:
                  type: boolean
                is_live:
                  type: boolean
                grid_layout:
                  type: object
                is_favourite:
                  type: boolean
                  description: Mark, or unmark, this dashboard as the caller's favourite.
        required: true
    patch:
      tags:
      - Dashboards
      operationId: Partially Update Dashboard
      description: |-
        HTTP METHOD: PATCH
        A partial update of the dashboard: the body of `PUT` on this path, with every
        field optional. Only the fields present are changed.
      responses:
        '201':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Dashboard has been successfully updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                status:
                  type: boolean
                is_live:
                  type: boolean
                grid_layout:
                  type: object
                is_favourite:
                  type: boolean
                  description: Mark, or unmark, this dashboard as the caller's favourite.
        required: true
    delete:
      tags:
      - Dashboards
      operationId: Delete Dashboard
      description: |-
        HTTP METHOD: DELETE
        Deletes a dashboard and the visualizations on it. Requires the
        `dashboards_delete` right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the dashboard.
      schema:
        type: string
  /api/search/visualizations/:
    get:
      tags:
      - Dashboards
      operationId: List Visualizations
      description: |-
        HTTP METHOD: GET
        Returns the visualizations of a dashboard, with their query configuration,
        their chart data and their anomaly-detection settings.
      parameters:
      - name: dashboard
        in: query
        required: false
        description: Title of the dashboard whose visualizations are returned.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVisualizationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Dashboards
      operationId: Create Visualization
      description: |-
        HTTP METHOD: POST
        Adds a visualization to a dashboard. `query_config` holds the query and the
        chart settings, `data` the rendered chart state; both are stored as JSON.
      responses:
        '201':
          description: Visualization created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateVisualizationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVisualizationBody'
        required: true
  /api/search/visualizations/{id}/:
    get:
      tags:
      - Dashboards
      operationId: Retrieve Visualization
      description: |-
        HTTP METHOD: GET
        Returns one visualization.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    $ref: '#/components/schemas/VisualizationJSON'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Dashboards
      operationId: Update Visualization
      description: |-
        HTTP METHOD: PUT
        Updates the title, the query configuration, the chart data or the
        anomaly-detection settings of a visualization.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVisualizationBody'
        required: true
    patch:
      tags:
      - Dashboards
      operationId: Partially Update Visualization
      description: |-
        HTTP METHOD: PATCH
        A partial update of the visualization: the body of `PUT` on this path, with every
        field optional. Only the fields present are changed.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVisualizationBody'
        required: true
    delete:
      tags:
      - Dashboards
      operationId: Delete Visualization
      description: |-
        HTTP METHOD: DELETE
        Removes a visualization from its dashboard. A `grid_layout` sent along is
        stored on the dashboard, so the remaining charts keep their places.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: successfully deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the visualization.
      schema:
        type: string
  /api/search/visualizations/update_all/:
    put:
      tags:
      - Dashboards
      operationId: Update Visualizations
      description: |-
        HTTP METHOD: PUT
        Updates several visualizations in one call — what the dashboard sends after
        the user has rearranged or re-configured more than one chart.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Visualisation has been successfully updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAllVSBody'
        required: true
  /api/search/charts/chart_types/:
    get:
      tags:
      - Dashboards
      operationId: List Chart Types
      description: |-
        HTTP METHOD: GET
        Returns the chart types a visualization can be drawn as — line, bar, pie,
        table and the rest — with the aggregation each one expects.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChartTypeBody'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/anomaly/:
    get:
      tags:
      - Dashboards
      operationId: List Anomalies
      description: |-
        HTTP METHOD: GET
        Returns the anomalies detected on the visualizations of a dashboard: the
        point that deviated, the series it belongs to and the chart it was found on.
      parameters:
      - name: dashboard
        in: query
        required: false
        description: Restrict the anomalies to one dashboard.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/anomaly/{id}/:
    get:
      tags:
      - Dashboards
      operationId: Retrieve Anomaly
      description: |-
        HTTP METHOD: GET
        Returns one detected anomaly.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the anomaly.
      schema:
        type: string
  /api/search/anomaly/calc_margin/:
    post:
      tags:
      - Dashboards
      operationId: Calculate Anomaly Margins
      description: |-
        HTTP METHOD: POST
        Computes the expected band of a series from the points given — the margins
        a chart draws around its line and outside of which a point counts as an
        anomaly.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  stats:
                    type: object
                    description: Statistics computed over the series.
                  data:
                    type: array
                    description: The margin band, point by point.
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - x_points
              - y_points
              properties:
                x_points:
                  type: array
                  description: Timestamps of the series.
                  items:
                    type: number
                y_points:
                  type: array
                  description: Values of the series.
                  items:
                    type: number
        required: true
  /api/search/anomaly/trigger_anomaly_task/:
    post:
      tags:
      - Dashboards
      operationId: Trigger Anomaly Detection
      description: |-
        HTTP METHOD: POST
        Runs the anomaly-detection task for the caller's environment straight away,
        instead of waiting for its schedule.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/rules/:
    get:
      tags:
      - Alerts
      operationId: List Rules
      description: |-
        HTTP METHOD: GET
        Returns the alert rules of the environment, newest first. A rule runs a
        query on a schedule and raises an alert when its condition is met.
        Requires the `alerts_view` right.
      parameters:
      - name: q
        in: query
        required: false
        description: Matches the title, description, severity or query of a rule.
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Rule'
                  page:
                    type: integer
                    nullable: true
                  total:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Alerts
      operationId: Create Rule
      description: |-
        HTTP METHOD: POST
        Creates an alert rule and schedules it. The rule runs `query` every
        `trigger_every`, looks back over `lookback_period`, and raises an alert of
        the given `severity` when the number of hits satisfies `condition` against
        `threshold`. Requires the `alerts_add` right.
      responses:
        '201':
          description: Rule created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuleBody'
        required: true
  /api/search/rules/{id}/:
    get:
      tags:
      - Alerts
      operationId: Retrieve Rule
      description: |-
        HTTP METHOD: GET
        Returns one alert rule with its schedule, its condition and the
        notifications attached to it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    $ref: '#/components/schemas/Rule'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Alerts
      operationId: Update Rule
      description: |-
        HTTP METHOD: PUT
        Updates an alert rule and reschedules it. Requires the `alerts_edit` right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuleBody'
        required: true
    delete:
      tags:
      - Alerts
      operationId: Delete Rule
      description: |-
        HTTP METHOD: DELETE
        Deletes an alert rule together with its schedule. Requires the
        `alerts_delete` right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
              example:
                message: The rule has been successfully deleted
                status: success
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the rule.
      schema:
        type: string
  /api/search/rules/{id}/alerts/:
    delete:
      tags:
      - Alerts
      operationId: Delete Rule Alerts
      description: |-
        HTTP METHOD: DELETE
        Deletes every alert a rule has raised, keeping the rule itself.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the rule.
      schema:
        type: string
  /api/search/alerts/:
    get:
      tags:
      - Alerts
      operationId: List Alerts
      description: |-
        HTTP METHOD: GET
        Returns the alerts raised by the rules of the environment, newest first,
        each with the rule that raised it, the sources it covers and how long ago
        it fired.
      parameters:
      - name: q
        in: query
        required: false
        description: Matches the rule title, description, severity or query.
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Alert'
                  page:
                    type: integer
                    nullable: true
                  total:
                    type: integer
                  count:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/alerts/{id}/:
    get:
      tags:
      - Alerts
      operationId: Retrieve Alert
      description: |-
        HTTP METHOD: GET
        Returns one alert with the rows that triggered it and the columns they
        should be displayed with.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: object
                    properties:
                      id:
                        type: string
                      total:
                        type: string
                      fields:
                        type: array
                        items:
                          type: string
                      data:
                        type: array
                        items:
                          type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Alerts
      operationId: Delete Alert
      description: |-
        HTTP METHOD: DELETE
        Deletes one alert. Requires the `alerts_delete` right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the alert.
      schema:
        type: string
  /api/search/alerts/{id}/recent_activity/:
    get:
      tags:
      - Alerts
      operationId: List Rule Activity
      description: |-
        HTTP METHOD: GET
        Returns the recent runs of a rule — when it fired, and what it delivered.
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                  page:
                    type: integer
                    nullable: true
                  total:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the rule.
      schema:
        type: string
  /api/search/alerts/charts/:
    get:
      tags:
      - Alerts
      operationId: Retrieve Alert Charts
      description: |-
        HTTP METHOD: GET
        Returns the charts of the alerts page: the split of alerts by severity, and
        the alert and log volumes over the last week.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  charts:
                    type: object
                    description: Pie charts for alerts and logs.
                  line_charts:
                    type: object
                    description: Time series for alerts and logs.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/alerts/condition_types/:
    get:
      tags:
      - Alerts
      operationId: List Condition Types
      description: |-
        HTTP METHOD: GET
        Returns the conditions a rule can trigger on — above, less than, rised by,
        drop by, not equals.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/alerts/severity_types/:
    get:
      tags:
      - Alerts
      operationId: List Severity Types
      description: |-
        HTTP METHOD: GET
        Returns the severities an alert rule can raise.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/alerts/notification_types/:
    get:
      tags:
      - Alerts
      operationId: List Notification Types
      description: |-
        HTTP METHOD: GET
        Returns the channels an alert can be delivered through.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/alerts/time_units/:
    get:
      tags:
      - Alerts
      operationId: List Rule Time Units
      description: |-
        HTTP METHOD: GET
        Returns the intervals a rule can be scheduled on, such as every 15 minutes
        or every day.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/alerts/trigger_on/:
    get:
      tags:
      - Alerts
      operationId: List Trigger Options
      description: |-
        HTTP METHOD: GET
        Returns what a rule can trigger on — a number of results, or every run.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/search/board/hosts/:
    post:
      tags:
      - Boards
      operationId: List Hosts
      description: |-
        HTTP METHOD: POST
        Returns the hosts seen in the incoming logs, with their sources, their
        tags, their event count and their activity status.

        The endpoint answers in two different ways, depending on the body:

          - without `stats`, it lists the stored hosts, paginated with `from` and
            `size`, ordered by `order_by` / `order`, and filtered by `q` — which
            matches a host name, a source or a tag;
          - with `stats` — a list of host identifiers — it goes to Elasticsearch
            instead and returns the event counts and last activity of exactly
            those hosts over `times`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoardListingResponse'
        '400':
          description: Nothing matched the request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  total:
                    type: integer
              example:
                message: No results found
                total: 0
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BoardListingBody'
  /api/search/board/hosts/add_tags/:
    put:
      tags:
      - Boards
      operationId: Add Tags To Hosts
      description: |-
        HTTP METHOD: PUT
        Attaches tags to hosts. The counters of every tag involved — hosts, sources
        and events — are kept up to date. Requires the `hosts_and_sources_edit`
        right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Host'
                  message:
                    type: string
              example:
                message: Tags added successfully
        '400':
          description: No tag or no host supplied
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - tags
              - host
              properties:
                tags:
                  type: array
                  description: Identifiers of the tags to attach.
                  items:
                    type: string
                host:
                  type: array
                  description: Identifiers of the hosts to tag.
                  items:
                    type: string
        required: true
  /api/search/board/hosts/remove_tags/:
    put:
      tags:
      - Boards
      operationId: Remove Tags From Hosts
      description: |-
        HTTP METHOD: PUT
        Detaches tags from hosts.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Tags removed successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - tags
              - host
              properties:
                tags:
                  type: array
                  items:
                    type: string
                host:
                  type: array
                  items:
                    type: string
        required: true
  /api/search/board/hosts/remove/:
    put:
      tags:
      - Boards
      operationId: Remove Hosts
      description: |-
        HTTP METHOD: PUT
        Removes hosts from the board. Only inactive hosts can be removed: a host
        that is still receiving logs is refused, and named in the answer.
        Requires the `hosts_and_sources_delete` right.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Object deleted successfully
        '400':
          description: Some hosts are still active
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  host:
                    type: array
                    items:
                      type: string
              example:
                message: cannot delete host with status active
                host:
                - web-01
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - host
              properties:
                host:
                  type: array
                  description: Identifiers of the hosts to remove.
                  items:
                    type: string
        required: true
  /api/search/board/sources/:
    post:
      tags:
      - Boards
      operationId: List Board Sources
      description: |-
        HTTP METHOD: POST
        Returns the sources the incoming logs arrive on, with their host count,
        their tags, their event count and their activity status. Takes the same
        body as the hosts listing: without `stats` it lists the stored sources,
        with `stats` it returns Elasticsearch counts for the given ones.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoardListingResponse'
        '400':
          description: Nothing matched the request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  total:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BoardListingBody'
  /api/search/board/sources/add_tags/:
    put:
      tags:
      - Boards
      operationId: Add Tags To Sources
      description: |-
        HTTP METHOD: PUT
        Attaches tags to sources.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/BoardSource'
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - tags
              - index
              properties:
                tags:
                  type: array
                  items:
                    type: string
                index:
                  type: array
                  description: Identifiers of the sources to tag.
                  items:
                    type: string
        required: true
  /api/search/board/sources/remove_tags/:
    put:
      tags:
      - Boards
      operationId: Remove Tags From Sources
      description: |-
        HTTP METHOD: PUT
        Detaches tags from sources.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - tags
              - index
              properties:
                tags:
                  type: array
                  items:
                    type: string
                index:
                  type: array
                  items:
                    type: string
        required: true
  /api/search/board/sources/remove/:
    put:
      tags:
      - Boards
      operationId: Remove Sources
      description: |-
        HTTP METHOD: PUT
        Removes sources from the board. As with hosts, a source that is still
        active cannot be removed.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          description: Some sources are still active
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  index:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - index
              properties:
                index:
                  type: array
                  items:
                    type: string
        required: true
  /api/search/board/tags/:
    get:
      tags:
      - Boards
      operationId: List Tags
      description: |-
        HTTP METHOD: GET
        Returns every tag of the environment with its value and its counters: how
        many hosts and sources carry it, and how many events they account for.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tag'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Boards
      operationId: Create Tag
      description: |-
        HTTP METHOD: POST
        Creates a tag. Requires the `hosts_and_sources_add` right.
      responses:
        '201':
          description: Tag created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                values:
                  type: string
        required: true
  /api/search/board/tags/{id}/:
    get:
      tags:
      - Boards
      operationId: Retrieve Tag
      description: |-
        HTTP METHOD: GET
        Returns one tag with the hosts and sources it is attached to.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Boards
      operationId: Update Tag
      description: |-
        HTTP METHOD: PUT
        Renames a tag or changes its value.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                values:
                  type: string
        required: true
    patch:
      tags:
      - Boards
      operationId: Partially Update Tag
      description: |-
        HTTP METHOD: PATCH
        A partial update of the tag: the body of `PUT` on this path, with every
        field optional. Only the fields present are changed.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                values:
                  type: string
        required: true
    delete:
      tags:
      - Boards
      operationId: Delete Tag
      description: |-
        HTTP METHOD: DELETE
        Deletes a tag and detaches it from every host and source that carried it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              example:
                detail: Object deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of the tag.
      schema:
        type: string
  /api/search/board/tags/tags_data/:
    post:
      tags:
      - Boards
      operationId: Retrieve Tags Data
      description: |-
        HTTP METHOD: POST
        Returns the event volume behind a tag selection, straight from
        Elasticsearch: the number of distinct events and, when a query is given,
        the hosts that produced them. Either `query` or `hosts` has to be supplied.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_events:
                    type: integer
                  host:
                    type: array
                    items:
                      type: object
        '400':
          description: Neither `query` nor `hosts` supplied
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Invalid request, required hosts or query
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                indices:
                  type: array
                  items:
                    type: string
                query:
                  type: object
                  description: Elasticsearch query the volume is computed over.
                hosts:
                  type: array
                  description: Hosts to compute the volume for, when no query is given.
                  items:
                    type: string
        required: true
  /api/components/services/:
    get:
      tags:
      - Services
      operationId: List Services
      description: |-
        HTTP METHOD: GET
        Returns the services of the environment, paginated. A service is a named
        slice of the log stream — everything matching its log and alert filters —
        that carries a class, a criticality, its sources, its entities, its tags
        and its relationships to other services.
      parameters:
      - name: page
        in: query
        required: false
        description: Zero-based page number.
        schema:
          type: integer
      - name: size
        in: query
        required: false
        description: Page size. Defaults to 25.
        schema:
          type: integer
      - name: order_by
        in: query
        required: false
        description: Field to sort on. Defaults to `updated_at`.
        schema:
          type: string
      - name: sort_order
        in: query
        required: false
        description: '`1` ascending, `-1` descending.'
        schema:
          type: integer
      - name: keyword
        in: query
        required: false
        description: Free text match on the service name.
        schema:
          type: string
      - name: query
        in: query
        required: false
        description: JSON encoded object of additional field filters.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDocuments'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Services
      operationId: Create Service
      description: |-
        HTTP METHOD: POST
        Creates a service. The log and alert filters are given as a filter tree
        (AST), which supports nested boolean expressions; the insight filters
        narrow that further for insight generation only.
      responses:
        '200':
          description: Service created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceBody'
        required: true
  /api/components/services/{service_id}:
    get:
      tags:
      - Services
      operationId: Retrieve Service
      description: |-
        HTTP METHOD: GET
        Returns one service, with its resolved tags, entities and service groups.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Services
      operationId: Update Service
      description: |-
        HTTP METHOD: PUT
        Updates a service.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceBody'
        required: true
    delete:
      tags:
      - Services
      operationId: Delete Service
      description: |-
        HTTP METHOD: DELETE
        Deletes a service.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Service deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: service_id
      in: path
      required: true
      description: Identifier of the service.
      schema:
        type: string
  /api/components/services/retrieve:
    get:
      tags:
      - Services
      operationId: Retrieve Service By Name
      description: |-
        HTTP METHOD: GET
        Returns a service by identifier or by name. Meant for the chatbot, which
        resolves a service from what the user typed. One of `service_id` or
        `service_name` is required.
      parameters:
      - name: service_id
        in: query
        required: false
        schema:
          type: string
      - name: service_name
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          description: Neither identifier nor name supplied
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/services/names:
    get:
      tags:
      - Services
      operationId: List Service Names
      description: |-
        HTTP METHOD: GET
        Returns services as identifier / name pairs, for pickers. The list can be
        narrowed to the services that belong to given service groups, entities or
        sources.
      parameters:
      - name: search
        in: query
        required: false
        schema:
          type: string
      - name: service_id
        in: query
        required: false
        schema:
          type: string
      - name: active
        in: query
        required: false
        description: Only active services. Defaults to true.
        schema:
          type: boolean
      - name: service_groups
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: entities
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sources
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: all_services
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    service_name:
                      type: string
                    indices:
                      type: array
                      items:
                        type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/services/filter:
    post:
      tags:
      - Services
      operationId: Filter Services
      description: |-
        HTTP METHOD: POST
        Returns services grouped and sorted as the services board asks for:
        `group_by` decides the horizontal and vertical grouping, `search` the field
        conditions, `time_filter` the activity window.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterPayload'
        required: true
  /api/components/services/preview:
    post:
      tags:
      - Services
      operationId: Preview Service Conditions
      description: |-
        HTTP METHOD: POST
        Returns the service names a set of conditions would produce, before
        anything is created.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
        required: true
  /api/components/services/validate:
    post:
      tags:
      - Services
      operationId: Validate Query
      description: |-
        HTTP METHOD: POST
        Parses a filter query string and reports whether it is valid, returning the
        resulting filter tree or the position of the syntax error.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryValidateResponse'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                  example: (level=error OR level=warn) AND host=server1
        required: true
  /api/components/services/validate-filters:
    post:
      tags:
      - Services
      operationId: Validate Service Filters
      description: |-
        HTTP METHOD: POST
        Validates the four filters of a service — log, alert, insight log and
        insight alert — in one call, and reports which of them are usable.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                log_query_filter:
                  type: object
                alert_query_filter:
                  type: object
                insight_log_query_filter:
                  type: object
                insight_alert_query_filter:
                  type: object
        required: true
  /api/components/services/service_fields:
    get:
      tags:
      - Services
      operationId: List Service Fields
      description: |-
        HTTP METHOD: GET
        Returns the fields of a service that can be filtered or grouped on, plus a
        `tags.<name>` entry for every tag in use. Pass `field` to narrow the list
        to the names containing it.
      parameters:
      - name: field
        in: query
        required: false
        description: Substring the field name has to contain, case-insensitive.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/services/service_values:
    get:
      tags:
      - Services
      operationId: List Service Field Values
      description: |-
        HTTP METHOD: GET
        Returns the distinct values services carry for one field — what fills the
        second half of a filter row once a field has been picked.
      parameters:
      - name: field
        in: query
        required: true
        description: Field to read values of, as returned by `service_fields`.
        schema:
          type: string
      - name: value
        in: query
        required: false
        description: Substring the value has to contain, case-insensitive.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/components/services/enum-values:
    get:
      tags:
      - Services
      operationId: List Service Enum Values
      description: |-
        HTTP METHOD: GET
        Returns the fixed vocabularies a service is described with: criticalities,
        statuses, classes and origins.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  criticalities:
                    type: array
                    items:
                      type: string
                  statuses:
                    type: array
                    items:
                      type: string
                  service_classes:
                    type: array
                    items:
                      type: string
                  service_origins:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/services/group_by_fields:
    get:
      tags:
      - Services
      operationId: List Service Group-By Fields
      description: |-
        HTTP METHOD: GET
        Returns the fields the service listing can be grouped by, including a
        `tags.<name>` entry for every tag in use.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/services/saved-filter:
    get:
      tags:
      - Services
      operationId: List Services Of Saved Filter
      description: |-
        HTTP METHOD: GET
        Runs the service filter the caller saved through
        `/api/components/saved-filters/service` and returns the services it
        matches — how the services page restores its last view.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/services/query/validate:
    post:
      tags:
      - Component Filters
      operationId: Validate Filter Query
      description: |-
        HTTP METHOD: POST
        Validates a single filter query string and returns its parsed tree.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryValidateResponse'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
        required: true
  /api/components/services/query/validate-batch:
    post:
      tags:
      - Component Filters
      operationId: Validate Filter Queries
      description: |-
        HTTP METHOD: POST
        Validates several filter query strings in one round trip.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/QueryValidateResponse'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - queries
              properties:
                queries:
                  type: array
                  items:
                    type: string
        required: true
  /api/components/services/query/preview:
    post:
      tags:
      - Component Filters
      operationId: Preview Filter Query
      description: |-
        HTTP METHOD: POST
        Runs a filter query against the logs and returns a sample of the lines it
        matches, so a filter can be checked before it is saved on a service.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                index:
                  type: string
                size:
                  type: integer
        required: true
  /api/components/services/query/parse:
    post:
      tags:
      - Component Filters
      operationId: Parse Filter Queries
      description: |-
        HTTP METHOD: POST
        Turns filter query strings into the per-source filter trees the platform
        stores, without saving anything.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
        required: true
  /api/components/services/query-syntax-help:
    get:
      tags:
      - Component Filters
      operationId: Retrieve Query Syntax Help
      description: |-
        HTTP METHOD: GET
        Returns the reference of the filter query syntax — operators, examples and
        the rules the parser applies — as the filter editor displays it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/service_groups/:
    get:
      tags:
      - Services
      operationId: List Service Groups
      description: |-
        HTTP METHOD: GET
        Returns the service groups, paginated. A service group gathers services
        that belong together — a business application, a platform, a location —
        and carries its own criticality and status.
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: size
        in: query
        required: false
        schema:
          type: integer
      - name: order_by
        in: query
        required: false
        schema:
          type: string
      - name: sort_order
        in: query
        required: false
        schema:
          type: integer
      - name: keyword
        in: query
        required: false
        schema:
          type: string
      - name: query
        in: query
        required: false
        description: JSON encoded object of additional field filters.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDocuments'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Services
      operationId: Create Service Group
      description: |-
        HTTP METHOD: POST
        Creates a service group.
      responses:
        '200':
          description: Service group created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceGroup'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceGroupBody'
        required: true
  /api/components/service_groups/{service_group_id}:
    get:
      tags:
      - Services
      operationId: Retrieve Service Group
      description: |-
        HTTP METHOD: GET
        Returns one service group with its assigned services.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceGroup'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Services
      operationId: Update Service Group
      description: |-
        HTTP METHOD: PUT
        Updates a service group.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceGroup'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceGroupBody'
        required: true
    delete:
      tags:
      - Services
      operationId: Delete Service Group
      description: |-
        HTTP METHOD: DELETE
        Deletes a service group. The services in it are not deleted.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: service_group_id
      in: path
      required: true
      description: Identifier of the service group.
      schema:
        type: string
  /api/components/service_groups/names:
    get:
      tags:
      - Services
      operationId: List Service Group Names
      description: |-
        HTTP METHOD: GET
        Returns service groups as identifier / name pairs, for pickers.
      parameters:
      - name: search
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/service_groups/service_mapping:
    get:
      tags:
      - Services
      operationId: Retrieve Group Service Mapping
      description: |-
        HTTP METHOD: GET
        Returns, for every service group, the names of the services assigned to it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/service_groups/filter:
    post:
      tags:
      - Services
      operationId: Filter Service Groups
      description: |-
        HTTP METHOD: POST
        Returns service groups grouped and sorted as the board asks for.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterPayload'
        required: true
  /api/components/service_groups/service_group_fields:
    get:
      tags:
      - Services
      operationId: List Service Group Fields
      description: |-
        HTTP METHOD: GET
        Returns the fields of a service group that can be filtered or grouped on,
        plus a `tags.<name>` entry for every tag in use. Pass `field` to narrow the
        list to the names containing it.
      parameters:
      - name: field
        in: query
        required: false
        description: Substring the field name has to contain, case-insensitive.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/service_groups/service_group_values:
    get:
      tags:
      - Services
      operationId: List Service Group Field Values
      description: |-
        HTTP METHOD: GET
        Returns the distinct values service groups carry for one field — what fills
        the second half of a filter row once a field has been picked.
      parameters:
      - name: field
        in: query
        required: true
        description: Field to read values of, as returned by `service_group_fields`.
        schema:
          type: string
      - name: value
        in: query
        required: false
        description: Substring the value has to contain, case-insensitive.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/components/service_groups/enum-values:
    get:
      tags:
      - Services
      operationId: List Service Group Enum Values
      description: |-
        HTTP METHOD: GET
        Returns the fixed vocabularies a service group is described with:
        criticalities, statuses, classes and origins. Same vocabulary as
        `/api/components/services/enum-values`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  criticalities:
                    type: array
                    items:
                      type: string
                  statuses:
                    type: array
                    items:
                      type: string
                  service_classes:
                    type: array
                    items:
                      type: string
                  service_origins:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/service_groups/group_by_fields:
    get:
      tags:
      - Services
      operationId: List Service Group Group-By Fields
      description: |-
        HTTP METHOD: GET
        Returns the fields the service-group listing can be grouped by, including a
        `tags.<name>` entry for every tag in use.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/service_groups/saved-filter:
    get:
      tags:
      - Services
      operationId: List Service Groups Of Saved Filter
      description: |-
        HTTP METHOD: GET
        Runs the service-group filter the caller saved through
        `/api/components/saved-filters/service_group` and returns the service
        groups it matches — how the page restores its last view.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/entities/:
    get:
      tags:
      - Entities
      operationId: List Entities
      description: |-
        HTTP METHOD: GET
        Returns the entities — hosts, devices, nodes, endpoints, users — discovered
        in the logs, paginated. Every entity carries the source it was seen on, the
        field it was read from, its services, its tags, its event total and its
        activity status. With `fresh_activity` the activity is read from
        Elasticsearch instead of the stored value.
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: size
        in: query
        required: false
        description: Page size. Defaults to 100.
        schema:
          type: integer
      - name: order_by
        in: query
        required: false
        description: Defaults to `last_activity`.
        schema:
          type: string
      - name: sort_order
        in: query
        required: false
        schema:
          type: integer
      - name: entity_class
        in: query
        required: false
        description: 'One of: host, device, node, endpoint, user.'
        schema:
          type: string
      - name: last_activity
        in: query
        required: false
        description: Only entities active since this datetime.
        schema:
          type: string
      - name: keyword
        in: query
        required: false
        schema:
          type: string
      - name: services
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sources
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: query
        in: query
        required: false
        description: JSON encoded object of additional field filters.
        schema:
          type: string
      - name: fresh_activity
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDocuments'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      tags:
      - Entities
      operationId: Delete Entities
      description: |-
        HTTP METHOD: DELETE
        Deletes several entities in one call. The body is the list of identifiers.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: 3 entities deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        required: true
  /api/components/entities/{entity_id}:
    get:
      tags:
      - Entities
      operationId: Retrieve Entity
      description: |-
        HTTP METHOD: GET
        Returns one entity.
      parameters:
      - name: fresh_activity
        in: query
        required: false
        description: Read the activity status from Elasticsearch.
        schema:
          type: boolean
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      tags:
      - Entities
      operationId: Delete Entity
      description: |-
        HTTP METHOD: DELETE
        Deletes one entity.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: entity_id
      in: path
      required: true
      description: Identifier of the entity.
      schema:
        type: string
  /api/components/entities/retrieve:
    get:
      tags:
      - Entities
      operationId: Retrieve Entity By Name
      description: |-
        HTTP METHOD: GET
        Returns an entity by identifier or by name. Meant for the chatbot. One of
        `entity_id` or `entity_name` is required.
      parameters:
      - name: entity_id
        in: query
        required: false
        schema:
          type: string
      - name: entity_name
        in: query
        required: false
        schema:
          type: string
      - name: fresh_activity
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '400':
          description: Neither identifier nor name supplied
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/entities/names:
    get:
      tags:
      - Entities
      operationId: List Entity Names
      description: |-
        HTTP METHOD: GET
        Returns entities as identifier / name pairs, optionally narrowed to given
        services, service groups or sources.
      parameters:
      - name: search
        in: query
        required: false
        schema:
          type: string
      - name: entity_id
        in: query
        required: false
        schema:
          type: string
      - name: services
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: service_groups
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sources
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/entities/entity-activity:
    get:
      tags:
      - Entities
      operationId: Retrieve Entity Activity
      description: |-
        HTTP METHOD: GET
        Returns the recorded activity of the given entities — event counts over
        time — for the sparklines of the entities board.
      parameters:
      - name: entity_ids
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    entity_id:
                      type: string
                    activities:
                      type: array
                      items:
                        type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/entities/get-elastic-datetimes:
    get:
      tags:
      - Entities
      operationId: Retrieve Entity Activity Times
      description: |-
        HTTP METHOD: GET
        Returns, straight from Elasticsearch, the last activity and the activity
        status of the given entities.
      parameters:
      - name: entity_ids
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    last_tracked_activity:
                      type: string
                    activity_status:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/entities/filter:
    post:
      tags:
      - Entities
      operationId: Filter Entities
      description: |-
        HTTP METHOD: POST
        Returns entities grouped and sorted as the entities board asks for.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterPayload'
        required: true
  /api/components/entities/entity_fields:
    get:
      tags:
      - Entities
      operationId: List Entity Fields
      description: |-
        HTTP METHOD: GET
        Returns the fields of an entity that can be filtered or grouped on, plus a
        `tags.<name>` entry for every tag in use. Pass `field` to narrow the list
        to the names containing it.
      parameters:
      - name: field
        in: query
        required: false
        description: Substring the field name has to contain, case-insensitive.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/entities/entity_values:
    get:
      tags:
      - Entities
      operationId: List Entity Field Values
      description: |-
        HTTP METHOD: GET
        Returns the distinct values entities carry for one field — what fills the
        second half of a filter row once a field has been picked.
      parameters:
      - name: field
        in: query
        required: true
        description: Field to read values of, as returned by `entity_fields`.
        schema:
          type: string
      - name: value
        in: query
        required: false
        description: Substring the value has to contain, case-insensitive.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/components/entities/group_by_fields:
    get:
      tags:
      - Entities
      operationId: List Entity Group-By Fields
      description: |-
        HTTP METHOD: GET
        Returns the fields the entity listing can be grouped by, including a
        `tags.<name>` entry for every tag in use.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/entities/enums:
    get:
      tags:
      - Entities
      operationId: List Entity Enums
      description: |-
        HTTP METHOD: GET
        Returns the fixed vocabularies an entity is described with: the entity
        classes, and the activity states an entity can be reported in. Each is a
        name-to-value mapping.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity_classes:
                    type: object
                    additionalProperties:
                      type: string
                  entity_activity:
                    type: object
                    additionalProperties:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/sources/:
    get:
      tags:
      - Sources
      operationId: List Component Sources
      description: |-
        HTTP METHOD: GET
        Returns the sources of the environment, paginated: the index they write to,
        their type and collector, their timezone, the entity field they are keyed
        on, their event total, their activity and the pipeline that parses them.
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: size
        in: query
        required: false
        schema:
          type: integer
      - name: order_by
        in: query
        required: false
        description: Defaults to `last_activity`.
        schema:
          type: string
      - name: sort_order
        in: query
        required: false
        schema:
          type: integer
      - name: entity_class
        in: query
        required: false
        schema:
          type: string
      - name: source_type
        in: query
        required: false
        schema:
          type: string
      - name: last_activity
        in: query
        required: false
        schema:
          type: string
      - name: keyword
        in: query
        required: false
        schema:
          type: string
      - name: query
        in: query
        required: false
        description: JSON encoded object of additional field filters.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDocuments'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Sources
      operationId: Create Component Source
      description: |-
        HTTP METHOD: POST
        Registers a source: the name it is known by, its type and collector, and
        the Kafka topic its raw logs arrive on.
      responses:
        '200':
          description: Source created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentSource'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceBody'
        required: true
  /api/components/sources/{source_id}:
    get:
      tags:
      - Sources
      operationId: Retrieve Component Source
      description: |-
        HTTP METHOD: GET
        Returns one source.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentSource'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Sources
      operationId: Update Component Source
      description: |-
        HTTP METHOD: PUT, PATCH
        Updates a source — its entity class and field, its type, its timezone or
        the pipeline attached to it. `PATCH` is accepted on the same path and
        behaves identically.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentSource'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                entity_class:
                  type: string
                source_type:
                  type: string
                collector_type:
                  type: string
                entity_field:
                  type: string
                timezone:
                  type: string
                pipeline_id:
                  type: string
                  nullable: true
        required: true
    patch:
      tags:
      - Sources
      operationId: Partially Update Component Source
      description: |-
        HTTP METHOD: PATCH
        A partial update of the source: the body of `PUT` on this path, with every
        field optional. Only the fields present are changed.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentSource'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                entity_class:
                  type: string
                source_type:
                  type: string
                collector_type:
                  type: string
                entity_field:
                  type: string
                timezone:
                  type: string
                pipeline_id:
                  type: string
                  nullable: true
        required: true
    delete:
      tags:
      - Sources
      operationId: Delete Component Source
      description: |-
        HTTP METHOD: DELETE
        Deletes a source.
      responses:
        '204':
          description: Source deleted
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: source_id
      in: path
      required: true
      description: Identifier of the source.
      schema:
        type: string
  /api/components/sources/retrieve:
    get:
      tags:
      - Sources
      operationId: Retrieve Source By Name
      description: |-
        HTTP METHOD: GET
        Returns a source by identifier or by name. Meant for the chatbot. One of
        `source_id` or `source_name` is required.
      parameters:
      - name: source_id
        in: query
        required: false
        schema:
          type: string
      - name: source_name
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentSource'
        '400':
          description: Neither identifier nor name supplied
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/sources/names:
    get:
      tags:
      - Sources
      operationId: List Source Names
      description: |-
        HTTP METHOD: GET
        Returns sources as identifier / name pairs, optionally narrowed to given
        services, service groups or entities.
      parameters:
      - name: search
        in: query
        required: false
        schema:
          type: string
      - name: source_id
        in: query
        required: false
        schema:
          type: string
      - name: services
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: service_groups
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: entities
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/sources/entity-keys:
    get:
      tags:
      - Sources
      operationId: List Source Entity Keys
      description: |-
        HTTP METHOD: GET
        Returns the fields present on a source's documents that can serve as its
        entity key — the field a host or device name is read from.
      parameters:
      - name: source_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/sources/source-activity:
    get:
      tags:
      - Sources
      operationId: Retrieve Source Activity
      description: |-
        HTTP METHOD: GET
        Returns the recorded activity of the given sources — event counts over time.
      parameters:
      - name: source_ids
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/sources/get-elastic-datetimes:
    get:
      tags:
      - Sources
      operationId: Retrieve Source Activity Times
      description: |-
        HTTP METHOD: GET
        Returns, straight from Elasticsearch, the last activity and the activity
        status of the given sources.
      parameters:
      - name: source_ids
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/sources/enums:
    get:
      tags:
      - Sources
      operationId: List Source Enums
      description: |-
        HTTP METHOD: GET
        Returns the values the source form can choose from — source types,
        collector types, entity classes and activity statuses — together with the
        environment's index prefix.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  source_type:
                    type: object
                  collector_type:
                    type: object
                  entity_classes:
                    type: object
                  source_activity:
                    type: object
                  env_name:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/tags/:
    get:
      tags:
      - Component Filters
      operationId: List Component Tags
      description: |-
        HTTP METHOD: GET
        Returns the tags of the environment with their counters — how many
        entities, services and service groups carry each, and the events they
        account for.
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: size
        in: query
        required: false
        schema:
          type: integer
      - name: keyword
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Component Filters
      operationId: Create Component Tag
      description: |-
        HTTP METHOD: POST
        Creates a tag and attaches it to the entities, services and service groups
        listed in the body.
      responses:
        '200':
          description: Tag created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentTag'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - value
              properties:
                name:
                  type: string
                value:
                  type: string
                entities:
                  type: array
                  items:
                    type: string
                services:
                  type: array
                  items:
                    type: string
                service_groups:
                  type: array
                  items:
                    type: string
        required: true
  /api/components/tags/{tag_id}:
    get:
      tags:
      - Component Filters
      operationId: Retrieve Component Tag
      description: |-
        HTTP METHOD: GET
        Returns one tag with the entities, services and service groups it is
        attached to.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentTag'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    patch:
      tags:
      - Component Filters
      operationId: Update Component Tag
      description: |-
        HTTP METHOD: PATCH
        Renames a tag or changes its value.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentTag'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                value:
                  type: string
        required: true
    delete:
      tags:
      - Component Filters
      operationId: Delete Component Tag
      description: |-
        HTTP METHOD: DELETE
        Deletes a tag and detaches it from everything that carried it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: tag_id
      in: path
      required: true
      description: Identifier of the tag.
      schema:
        type: string
  /api/components/tags/names:
    get:
      tags:
      - Component Filters
      operationId: List Component Tag Names
      description: |-
        HTTP METHOD: GET
        Returns the distinct tag names of the environment.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/tags/rename:
    put:
      tags:
      - Component Filters
      operationId: Rename Component Tag
      description: |-
        HTTP METHOD: PUT
        Renames every tag carrying `old_name` to `new_name`.
      parameters:
      - name: old_name
        in: query
        required: true
        schema:
          type: string
      - name: new_name
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/tags/add-tag/{tag_id}:
    post:
      tags:
      - Component Filters
      operationId: Attach Component Tag
      description: |-
        HTTP METHOD: POST
        Attaches an existing tag to services, entities or service groups.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                object_type:
                  type: string
                  enum:
                  - services
                  - entities
                  - service_groups
                object_ids:
                  type: array
                  items:
                    type: string
        required: true
    parameters:
    - name: tag_id
      in: path
      required: true
      description: Identifier of the tag.
      schema:
        type: string
  /api/components/dynamic_filter/:
    get:
      tags:
      - Component Filters
      operationId: List Dynamic Filters
      description: |-
        HTTP METHOD: GET
        Returns the dynamic service filters, paginated. A dynamic filter creates
        and maintains a family of services automatically: it watches one field of
        one source and turns every value it finds into a service of its own.
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: size
        in: query
        required: false
        schema:
          type: integer
      - name: order_by
        in: query
        required: false
        schema:
          type: string
      - name: sort_order
        in: query
        required: false
        schema:
          type: integer
      - name: keyword
        in: query
        required: false
        schema:
          type: string
      - name: query
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDocuments'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Component Filters
      operationId: Create Dynamic Filter
      description: |-
        HTTP METHOD: POST
        Creates a dynamic service filter. `index` and `field_name` say where the
        values are read from; `prefix`, `suffix`, `match_pattern` and
        `service_name_mappings` shape the names of the services it generates.
      responses:
        '200':
          description: Dynamic filter created
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DynamicFilterBody'
        required: true
  /api/components/dynamic_filter/{dynamic_service_filter_id}:
    get:
      tags:
      - Component Filters
      operationId: Retrieve Dynamic Filter
      description: |-
        HTTP METHOD: GET
        Returns one dynamic service filter.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Component Filters
      operationId: Update Dynamic Filter
      description: |-
        HTTP METHOD: PUT
        Updates a dynamic service filter; the services it generated are
        re-evaluated.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DynamicFilterBody'
        required: true
    delete:
      tags:
      - Component Filters
      operationId: Delete Dynamic Filter
      description: |-
        HTTP METHOD: DELETE
        Deletes a dynamic service filter. With `delete_services=true` the services
        it generated are deleted with it; otherwise they are kept and become
        ordinary services.
      parameters:
      - name: delete_services
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: dynamic_service_filter_id
      in: path
      required: true
      description: Identifier of the dynamic service filter.
      schema:
        type: string
  /api/components/dynamic_filter/{dynamic_service_filter_id}/services-relations:
    get:
      tags:
      - Component Filters
      operationId: List Dynamic Filter Services
      description: |-
        HTTP METHOD: GET
        Returns the services a dynamic filter has generated.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: dynamic_service_filter_id
      in: path
      required: true
      schema:
        type: string
  /api/components/dynamic_filter/{dynamic_service_filter_id}/relations:
    post:
      tags:
      - Component Filters
      operationId: Add Dynamic Filter Relation
      description: |-
        HTTP METHOD: POST
        Records an upstream/downstream relationship between two of the services a
        dynamic filter maintains.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - from_id
              - to_id
              properties:
                from_id:
                  type: string
                to_id:
                  type: string
        required: true
    delete:
      tags:
      - Component Filters
      operationId: Remove Dynamic Filter Relation
      description: |-
        HTTP METHOD: DELETE
        Removes a relationship between two services of a dynamic filter.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - from_id
              - to_id
              properties:
                from_id:
                  type: string
                to_id:
                  type: string
        required: true
    parameters:
    - name: dynamic_service_filter_id
      in: path
      required: true
      schema:
        type: string
  /api/components/dynamic_filter/preview:
    post:
      tags:
      - Component Filters
      operationId: Preview Dynamic Filter
      description: |-
        HTTP METHOD: POST
        Returns the services a dynamic filter would generate, before it is saved.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DynamicFilterBody'
        required: true
  /api/components/dynamic_filter/validate-filters:
    post:
      tags:
      - Component Filters
      operationId: Validate Dynamic Filters
      description: |-
        HTTP METHOD: POST
        Validates the query filter and the insight query filter of a dynamic
        filter.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query_filter:
                  type: object
                insight_query_filter:
                  type: object
        required: true
  /api/components/saved-filters/{filter_type}:
    get:
      tags:
      - Component Filters
      operationId: Retrieve Saved Board Filter
      description: |-
        HTTP METHOD: GET
        Returns the filter the caller last saved for a board. `filter_type` is one
        of `service`, `service_group` or `entity`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterPayload'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Component Filters
      operationId: Save Board Filter
      description: |-
        HTTP METHOD: POST
        Saves the filter of a board for the caller, so it is restored the next time
        they open it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterPayload'
        required: true
    delete:
      tags:
      - Component Filters
      operationId: Delete Saved Board Filter
      description: |-
        HTTP METHOD: DELETE
        Removes the saved filter of a board.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Saved filter deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: filter_type
      in: path
      required: true
      description: 'One of: service, service_group, entity.'
      schema:
        type: string
  /api/components/saved-filters/enums:
    get:
      tags:
      - Component Filters
      operationId: List Saved Filter Types
      description: |-
        HTTP METHOD: GET
        Returns the object types a filter can be saved for — the values
        `{filter_type}` accepts — as a name-to-value mapping.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  filter_type:
                    type: object
                    additionalProperties:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/autocomplete/indices:
    get:
      tags:
      - Component Filters
      operationId: Autocomplete Indices
      description: |-
        HTTP METHOD: GET
        Returns the indices of the environment, for the filter editor's
        auto-completion.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/autocomplete/elastic_fields:
    get:
      tags:
      - Component Filters
      operationId: Autocomplete Elastic Fields
      description: |-
        HTTP METHOD: GET
        Returns the fields of an index, optionally narrowed to those matching
        `field_name`.
      parameters:
      - name: index
        in: query
        required: true
        schema:
          type: string
      - name: field_name
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/autocomplete/elastic_values:
    get:
      tags:
      - Component Filters
      operationId: Autocomplete Elastic Values
      description: |-
        HTTP METHOD: GET
        Returns the values a field takes on an index, for auto-completion.
      parameters:
      - name: index
        in: query
        required: true
        schema:
          type: string
      - name: field
        in: query
        required: true
        schema:
          type: string
      - name: value
        in: query
        required: false
        description: Prefix the values must match.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/autocomplete/search_fields:
    get:
      tags:
      - Component Filters
      operationId: Autocomplete Search Fields
      description: |-
        HTTP METHOD: GET
        Returns the stored fields of services, entities and dynamic filters that a
        board search can be written against.
      parameters:
      - name: field
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/autocomplete/search_values:
    get:
      tags:
      - Component Filters
      operationId: Autocomplete Search Values
      description: |-
        HTTP METHOD: GET
        Returns the values a stored field takes, for auto-completion in a board
        search.
      parameters:
      - name: field
        in: query
        required: true
        schema:
          type: string
      - name: value
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/pipelines/:
    get:
      tags:
      - Pipelines
      operationId: List Pipelines
      description: |-
        HTTP METHOD: GET
        Returns the parsing pipelines, paginated. A pipeline is the ordered list of
        steps a raw log line goes through before it is indexed — parsing,
        extraction, renaming, dropping — together with the sources it is attached
        to and the strategy it follows when a step fails.
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: size
        in: query
        required: false
        schema:
          type: integer
      - name: order_by
        in: query
        required: false
        schema:
          type: string
      - name: sort_order
        in: query
        required: false
        schema:
          type: integer
      - name: keyword
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDocuments'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Pipelines
      operationId: Create Pipeline
      description: |-
        HTTP METHOD: POST
        Creates a pipeline and binds it to its sources.
      responses:
        '200':
          description: Pipeline created
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelineBody'
        required: true
  /api/components/pipelines/{pipeline_id}:
    get:
      tags:
      - Pipelines
      operationId: Retrieve Pipeline
      description: |-
        HTTP METHOD: GET
        Returns one pipeline with its steps.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Pipelines
      operationId: Replace Pipeline
      description: |-
        HTTP METHOD: PUT
        Replaces a pipeline as a whole.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelineBody'
        required: true
    patch:
      tags:
      - Pipelines
      operationId: Update Pipeline
      description: |-
        HTTP METHOD: PATCH
        Updates part of a pipeline — its name, description, steps, error strategy,
        sources, or whether it is the default one.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                steps:
                  type: array
                  items:
                    type: object
                on_error:
                  type: string
                  enum:
                  - raise
                  - skip
                  - drop
                is_default:
                  type: boolean
                sources:
                  type: array
                  items:
                    type: string
        required: true
    delete:
      tags:
      - Pipelines
      operationId: Delete Pipeline
      description: |-
        HTTP METHOD: DELETE
        Deletes a pipeline.
      responses:
        '204':
          description: Pipeline deleted
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: pipeline_id
      in: path
      required: true
      description: Identifier of the pipeline.
      schema:
        type: string
  /api/components/pipelines/names:
    get:
      tags:
      - Pipelines
      operationId: List Pipeline Names
      description: |-
        HTTP METHOD: GET
        Returns pipelines as identifier / name pairs, for pickers.
      parameters:
      - name: search
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/pipelines/functions:
    get:
      tags:
      - Pipelines
      operationId: List Pipeline Functions
      description: |-
        HTTP METHOD: GET
        Returns every function a pipeline step can call, with its description, its
        parameters and an example — the reference the pipeline editor is built on.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    description:
                      type: string
                    params:
                      type: array
                      items:
                        type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/pipelines/functions/names:
    get:
      tags:
      - Pipelines
      operationId: List Pipeline Function Names
      description: |-
        HTTP METHOD: GET
        Returns just the names of the available pipeline functions.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/pipelines/enums:
    get:
      tags:
      - Pipelines
      operationId: List Pipeline Enums
      description: |-
        HTTP METHOD: GET
        Returns the error strategies a pipeline can be configured with: `raise`,
        `skip`, `drop`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  on_error:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/pipelines/validate:
    post:
      tags:
      - Pipelines
      operationId: Validate Pipeline
      description: |-
        HTTP METHOD: POST
        Checks a list of pipeline steps and reports, per step, what is wrong with
        it.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        step_index:
                          type: integer
                        function_name:
                          type: string
                        message:
                          type: string
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
        required: true
  /api/components/pipelines/preview:
    post:
      tags:
      - Pipelines
      operationId: Preview Pipeline
      description: |-
        HTTP METHOD: POST
        Runs pipeline steps against sample log lines and returns what each line
        turns into, without saving anything. Up to 100 samples per call.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelinePreviewResponse'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - steps
              - sample_logs
              properties:
                steps:
                  type: array
                  items:
                    type: object
                on_error:
                  type: string
                  enum:
                  - raise
                  - skip
                  - drop
                sample_logs:
                  type: array
                  items:
                    type: string
        required: true
  /api/components/pipelines/preview-with-source:
    post:
      tags:
      - Pipelines
      operationId: Preview Pipeline With Source
      description: |-
        HTTP METHOD: POST
        Runs pipeline steps against real log lines pulled from the Kafka topics of
        the given sources, so a pipeline can be tested on production data before it
        is saved.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelinePreviewResponse'
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - steps
              - sources
              properties:
                steps:
                  type: array
                  items:
                    type: object
                on_error:
                  type: string
                sources:
                  type: array
                  items:
                    type: string
                limit:
                  type: integer
                sort_order:
                  type: string
                  enum:
                  - asc
                  - desc
                keyword:
                  type: string
        required: true
  /api/components/pipelines/preview-file:
    post:
      tags:
      - Pipelines
      operationId: Preview Pipeline From File
      description: |-
        HTTP METHOD: POST
        Runs pipeline steps against the log objects of an uploaded JSON file. Sent
        as `multipart/form-data` with the file in `file` and the pipeline
        configuration as a JSON string in `request`. The file is limited to 1 MB,
        100 entries and a bounded nesting depth.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelinePreviewResponse'
        '400':
          description: File too large, malformed, or too deeply nested
        '422':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: JSON file holding an array of log objects.
                request:
                  type: string
                  description: 'JSON string, e.g. `{"steps": [...], "on_error": "skip"}`.'
              required:
              - file
              - request
  /api/components/kafka/topics:
    get:
      tags:
      - Sources
      operationId: List Kafka Topics
      description: |-
        HTTP METHOD: GET
        Returns the Kafka topics raw logs arrive on.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '500':
          description: Kafka could not be reached
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/kafka/topics/{topic_name}/raw-logs:
    get:
      tags:
      - Sources
      operationId: List Raw Logs By Topic
      description: |-
        HTTP METHOD: GET
        Returns raw, unparsed messages from a Kafka topic — the lines exactly as
        they were received.
      parameters:
      - name: limit
        in: query
        required: false
        description: Number of messages, 1 to 1000. Defaults to 100.
        schema:
          type: integer
      - name: sort_order
        in: query
        required: false
        description: '`desc` newest first (default), `asc` oldest first.'
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Kafka could not be reached
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: topic_name
      in: path
      required: true
      schema:
        type: string
  /api/components/kafka/sources/{source_name}/raw-logs:
    get:
      tags:
      - Sources
      operationId: List Raw Logs By Source
      description: |-
        HTTP METHOD: GET
        Returns raw messages from the Kafka topic a source is mapped to.
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: sort_order
        in: query
        required: false
        schema:
          type: string
      - name: keyword
        in: query
        required: false
        description: Case-insensitive filter on the message text.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Kafka could not be reached
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: source_name
      in: path
      required: true
      schema:
        type: string
  /api/components/kafka/sources/raw-logs:
    get:
      tags:
      - Sources
      operationId: List Raw Logs By Sources
      description: |-
        HTTP METHOD: GET
        Returns raw messages for several sources at once. Repeat `source_name` for
        each one.
      parameters:
      - name: source_name
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
      - name: limit
        in: query
        required: false
        description: Messages per source.
        schema:
          type: integer
      - name: sort_order
        in: query
        required: false
        schema:
          type: string
      - name: keyword
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: No source name supplied
        '500':
          description: Kafka could not be reached
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/log-monitoring/:
    get:
      tags:
      - Sources
      operationId: List Log Monitoring
      description: |-
        HTTP METHOD: GET
        Returns what the parsing pipeline failed on, per source: the events it
        could not process and the errors it raised. This is where a broken pipeline
        or an unexpected log format shows up.
      parameters:
      - name: index
        in: query
        required: false
        description: Restrict to one index.
        schema:
          type: string
      - name: keyword
        in: query
        required: false
        description: Case-insensitive match on raw messages and error messages.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/components/log-monitoring/parsed-documents:
    get:
      tags:
      - Sources
      operationId: List Parsed Documents
      description: |-
        HTTP METHOD: GET
        Returns the most recent documents an index actually holds after parsing, so
        the result of a pipeline can be inspected. `keyword` matches both field
        names and field values. Internal pattern fields are stripped from the
        answer.
      parameters:
      - name: index
        in: query
        required: true
        schema:
          type: string
      - name: keyword
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/chatbot/free-prompt:
    post:
      tags:
      - Chatbot
      operationId: Ask The Chatbot
      description: |-
        HTTP METHOD: POST
        Asks the assistant a question in plain language and returns its answer.

        The agent decides for itself which of its tools to reach for — the
        components service for sources, entities and services, the insights service
        for insight groups, or a generated Elasticsearch query against the logs of
        the caller's environment. A summary of the environment's index mapping is
        put in front of the model, so queries it writes use fields that exist.

        The exchange is appended to the caller's conversation, which is what gives
        follow-up questions their context.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatbotInput'
        required: true
  /api/chatbot/retrieve-conversation:
    get:
      tags:
      - Chatbot
      operationId: Retrieve Conversation
      description: |-
        HTTP METHOD: GET
        Returns the caller's conversation so far, oldest message first, as an
        alternating list of `human` and `ai` turns.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChatHistory'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/chatbot/clear-conversation:
    delete:
      tags:
      - Chatbot
      operationId: Clear Conversation
      description: |-
        HTTP METHOD: DELETE
        Forgets the caller's conversation. The next question starts a fresh one,
        with no memory of what came before.
      responses:
        '204':
          description: Conversation cleared
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/chatbot/retrieve-prompts:
    get:
      tags:
      - Chatbot
      operationId: List Predefined Prompts
      description: |-
        HTTP METHOD: GET
        Returns the predefined prompts the interface offers as one-click questions,
        keyed by the endpoint that sends them. These are the exact texts the
        `…-prompt` endpoints put to the agent.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
              example:
                entity-prompt: Show a simple overview of this entity
                source-prompt: Explain what this data source is and its current status
                service-prompt: Describe what this service does and how it’s used
                insight-group-prompt: Give me a brief summary and key insights for this insights group
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/chatbot/entity-prompt/{entity_id}:
    post:
      tags:
      - Chatbot
      operationId: Ask About An Entity
      description: |-
        HTTP METHOD: POST
        Asks the assistant for an overview of one entity. The question is the
        predefined `entity-prompt` with the identifier appended, so the caller does
        not have to phrase anything — this is what the "ask the assistant" button on
        an entity sends.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: entity_id
      in: path
      required: true
      description: Identifier of the entity, as served by the components service.
      schema:
        type: string
  /api/chatbot/source-prompt/{source_id}:
    post:
      tags:
      - Chatbot
      operationId: Ask About A Source
      description: |-
        HTTP METHOD: POST
        Asks the assistant what a source is and how it is doing right now.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: source_id
      in: path
      required: true
      description: Identifier of the source, as served by the components service.
      schema:
        type: string
  /api/chatbot/service-prompt/{service_id}:
    post:
      tags:
      - Chatbot
      operationId: Ask About A Service
      description: |-
        HTTP METHOD: POST
        Asks the assistant what a service does and how it is used.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: service_id
      in: path
      required: true
      description: Identifier of the service, as served by the components service.
      schema:
        type: string
  /api/chatbot/components-source-prompt:
    post:
      tags:
      - Chatbot
      operationId: Ask About Sources
      description: |-
        HTTP METHOD: POST
        Asks the assistant about the sources as a whole, rather than about one of
        them. Takes no body and no identifier — the question is a predefined
        prompt.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/chatbot/components-entity-prompt:
    post:
      tags:
      - Chatbot
      operationId: Ask About Entities
      description: |-
        HTTP METHOD: POST
        Asks the assistant about the entities as a whole, rather than about one of
        them. Takes no body and no identifier — the question is a predefined
        prompt.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/chatbot/components-service-prompt:
    post:
      tags:
      - Chatbot
      operationId: Ask About Services
      description: |-
        HTTP METHOD: POST
        Asks the assistant about the services as a whole, rather than about one of
        them. Takes no body and no identifier — the question is a predefined
        prompt.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/chatbot/components-service-group-prompt:
    post:
      tags:
      - Chatbot
      operationId: Ask About Service Groups
      description: |-
        HTTP METHOD: POST
        Asks the assistant about the service groups as a whole, rather than about
        one of them. Takes no body and no identifier — the question is a predefined
        prompt.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/chatbot/insight-group-prompt/{insights_group_id}:
    post:
      tags:
      - Chatbot
      operationId: Ask About An Insight Group
      description: |-
        HTTP METHOD: POST
        Asks the assistant to summarise one insight group and pull out what matters
        in it. The agent reads the group through the chatbot slice of the insights
        service, `/api/insights/chatbot/groups/{id}/`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    parameters:
    - name: insights_group_id
      in: path
      required: true
      description: Identifier of the insight group.
      schema:
        type: string
  /api/chatbot/elasticsearch-prompt:
    post:
      tags:
      - Chatbot
      operationId: Ask The Elasticsearch Tool
      description: |-
        HTTP METHOD: POST
        Puts a question straight to the Elasticsearch tool: the agent writes a DSL
        query from the fields the environment actually has, runs it, and answers
        from the result.

        **Only registered when the service runs with `DEBUG` enabled**, so it is
        absent from a production deployment.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatbotInput'
        required: true
  /api/activities/:
    post:
      tags:
      - Notifications
      operationId: List Activities
      description: |-
        HTTP METHOD: POST
        Returns the activity feed of the caller — one page of the actions other
        people took on the insights, roles and dashboards the caller can see.
        The caller's own actions are left out.

        Administrators see every activity; everyone else sees the ones addressed
        to them (assigned directly, assigned through a role, or sent to them) plus
        the global ones. The feed is further narrowed to activities on indices the
        caller may read, and to activities recorded after they joined.

        The verb is `POST` because the filters travel in the body, not because the
        call changes anything.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivityFilterBody'
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ActivityForbidden'
  /api/activities/notification:
    post:
      tags:
      - Notifications
      operationId: List Notifications
      description: |-
        HTTP METHOD: POST
        Returns the caller's unseen notifications — the same feed as
        `/api/activities/`, narrowed to activities that are addressed to the
        caller personally and that they have not marked as seen.

        This is what the bell in the navigation bar reads. Body and response are
        shaped exactly like `/api/activities/`.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivityFilterBody'
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ActivityForbidden'
  /api/activities/seen:
    put:
      tags:
      - Notifications
      operationId: Mark Activity as Seen
      description: |-
        HTTP METHOD: PUT
        Marks one activity as seen by the caller. The activity is identified by an
        `id` in the **body** — there is no path parameter.

        Being seen is per user: the caller's id is appended to the activity's
        `seen` list, and the activity then reads `"seen": true` for them and stays
        unchanged for everyone else.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - id
              type: object
              properties:
                id:
                  title: Id
                  description: Id of the activity to mark as seen.
                  type: string
                  example: 66b0f0a1c3d4e5f6a7b8c9d0
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: string
                    example: seen
        '400':
          description: '`id` is missing from the body'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ActivityForbidden'
  /api/activities/see_all:
    post:
      tags:
      - Notifications
      operationId: Mark All Activities as Seen
      description: |-
        HTTP METHOD: POST
        Marks every activity the caller did not themselves cause as seen by them —
        what the "mark all as read" control does. Takes no body.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: string
                    example: see all
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ActivityForbidden'
  /api/activities/delete_notification/{activity_id}:
    delete:
      tags:
      - Notifications
      operationId: Delete an Activity
      description: |-
        HTTP METHOD: DELETE
        Removes one activity from the feed. The activity is flagged deleted rather
        than dropped, so it disappears for everyone, not only for the caller.
      parameters:
      - in: path
        name: activity_id
        required: true
        description: Id of the activity to delete.
        schema:
          type: string
          example: 66b0f0a1c3d4e5f6a7b8c9d0
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: string
                    example: delete_one
        '400':
          description: '`activity_id` is not a valid id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ActivityForbidden'
  /api/activities/delete_all:
    delete:
      tags:
      - Notifications
      operationId: Delete All Activities
      description: |-
        HTTP METHOD: DELETE
        Clears the feed. Administrators clear every activity they did not
        themselves cause; everyone else clears the ones addressed to them. As with
        a single delete, the activities are flagged deleted rather than dropped.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: string
                    example: delete_all
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ActivityForbidden'
  /api/activities/last_modified/{insight_id}:
    get:
      tags:
      - Notifications
      operationId: Retrieve Last Activity on an Insight
      description: |-
        HTTP METHOD: GET
        Returns who last acted on one insight, and when — the "last modified by"
        line of the insight page. The list holds at most one entry, and is empty
        when nothing has happened to the insight yet.
      parameters:
      - in: path
        name: insight_id
        required: true
        description: Id of the insight to look up.
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        user:
                          description: Id of the user who acted.
                          type: string
                        date:
                          description: When they acted, in milliseconds since the epoch.
                          type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ActivityForbidden'
  /api/activities/datetime_intervals:
    get:
      tags:
      - Notifications
      operationId: List Datetime Intervals
      description: |-
        HTTP METHOD: GET
        Returns the date filters the activity feed offers: `predefined` holds the
        ready-made ranges, and `last` holds the unit names a custom "last N …"
        range can be built from. Either shape is accepted as the `interval` of
        `/api/activities/` and `/api/activities/notification`.
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: object
                    properties:
                      last:
                        description: Unit names for a custom range.
                        type: array
                        items:
                          type: string
                      predefined:
                        description: Ready-made ranges.
                        type: array
                        items:
                          $ref: '#/components/schemas/ActivityInterval'
              example:
                results:
                  last:
                  - Seconds
                  - Minutes
                  - Hours
                  - Days
                  - Weeks
                  - Months
                  - Years
                  predefined:
                  - label: All time
                    type: alltime
                    value: null
                  - label: Today
                    type: days
                    value: 0
                  - label: Last 30 mins
                    type: minutes
                    value: 30
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    ACSBody:
      required:
      - SAMLResponse
      type: object
      properties:
        SAMLResponse:
          title: Samlresponse
          type: string
          minLength: 1
    Activity:
      type: object
      description: |-
        One recorded action. Which of the insight-related fields are filled
        depends on the module the action happened in.
      properties:
        id:
          description: Id of the activity.
          type: string
        user:
          description: Id of the user who acted.
          type: string
        date:
          description: When the action happened, in milliseconds since the epoch.
          type: integer
        action:
          description: The action as rendered for display, with inline `<code>` markup.
          type: string
        raw_action:
          description: The action as a machine-readable key, for example `state` or `add_comment`.
          type: string
        seen:
          description: Whether the calling user has marked this activity as seen.
          type: boolean
        extra_data:
          description: Always `null` in responses; the service strips it before serialising.
          type: string
          nullable: true
        insight:
          type: string
          nullable: true
        insight_id:
          type: string
          nullable: true
        group_id:
          description: Id of the insight group the insight belongs to.
          type: string
          nullable: true
        insight_source:
          description: The source, or sources, the insight came from.
          nullable: true
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        insight_title:
          description: |-
            The insight title, either as plain text or as the rich-text fragments
            the insights page renders.
          nullable: true
          oneOf:
          - type: string
          - type: array
            items:
              type: object
        insight_indices:
          description: The index, or indices, the insight lives in.
          nullable: true
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        insight_link:
          description: Path to the insight in the UI.
          type: string
          nullable: true
        last_state_or_level:
          description: |-
            The state or severity the action moved the insight to. State changes
            report an object, everything else a plain string.
          nullable: true
          oneOf:
          - type: string
          - type: object
        module:
          description: Where the action happened, for example `Insights`, `Dashboard`, `Search` or `Role`.
          type: string
          nullable: true
    ActivityFilterBody:
      type: object
      description: |-
        Filters for the activity feed. Every field is optional; an empty body
        returns the first page unfiltered.
      properties:
        keyword:
          description: |-
            Free-text search over the action, source, title, state and module of
            each activity. A list of words is joined with spaces and matched as
            one phrase.
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        page:
          description: 1-based page number. Pages hold 10 activities.
          type: integer
          default: 1
          example: 1
        interval:
          description: |-
            Date range to restrict the feed to. Either an absolute range, or one of
            the ranges `/api/activities/datetime_intervals` offers. A JSON string is
            accepted in place of an object. An unparsable interval is ignored rather
            than rejected.
          allOf:
          - $ref: '#/components/schemas/ActivityInterval'
    ActivityInterval:
      type: object
      description: |-
        A date range. Give `start`/`end` for an absolute range, or `label`, `type`
        and `value` for a relative one. `type: alltime` places no bound.
      properties:
        start:
          description: Lower bound, in seconds since the epoch.
          type: integer
        end:
          description: Upper bound, in seconds since the epoch.
          type: integer
        label:
          description: Display name of the range, for example `Today` or `Last 7 days`.
          type: string
        type:
          description: Unit the range counts back in.
          type: string
          enum:
          - alltime
          - seconds
          - minutes
          - hours
          - days
        value:
          description: How many units to count back.
          type: integer
          nullable: true
    ActivityPage:
      type: object
      description: One page of the activity feed.
      properties:
        results:
          description: The activities on this page, newest first.
          type: array
          items:
            $ref: '#/components/schemas/Activity'
        page:
          description: |-
            Number of the **next** page, or `null` once the last page has been
            reached.
          type: integer
          nullable: true
        total:
          description: Number of activities matching the filters.
          type: integer
        count:
          description: Number of activities on this page, at most 10.
          type: integer
    ActivityError:
      type: object
      description: |-
        How the activities service reports an error. Note that it reports the
        reason under `message`, where the other services use `detail`.
      properties:
        message:
          description: Error reason.
          type: string
    IntegrationError:
      type: object
      properties:
        message:
          description: Error reason.
          type: string
    JiraNotificationBody:
      required:
      - project_id
      type: object
      properties:
        project_id:
          description: Jira project the issue is created in.
          type: string
        board_id:
          description: Board to place the issue on.
          type: string
        sprint_id:
          description: Sprint to place the issue in.
          type: string
        issue_type:
          description: Issue type; the project's first type is used when omitted.
          type: string
        priority:
          type: string
        account_id:
          description: Jira account id of the assignee.
          type: string
    JiraSendResult:
      type: object
      properties:
        message:
          type: string
        issue_key:
          type: string
        issue_url:
          type: string
        project_id:
          type: string
        board_id:
          type: string
        sprint_id:
          type: string
        insight_group:
          type: string
    JiraTicket:
      type: object
      properties:
        ticket:
          description: The issue as Logmind stored it.
          type: object
          nullable: true
        jira_data:
          description: Live issue data from Jira, with history and comments.
          type: object
          nullable: true
        message:
          type: string
    ServiceNowNotificationBody:
      type: object
      properties:
        urgency:
          type: string
        state:
          $ref: '#/components/schemas/ServiceNowChoice'
        category:
          $ref: '#/components/schemas/ServiceNowChoice'
        subcategory:
          $ref: '#/components/schemas/ServiceNowChoice'
        contact_type:
          $ref: '#/components/schemas/ServiceNowChoice'
        assignment_group:
          $ref: '#/components/schemas/ServiceNowReference'
        assigned_to:
          $ref: '#/components/schemas/ServiceNowReference'
        business_service:
          $ref: '#/components/schemas/ServiceNowReference'
        work_notes:
          type: string
        comments:
          type: string
    ServiceNowChoice:
      description: A ServiceNow choice field, given by value.
      type: object
      properties:
        value:
          type: string
    ServiceNowReference:
      description: A ServiceNow reference field, given by record id.
      type: object
      properties:
        sys_id:
          type: string
    ServiceNowSendResult:
      type: object
      properties:
        message:
          type: string
        incident_number:
          type: string
        incident_url:
          type: string
        insight_group:
          type: string
    ServiceNowTicket:
      type: object
      properties:
        ticket:
          description: The incident as Logmind stored it.
          type: object
          nullable: true
        sn_data:
          description: Live incident data from ServiceNow, with work notes and comments.
          type: object
          nullable: true
        message:
          type: string
    PagerDutyNotificationBody:
      required:
      - service_id
      type: object
      properties:
        service_id:
          type: string
        assignee_id:
          type: string
        escalation_policy_id:
          type: string
        priority_id:
          type: string
        urgency:
          type: string
          enum:
          - high
          - low
        incident_status:
          type: string
    PagerDutySendResult:
      type: object
      properties:
        message:
          type: string
        incident_id:
          type: string
        incident_number:
          type: string
        incident_url:
          type: string
        insight_group:
          type: string
    PagerDutyTicket:
      type: object
      properties:
        ticket:
          description: The incident as Logmind stored it.
          type: object
          nullable: true
        pd_data:
          description: Live incident data from PagerDuty, with log entries and notes.
          type: object
          nullable: true
        message:
          type: string
    Embedded:
      type: object
      properties:
        name:
          title: Name
          type: string
          minLength: 1
    PatternResults:
      type: object
      properties:
        id:
          title: id
          type: string
          readOnly: true
        order:
          title: Order
          type: integer
        first_occurrence:
          title: First occurrence
          type: string
          readOnly: true
        last_occurrence:
          title: Last occurrence
          type: string
          readOnly: true
        level:
          title: Level
          type: string
          minLength: 1
        occurrences:
          title: Occurrences
          type: integer
        pattern:
          title: Pattern
          type: string
          minLength: 1
        percent:
          title: Percent
          type: string
          format: decimal
        stats:
          type: array
          items:
            type: string
            nullable: true
    ChartTypeBody:
      required:
      - type
      type: object
      properties:
        name:
          title: Name
          description: The name of the chart type
          type: string
          minLength: 1
        type:
          title: Type
          description: The type of the chart
          type: string
          minLength: 1
    CreateCriticalPatternBody:
      required:
      - occurrences
      - first_occurrence
      - last_occurrence
      - pattern
      type: object
      properties:
        occurrences:
          title: Occurrences
          description: total occurrences
          type: integer
        first_occurrence:
          title: First occurrence
          description: pattern first occurrence
          type: string
          minLength: 1
        last_occurrence:
          title: Last occurrence
          description: pattern last occurrence
          type: string
          minLength: 1
        pattern:
          title: Pattern
          description: pattern fields
          type: array
          items:
            type: object
            properties:
              text:
                type: string
              position:
                type: integer
              tag:
                type: string
            required:
            - text
    CreatePatternsResponse:
      required:
      - result
      - limit
      type: object
      properties:
        result:
          title: Result
          type: object
          description: Patterns Result
          properties:
            pattern:
              type: array
              items:
                description: Pattern text position
                type: object
                properties:
                  text:
                    type: string
                    description: The pattern text
                  position:
                    type: integer
                    description: The position of the pattern
                  tag:
                    type: string
                    description: The tag associated with the pattern
                required:
                - text
            stats:
              description: Array of pattern occurrences stats
              type: array
              items:
                type: array
                items:
                  type: integer
            occurrences:
              type: integer
              description: Number of pattern occurrences
            first_occurrence:
              type: string
              description: First occurrence of pattern
            last_occurrence:
              type: string
              description: Last occurrence of pattern
            source:
              type: string
              description: Index
            hosts:
              type: string
              description: Patterns host
            pattern_field:
              type: string
              description: Pattern field
            host_count:
              type: integer
              description: Count of patterns host
            id:
              type: string
              description: ID
            query:
              type: string
              description: Patterns query
            exist:
              type: boolean
              description: Flag indicating if the pattern exists
            percent:
              type: number
              description: Occurrence percentage
          required:
          - pattern
          - stats
          - occurrences
          - first_occurrence
          - last_occurrence
          - source
          - hosts
          - pattern_field
          - host_count
          - id
          - query
          - exist
          - percent
        limit:
          title: Limit
          description: limit of patterns on each page
          type: integer
        offset:
          title: Offset
          description: pagination page number
          type: integer
    CreateRoleBody:
      required:
      - name
      - description
      - indices
      - rights
      type: object
      properties:
        name:
          title: Role Name
          type: string
          minLength: 1
        description:
          title: Description
          type: string
          minLength: 1
        indices:
          type: array
          items:
            type: string
            minLength: 1
        rights:
          $ref: '#/components/schemas/RightResult'
    CreateVisualizationBody:
      required:
      - query_config
      - data
      - dashboard
      type: object
      properties:
        query_config:
          title: Query config
          description: visualization query
          type: object
          properties:
            query:
              description: searching parameters
              type: object
              properties: {}
            indices:
              description: list of indices
              type: array
              items:
                type: string
            isAggs:
              type: boolean
            queryString:
              type: string
            times:
              description: time format and filter
              type: object
              properties:
                times:
                  type: array
                  items:
                    type: object
                    properties:
                      gte:
                        type: string
                      lte:
                        type: string
        data:
          title: Data
          description: static data of visualization
          type: object
          properties:
            instanceName:
              type: object
              properties: {}
            instanceState:
              type: object
              properties: {}
            formsValues:
              type: object
              properties: {}
        dashboard:
          title: Dashboard
          description: dashboard name and id
          type: object
          properties:
            id:
              description: dashboard id
              type: string
            name:
              description: dashboard name
              type: string
    CreateVisualizationResponse:
      required:
      - result
      type: object
      properties:
        result:
          title: Result
          type: array
          description: '[{''title'': title, ''id'': ''id'',}]'
          items:
            type: object
            properties:
              title:
                description: visualization title
                type: string
              id:
                description: visualization Id
                type: string
        message:
          title: Message
          type: string
          default: Visualization has been successfully added to { dashboard_name } dashboard
          minLength: 1
    DateTimeQuickResponse:
      required:
      - result
      type: object
      properties:
        result:
          title: Result
          type: array
          description: '[{''name'': name, ''gte'': ''gte'', ''lte'': ''lte'', ''type'':''type''}]'
          items:
            type: object
            properties:
              name:
                type: string
                description: 'time field name: "Last 5 mins'
              gte:
                type: string
                description: 'gte field name: now-5m'
              lte:
                type: string
                description: 'lte field name: now'
              type:
                type: string
                description: 'type field name: minute'
    DateTimeRangeResponse:
      required:
      - result
      type: object
      properties:
        result:
          title: Result
          type: array
          description: '[{''name'': name, ''type'': ''type''}]'
          items:
            type: object
            properties:
              name:
                type: string
                description: 'time field name: Between'
              type:
                type: string
                description: 'type field name: between'
    DateTimeUnitResponse:
      required:
      - result
      type: object
      properties:
        result:
          title: Result
          type: array
          description: 'static datetimes names and short keywords : [{''name'': name, ''indicator'': ''indicator''}]'
          items:
            type: object
            properties:
              name:
                type: string
                description: 'time field name: Minutes'
              indicator:
                type: string
                description: 'time field short name : m'
    FeedBackSuccess:
      required:
      - message
      - status
      type: object
      properties:
        message:
          title: Message
          type: string
          minLength: 1
        status:
          title: Status
          type: string
          minLength: 1
    InvitationBody:
      required:
      - roles
      - email
      type: object
      properties:
        roles:
          description: assign roles
          type: array
          items:
            type: string
            minLength: 1
        email:
          title: Email
          type: string
          minLength: 1
    ListPatternsResult:
      required:
      - result
      - page
      - total
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/PatternResults'
        page:
          title: Page
          description: page number
          type: integer
        total:
          title: Total
          description: total patterns
          type: integer
        limit:
          title: Limit
          description: 'limit of patterns on each page '
          type: integer
          default: 20
        after_key:
          title: After key
          description: next page
          type: string
          minLength: 1
    ListVisualizationResponse:
      required:
      - id
      - visualization
      - grid_layout
      - title
      type: object
      properties:
        id:
          title: Id
          type: string
          minLength: 1
        visualization:
          title: Visualization
          type: array
          description: Visualization Serializer
          items:
            type: object
            properties:
              id:
                description: The ID of the visualization
                type: string
              title:
                description: The title of the visualization
                type: string
              query_config:
                description: The query configuration
                type: object
                properties:
                  query:
                    description: The query configuration
                    type: object
                    properties: {}
                  indices:
                    description: The indices used in the visualization
                    type: array
                    items:
                      type: string
                  isAggs:
                    description: Flag indicating if aggregation exist
                    type: boolean
                  queryString:
                    description: The query string
                    type: string
                  times:
                    type: object
                    properties:
                      times:
                        description: The times filter and format
                        type: array
                        items:
                          type: object
                          properties:
                            gte:
                              description: The start time
                              type: string
                            lte:
                              description: The end time
                              type: string
              data:
                description: The visualization data
                type: object
                properties:
                  instanceName:
                    description: The instance name
                    type: string
                  instanceState:
                    description: The instance state
                    type: object
                    properties: {}
                  formsValues:
                    description: The form values
                    type: object
                    properties: {}
        grid_layout:
          title: Grid layout
          type: array
          description: stats for creating visualizations and charts
          items:
            type: object
            properties:
              w:
                description: The width of the element
                type: integer
              h:
                description: The height of the element
                type: integer
              x:
                description: The X position of the element
                type: integer
              y:
                description: The Y position of the element
                type: integer
              i:
                description: The unique identifier of the element
                type: string
              moved:
                description: Flag indicating if the element was moved
                type: boolean
              static:
                description: Flag indicating if the element is static
                type: boolean
        title:
          title: Title
          description: dashboard title
          type: string
          minLength: 1
        status:
          title: Status
          description: dashboard status
          type: string
          minLength: 1
        is_live:
          title: Is live
          description: if visualization still exist
          type: string
          minLength: 1
    LogInBody:
      required:
      - username
      - password
      type: object
      properties:
        username:
          title: Username
          description: The user's email address. The field is named `username`
            for historical reasons; an `email` key in the body is ignored.
          type: string
          format: email
          minLength: 1
          example: user@example.com
        password:
          title: Password
          type: string
          format: password
          minLength: 1
    LogInResponse:
      required:
      - refresh
      - access
      type: object
      properties:
        refresh:
          title: Refresh
          description: refresh token
          type: string
          minLength: 1
        access:
          title: Access
          description: access token
          type: string
          minLength: 1
    PasswordReset:
      required:
      - email
      type: object
      properties:
        email:
          title: Email
          type: string
          format: email
          minLength: 1
    PasswordResetDone:
      required:
      - password
      - activation_key
      type: object
      properties:
        password:
          title: Password
          type: string
          minLength: 1
        activation_key:
          title: Activation key
          type: string
          minLength: 1
    PasswordResponse:
      required:
      - message
      type: object
      properties:
        message:
          title: Message
          description: Password change text
          type: string
          minLength: 1
    PlaceholdersResponse:
      required:
      - data
      type: object
      properties:
        data:
          title: Data
          description: '[{''key'': key, ''count'': ''occurrence count'', ''percentage'': ''percentage''}]'
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              count:
                type: integer
              percentage:
                type: integer
    RefreshTokenBody:
      required:
      - refresh
      type: object
      properties:
        refresh:
          title: Refresh
          description: old token
          type: string
          minLength: 1
    RefreshTokenResponse:
      required:
      - access
      type: object
      properties:
        access:
          title: Access
          type: string
          minLength: 1
    ReportBody:
      type: object
      description: report body
      properties:
        indices:
          title: Indices
          description: User selected indices
          type: array
          items:
            type: string
        timestamp:
          title: Times
          type: array
          description: time filter and formatting
          items:
            type: object
            properties:
              gte:
                description: greater than or equal
                type: string
              lte:
                description: lower than or equal
                type: string
        query:
          title: Query
          description: User search query
          type: string
          minLength: 1
        recipients:
          title: Recipients
          description: User selected recipients to send report
          type: array
          items:
            type: string
        filename:
          title: Filename
          description: report filename
          type: string
          minLength: 1
        format:
          title: Format
          description: Report file format
          type: string
          minLength: 1
    ReSendInvitationBody:
      required:
      - email
      type: object
      properties:
        email:
          title: email
          type: string
          format: email
          minLength: 1
    RightResult:
      required:
      - discover
      - dashboards
      - visualisations
      - insights
      - alerts
      - access_control
      type: object
      properties:
        discover:
          title: Discover
          description: accesses for discover
          type: object
          properties:
            title:
              description: discover
              type: string
              example: Discover
            add:
              description: add permission
              type: boolean
            view:
              description: view permission
              type: boolean
            edit:
              description: edit permission
              type: boolean
            delete:
              description: delete permission
              type: boolean
        dashboards:
          title: Dashboards
          description: accesses for dashboards
          type: object
          properties:
            title:
              description: dashboards
              type: string
              example: Dashboard
            add:
              description: add permission
              type: boolean
            view:
              description: view permission
              type: boolean
            edit:
              description: edit permission
              type: boolean
            delete:
              description: delete permission
              type: boolean
        visualizations:
          title: Visualisations
          description: accesses for visualisations
          type: object
          properties:
            title:
              description: visualisations
              type: string
              example: Visualisations
            add:
              description: add permission
              type: boolean
            view:
              description: view permission
              type: boolean
            edit:
              description: edit permission
              type: boolean
            delete:
              description: delete permission
              type: boolean
        insights:
          title: Insights
          description: accesses for insights
          type: object
          properties:
            title:
              description: insights
              type: string
              example: Insights
            add:
              description: add permission
              type: boolean
            view:
              description: view permission
              type: boolean
            edit:
              description: edit permission
              type: boolean
            delete:
              description: delete permission
              type: boolean
        alerts:
          title: Alerts
          description: accesses for alerts
          type: object
          properties:
            title:
              description: alerts
              type: string
              example: Alerts
            add:
              description: add permission
              type: boolean
            view:
              description: view permission
              type: boolean
            edit:
              description: edit permission
              type: boolean
            delete:
              description: delete permission
              type: boolean
        access_control:
          title: Access control
          description: accesses for access control
          type: object
          properties:
            title:
              description: access_control
              type: string
              example: Access_Control
            add:
              description: add permission
              type: boolean
            view:
              description: view permission
              type: boolean
            edit:
              description: edit permission
              type: boolean
            delete:
              description: delete permission
              type: boolean
    RightsBody:
      required:
      - rights
      type: object
      properties:
        rights:
          $ref: '#/components/schemas/RightResult'
    RolesResult:
      required:
      - id
      - slug
      - name
      - description
      - is_deleted
      - rights
      - can_delete
      - is_administrator
      - created_at
      type: object
      properties:
        id:
          title: Id
          description: The unique identifier of the role.
          type: string
          minLength: 1
        slug:
          title: Slug
          description: The slug associated with the role.
          type: string
          minLength: 1
        name:
          title: Name
          description: The name of the role.
          type: string
          minLength: 1
        description:
          title: Description
          description: The description of the role.
          type: string
          minLength: 1
        is_deleted:
          title: Is deleted
          description: Indicates whether the role is deleted or not.
          type: boolean
        rights:
          title: Rights
          description: The description of the rights assigned to the role.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RightResult'
        can_delete:
          title: Can delete
          description: Specifies if the role can be deleted.
          type: boolean
        is_administrator:
          title: Is administrator
          description: Indicates if the role is an administrator.
          type: boolean
        created_at:
          title: Created at
          description: The creation date of the role.
          type: string
          format: date-time
    SamlLoginBody:
      required:
      - org_name
      type: object
      properties:
        org_name:
          title: Org name
          type: string
          minLength: 1
    SearchField:
      type: object
      properties:
        field_name:
          title: Field name
          type: string
          minLength: 1
        field_type:
          title: Field type
          type: string
          minLength: 1
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Embedded'
    UpdateAllVSBody:
      required:
      - visualizations
      type: object
      properties:
        visualizations:
          description: contains active visualizations
          type: array
          items:
            $ref: '#/components/schemas/CreateVisualizationBody'
    UpdateRoleBody:
      required:
      - name
      - description
      type: object
      properties:
        name:
          title: Name
          description: role name
          type: string
          minLength: 1
        description:
          title: Description
          description: role description
          type: string
          minLength: 1
    UpdateRoleIndexBody:
      required:
      - index
      type: object
      properties:
        index:
          title: Index
          type: string
          minLength: 1
    UpdateUser:
      required:
      - id
      - first_name
      - last_name
      type: object
      properties:
        id:
          title: Id
          type: string
          minLength: 1
        first_name:
          title: First name
          type: string
          minLength: 1
        last_name:
          title: Last name
          type: string
          minLength: 1
    UserActivation:
      required:
      - first_name
      - last_name
      - password
      type: object
      properties:
        first_name:
          title: First name
          type: string
          minLength: 1
        last_name:
          title: Last name
          type: string
          minLength: 1
        password:
          title: Password
          type: string
          minLength: 1
    UserDetail:
      required:
      - id
      - first_name
      - last_name
      - email
      - last_login
      - date_joined
      - is_active
      - is_superuser
      - slug
      - roles
      - rights
      type: object
      properties:
        id:
          title: Id
          description: user's id
          type: string
          minLength: 1
        first_name:
          title: First name
          description: user's first name
          type: string
          minLength: 1
        last_name:
          title: Last name
          description: user's Last name
          type: string
          minLength: 1
        email:
          title: Email
          description: user email
          type: string
          format: email
          minLength: 1
        last_login:
          title: Last login
          description: last login of user
          type: string
          minLength: 1
        date_joined:
          title: Date joined
          description: registration date of user
          type: string
          minLength: 1
        is_active:
          title: Is active
          description: if user is active
          type: boolean
        is_superuser:
          title: Is superuser
          description: has a administrator roles
          type: boolean
        slug:
          title: Slug
          description: slug
          type: string
          minLength: 1
        roles:
          description: user roles
          type: array
          items:
            $ref: '#/components/schemas/RolesResult'
        rights:
          title: Rights
          description: user rights
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RightResult'
    UserResult:
      required:
      - id
      - first_name
      - last_name
      - email
      - last_login
      - date_joined
      - is_active
      - is_superuser
      - slug
      - roles
      type: object
      properties:
        id:
          title: Id
          description: user's id
          type: string
          minLength: 1
        first_name:
          title: First name
          description: user's first name
          type: string
          minLength: 1
        last_name:
          title: Last name
          description: user's Last name
          type: string
          minLength: 1
        email:
          title: Email
          type: string
          format: email
          minLength: 1
        last_login:
          title: Last login
          type: string
          minLength: 1
        date_joined:
          title: Date joined
          type: string
          minLength: 1
        is_active:
          title: Is active
          type: boolean
        is_superuser:
          title: Is superuser
          type: boolean
        slug:
          title: Slug
          type: string
          minLength: 1
        roles:
          description: user roles
          type: array
          items:
            $ref: '#/components/schemas/RolesResult'
    UserVerifyResponse:
      required:
      - X_User
      - X_User_Env
      - Authorization
      type: object
      properties:
        X_User:
          title: X user
          description: X-User, accessed data
          type: object
          properties:
            id:
              type: string
            first_name:
              type: string
            last_name:
              type: string
            is_superuser:
              type: boolean
            is_administrator:
              type: boolean
            is_active:
              type: boolean
            email:
              type: string
              format: email
            username:
              type: string
            roles:
              type: array
              items:
                type: string
            indices:
              type: array
              items:
                type: string
            rights:
              type: array
              items:
                type: string
        X_User_Env:
          title: X user env
          description: X-User-Env, user detail information
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            main_db:
              type: string
            insights_db:
              type: string
            patterns_db:
              type: string
            activities_db:
              type: string
        Authorization:
          title: Authorization
          description: authorization token
          type: string
          minLength: 1
    VerifyToken:
      required:
      - token
      type: object
      properties:
        token:
          title: Token
          type: string
          minLength: 1
    VisualizationJSON:
      required:
      - title
      - query_config
      - query
      - position
      - data
      - dashboard
      type: object
      properties:
        title:
          title: Title
          description: The title of the visualization
          type: string
          minLength: 1
        query_config:
          title: Query config
          description: The configuration of the visualization query
          type: string
          minLength: 1
        query:
          title: Query
          description: The query used for the visualization
          type: string
          minLength: 1
        position:
          title: Position
          description: The position of the visualization on the dashboard
          type: string
          minLength: 1
        data:
          title: Data
          description: The data associated with the visualization
          type: string
          minLength: 1
        dashboard:
          title: Dashboard
          description: The ID of the associated dashboard
          type: string
    PasswordChange:
      required:
      - old_password
      - password
      type: object
      properties:
        old_password:
          title: Old password
          description: The password currently in use.
          type: string
          minLength: 1
        password:
          title: Password
          description: The new password. It has to satisfy the password-strength policy.
          type: string
          minLength: 1
    UserRolesBody:
      required:
      - roles
      type: object
      properties:
        roles:
          title: Roles
          description: The roles to assign, each given as an object carrying its id.
          type: array
          items:
            type: object
            properties:
              id:
                type: string
      example:
        roles:
        - id: 65f1c2a4b8d3e40012a7f001
    InsightsFilterBody:
      type: object
      description: Filter accepted by the insights listing.
      properties:
        index:
          description: Sources to search. A single name, a list, or `*` for every source the caller may
            read.
          type: array
          items:
            type: string
        service:
          description: Service names the insights must belong to.
          type: array
          items:
            type: string
        host:
          description: Entities the insights must concern.
          type: array
          items:
            type: string
        interval:
          title: Interval
          description: |-
            Period to report on. Either a named period (`{"value": "Last 7 days"}`)
            or an explicit range in milliseconds (`{"start": …, "end": …}`).
            When absent, the environment's configured default period is used.
          type: object
          properties:
            value:
              type: string
            start:
              type: integer
              format: int64
            end:
              type: integer
              format: int64
        page:
          title: Page
          description: Page to return, starting at 1.
          type: integer
        limit:
          title: Limit
          description: Page size. Defaults to 5, at most 100.
          type: integer
    InsightGroupsFilterBody:
      type: object
      description: Filter accepted by the insight group listings and by the summary widgets.
      properties:
        index:
          description: Sources the groups must touch.
          type: array
          items:
            type: string
        service:
          description: Service names the groups must touch.
          type: array
          items:
            type: string
        service_group:
          title: Service group
          description: Name of the service group the insights must belong to.
          type: string
        host:
          description: Entities the groups must concern.
          type: array
          items:
            type: string
        level:
          description: 'Severities to keep: `critical`, `major`, `minor`, `unknown`.'
          type: array
          items:
            type: string
        status:
          description: 'Status codes to keep: 0 active, 1 unhandled, 2 resolved, 3 ignored.'
          type: array
          items:
            type: integer
        assigned_users:
          description: Identifiers of the users the groups are assigned to.
          type: array
          items:
            type: string
        hasAssignedTo:
          title: Has assigned to
          description: Keep only groups that have, or have not, an assignee.
          type: boolean
        comments:
          title: Comments
          description: Keep only groups that carry comments.
          type: boolean
        dynamic_components_filter:
          title: Dynamic components filter
          description: Service group name mapped to the service names to keep within it.
          type: object
        q:
          title: Q
          description: |-
            Free text. Matches the insight title, the last event, the source, the
            entity names, the service names, the service group, the status, the AI
            title and the assignees.
          type: string
        interval:
          title: Interval
          description: Period to report on, as in the insights listing.
          type: object
        page:
          type: integer
        limit:
          type: integer
    ListInsightsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Insight'
        page:
          title: Page
          description: Page to request next, or `null` on the last page.
          type: integer
          nullable: true
        total:
          title: Total
          description: Number of insights matching the filter.
          type: integer
        count:
          title: Count
          description: Number of insights in this page.
          type: integer
    Insight:
      type: object
      description: One insight, as it appears in a listing.
      properties:
        id:
          type: string
        title:
          type: string
        level:
          description: Severity of the insight, with its name, code and colour class.
          type: object
        service:
          type: string
        type:
          description: What the insight was built from — an alert, or an anomaly.
          type: string
        index:
          description: Source the insight belongs to.
          type: string
        event_date:
          description: The period the insight covers, formatted for display.
          type: string
        new_pattern:
          description: Whether the insight introduced a message pattern never seen before.
          type: boolean
        meta:
          type: object
        docs:
          description: Number of events behind the insight.
          type: integer
        comments:
          description: Number of comments on the group the insight belongs to.
          type: integer
        muted:
          type: boolean
        date:
          type: object
          properties:
            gte:
              type: number
            lte:
              type: number
        label_tags:
          description: Extra fields the environment chose to surface on the listing.
          type: object
    InsightDetail:
      type: object
      description: One insight, in full.
      properties:
        id:
          type: string
        title:
          type: string
        severity:
          type: object
          properties:
            name:
              type: string
            code:
              type: integer
        index:
          type: string
        service:
          type: string
        meta:
          type: object
        query:
          description: The Elasticsearch query behind the insight's events.
          type: object
        assigned_users:
          type: array
          items:
            type: object
        new_pattern:
          type: boolean
        is_active:
          type: boolean
        custom_fields:
          type: object
        entities:
          type: array
          items:
            type: object
    InsightAlertsResponse:
      type: object
      description: The alert objects behind an insight, with their severity spans.
      properties:
        min_date:
          type: string
          format: date-time
        max_date:
          type: string
          format: date-time
        object_stats:
          type: array
          items:
            type: object
            properties:
              sensor:
                type: string
              device:
                type: string
              level:
                type: object
              stats:
                type: array
                items:
                  type: object
                  properties:
                    level:
                      type: object
                    start:
                      type: string
                      format: date-time
                    end:
                      type: string
                      format: date-time
                    message_patterns:
                      type: array
                      items:
                        type: string
    InsightAnomaly:
      type: object
      description: One anomaly behind an insight.
      properties:
        anomaly_id:
          type: string
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
        severity:
          type: object
        status:
          type: string
        entities:
          type: array
          items:
            type: string
        index:
          type: string
        total:
          description: Number of events the anomaly covers.
          type: integer
        field_name:
          description: The field the anomaly was tracked on; `message` for a pattern anomaly.
          type: string
        field_value:
          description: |-
            The tracked value; for a pattern anomaly, the pattern title with its
            variable parts rendered as `*`.
          type: string
        placeholders:
          description: |-
            Present on pattern anomalies. Each entry maps a rendered `*` to the token
            position whose values `placeholder_tokens` can expand.
          type: array
          items:
            type: object
            properties:
              position:
                type: integer
        timeline:
          type: array
          items:
            type: object
            properties:
              key:
                description: Sample time, in milliseconds.
                type: integer
                format: int64
              key_as_string:
                type: string
              doc_count:
                type: integer
              is_anomaly:
                description: Whether this sample falls inside the anomalous window.
                type: boolean
    PlaceholderTokensBody:
      required:
      - anomaly_id
      - position
      type: object
      properties:
        anomaly_id:
          title: Anomaly id
          description: Identifier of the pattern anomaly, as returned by `anomalies` or `get_components`.
          type: string
        position:
          title: Position
          description: Token position of the placeholder that was clicked.
          type: integer
        selected:
          title: Selected
          description: Placeholders already pinned, as `[position, value]` pairs.
          type: array
          items:
            type: array
            items:
              type: string
    PlaceholderTokensResponse:
      type: object
      properties:
        values:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              count:
                type: integer
        total:
          type: integer
    InsightsOccurrences:
      type: object
      description: |-
        Occurrence statistics of an insight. With `fields` the answer holds one entry
        per field, each mapping a value to its count and share; with `is_timeline` it
        holds the distribution over time instead.
      properties:
        occurrences:
          type: object
          properties:
            fields:
              type: array
              items:
                type: object
                description: 'Field name mapped to `{value: {count, percentage}}`.'
            result:
              description: Present for a timeline request.
              type: array
              items:
                type: object
                properties:
                  values:
                    type: array
                    items:
                      type: array
                      items:
                        type: number
    InsightLevelResponse:
      type: object
      properties:
        response:
          type: object
          properties:
            levels:
              description: The severities that can be selected.
              type: array
              items:
                type: string
            selected:
              description: The severity currently in force.
              type: string
      example:
        response:
          levels:
          - CRITICAL
          - MAJOR
          - MINOR
          selected: MAJOR
    InsightLevelBody:
      required:
      - level
      type: object
      properties:
        level:
          title: Level
          description: 'The severity to set: `critical`, `major`, `minor` or `unknown`.'
          type: string
    LevelUpdatedResponse:
      type: object
      properties:
        message:
          type: string
        status:
          type: string
        selected:
          type: string
        code:
          description: Numeric weight of the severity.
          type: integer
        class:
          description: Colour class the interface draws the severity with.
          type: string
    ListInsightGroupsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/InsightGroup'
        page:
          type: integer
          nullable: true
        total:
          type: integer
        count:
          type: integer
    InsightGroup:
      type: object
      description: A group of insights describing one and the same incident.
      properties:
        id:
          type: string
        indices:
          type: array
          items:
            type: string
        service_group:
          type: string
          nullable: true
        service_names:
          type: array
          items:
            type: string
        status:
          description: '`active` or `unhandled`, as computed by the pipeline.'
          type: string
        severity:
          type: object
        comment_counts:
          type: integer
        assigned_users:
          type: array
          items:
            type: object
        insights:
          type: array
          items:
            $ref: '#/components/schemas/Insight'
        ai_title:
          description: Title generated for the incident.
          type: string
        ai_model:
          description: Model that produced the summary.
          type: string
        ai_root_cause:
          type: string
        ai_procedures:
          description: Suggested procedures, each with its priority and its steps.
          type: array
          items:
            type: object
        summary:
          type: string
        description:
          type: string
        jira_sent:
          type: boolean
        servicenow_sent:
          type: boolean
        pagerduty_sent:
          type: boolean
    InsightGroupV3:
      type: object
      description: An insight group as the Overview listing shows it.
      properties:
        id:
          type: string
        ai_title:
          type: string
        last_seen:
          type: string
          nullable: true
        events:
          type: integer
        status:
          type: string
        severity:
          type: object
        service_group:
          type: string
          nullable: true
        services:
          type: array
          items:
            type: string
        indices:
          type: array
          items:
            type: string
        assigned_users:
          type: array
          items:
            type: object
        entities:
          type: array
          items:
            type: object
        custom_fields:
          type: object
        range:
          description: The period the group covers.
          type: object
    InsightGroupV3Detail:
      type: object
      description: An insight group as the Overview detail shows it.
      properties:
        id:
          type: string
        ai_title:
          type: string
        ai_model:
          type: string
        ai_root_cause:
          type: string
        ai_procedures:
          type: array
          items:
            type: object
        summary:
          type: string
        description:
          type: string
        jira_sent:
          type: boolean
        servicenow_sent:
          type: boolean
        pagerduty_sent:
          type: boolean
        last_seen:
          type: string
          nullable: true
        total_events:
          type: integer
        status:
          type: string
        severity:
          type: object
        service_group:
          type: string
          nullable: true
        services:
          type: array
          items:
            type: string
        indices:
          type: array
          items:
            type: string
        assigned_users:
          type: array
          items:
            type: object
        entities:
          type: array
          items:
            type: object
        custom_fields:
          type: object
        range:
          type: object
        query:
          description: The Elasticsearch query behind the group's events.
          type: object
    InsightGroupChatbot:
      type: object
      description: An insight group with its stored fields left as they are.
      properties:
        id:
          type: string
        service_group:
          type: string
          nullable: true
        service_names:
          type: array
          items:
            type: string
        indices:
          type: array
          items:
            type: string
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
        level:
          type: string
        status:
          type: string
        assigned_status:
          type: string
          nullable: true
        assigned_status_data:
          type: object
          properties:
            previous:
              type: string
            updated_at:
              type: string
              format: date-time
            updated_by:
              type: string
          nullable: true
        event_count:
          type: integer
        ai_model:
          type: string
        ai_title:
          type: string
        ai_root_cause:
          type: string
        ai_procedures:
          type: array
          items:
            type: object
        ai_severity_score:
          type: number
        is_ai_summary_outdated:
          type: boolean
        is_visible:
          type: boolean
        insights:
          type: array
          items:
            type: object
    SeverityCountsResponse:
      type: object
      description: |-
        How many insight groups of each severity are open, per target. Only the keys
        that were asked for are present.
      properties:
        services:
          type: object
          additionalProperties:
            type: object
        service_groups:
          type: object
          additionalProperties:
            type: object
        entities:
          type: object
          additionalProperties:
            type: object
    ServiceTopologyResponse:
      type: object
      properties:
        nodes:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              service_name:
                type: string
              service_class:
                type: string
              criticality:
                type: string
              status:
                type: string
              indices:
                type: array
                items:
                  type: string
              severity:
                type: object
              anomaly_count:
                type: integer
              anomalies:
                description: Anomaly counts broken down by severity.
                type: object
              entity_count:
                type: integer
              in_group:
                description: Whether the group actually reaches this service.
                type: boolean
        edges:
          type: array
          items:
            type: object
            properties:
              from:
                type: string
              to:
                type: string
                nullable: true
    SummaryResponse:
      type: object
      description: |-
        One timeline per severity, plus the title and the period they report on. Each
        timeline gives its points as `[timestamp, count]`, the count over the period
        and the progress against the preceding period of the same length.
      properties:
        Critical:
          $ref: '#/components/schemas/SummaryTimeline'
        Major:
          $ref: '#/components/schemas/SummaryTimeline'
        Minor:
          $ref: '#/components/schemas/SummaryTimeline'
        Unknown:
          $ref: '#/components/schemas/SummaryTimeline'
        title:
          type: string
        interval:
          type: string
          example: Last 30 Days
    StatusSummaryResponse:
      type: object
      description: One timeline per status, in the same shape as the severity summary.
      properties:
        Active:
          $ref: '#/components/schemas/SummaryTimeline'
        Unhandled:
          $ref: '#/components/schemas/SummaryTimeline'
        Resolved:
          $ref: '#/components/schemas/SummaryTimeline'
        Ignored:
          $ref: '#/components/schemas/SummaryTimeline'
        title:
          type: string
        interval:
          type: string
    SummaryTimeline:
      type: object
      properties:
        data:
          description: Points of the timeline, as `[timestamp in ms, count]`.
          type: array
          items:
            type: array
            items:
              type: number
        count:
          type: integer
        progress:
          description: Change against the preceding period, in percent.
          type: number
        filter:
          description: The filter that reproduces this timeline in the group list.
          type: object
        key:
          type: string
    Comment:
      type: object
      properties:
        id:
          type: string
        user:
          type: string
        text:
          type: string
        date:
          description: How long ago the comment was posted.
          type: string
          example: 2 hours ago
        has_right:
          description: Whether the caller may edit or delete this comment.
          type: boolean
        edited:
          type: boolean
        reply_count:
          type: integer
        replies:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              username:
                type: string
              date:
                type: string
              text:
                type: string
              edited:
                type: boolean
              has_right:
                type: boolean
    SavedInsightFilter:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        query:
          description: The filter itself, in the shape the listing takes.
          type: object
        is_favorite:
          description: Applied automatically when the page opens.
          type: boolean
        is_tab:
          description: Pinned to the tab bar.
          type: boolean
        position:
          description: Place in the tab bar; `null` when the filter is not pinned.
          type: integer
          nullable: true
    SavedInsightFilterBody:
      required:
      - name
      - query
      type: object
      properties:
        name:
          type: string
        query:
          type: object
        is_favorite:
          type: boolean
        is_tab:
          type: boolean
        position:
          type: integer
    InsightDashboard:
      type: object
      properties:
        grid_layout:
          description: Placement of the charts on the grid.
          type: object
        charts:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              title:
                type: string
              type:
                type: string
              interval:
                type: object
              is_active:
                type: boolean
    NotificationRecipient:
      type: object
      description: |-
        A delivery target for insights. Exactly one of `email`, `slack`,
        `microsoftteams`, `jira`, `servicenow` or `pagerduty` is filled, matching
        `channel`; the others are `null`.
      properties:
        id:
          type: string
        title:
          type: string
        channel:
          type: string
          enum:
          - email
          - slack
          - microsoftteams
          - jira
          - servicenow
          - pagerduty
        is_active:
          type: boolean
        filter_groups:
          description: An insight is delivered when it matches any of these groups.
          type: array
          items:
            $ref: '#/components/schemas/NotificationFilterGroup'
        email:
          type: object
          properties:
            email:
              type: string
          nullable: true
        slack:
          type: object
          properties:
            webhook_url:
              type: string
          nullable: true
        microsoftteams:
          type: object
          properties:
            webhook_url:
              type: string
          nullable: true
        jira:
          type: object
          properties:
            project_id:
              type: string
            issue_type:
              type: string
            trigger:
              type: string
          nullable: true
        servicenow:
          type: object
          properties:
            instance_url:
              type: string
            display_name:
              type: string
            caller_email:
              type: string
            trigger:
              type: string
          nullable: true
        pagerduty:
          type: object
          properties:
            service_id:
              type: string
            service_name:
              type: string
            trigger:
              type: string
          nullable: true
    NotificationFilterGroup:
      type: object
      properties:
        services:
          type: array
          items:
            type: string
        service_groups:
          type: array
          items:
            type: string
        sources:
          type: array
          items:
            type: string
        entities:
          type: array
          items:
            type: string
        severities:
          type: array
          items:
            type: string
    NotificationRecipientBody:
      required:
      - channel
      type: object
      properties:
        channel:
          type: string
          enum:
          - email
          - slack
          - microsoftteams
          - jira
          - servicenow
          - pagerduty
        title:
          type: string
        filter_groups:
          type: array
          items:
            $ref: '#/components/schemas/NotificationFilterGroup'
        email:
          description: Required for the `email` channel.
          type: string
        webhook_url:
          description: Required for the `slack` and `microsoftteams` channels.
          type: string
        project_id:
          description: Required for the `jira` channel.
          type: string
        board_id:
          type: string
        sprint_id:
          type: string
        issue_type:
          type: string
        service_id:
          description: Required for the `pagerduty` channel.
          type: string
        service_name:
          type: string
        trigger:
          description: '`manual` or `automatic`.'
          type: string
        sources:
          description: Legacy flat filter, folded into a single filter group on output.
          type: array
          items:
            type: string
        severities:
          description: Legacy flat filter.
          type: array
          items:
            type: string
        services:
          description: Legacy flat filter.
          type: array
          items:
            type: string
        service_groups:
          description: Legacy flat filter.
          type: array
          items:
            type: string
        entities:
          description: Legacy flat filter.
          type: array
          items:
            type: string
    SearchQueryBody:
      required:
      - q
      type: object
      properties:
        q:
          title: Q
          description: The LQL query, for example `SELECT * FROM source="demo-iis" WHERE level="error";`
          type: string
          minLength: 1
        times:
          title: Times
          description: |-
            Period to search. Defaults to the last 7 days. The bounds accept
            Elasticsearch date math (`now-1w/d`) as well as absolute timestamps.
          type: object
          properties:
            data:
              type: array
              items:
                type: object
                properties:
                  gte:
                    type: string
                  lte:
                    type: string
          example:
            data:
            - gte: now-1w/d
              lte: now/d
        indices:
          description: Sources to search. Defaults to every source the caller may read.
          type: array
          items:
            type: string
        limit:
          title: Limit
          description: Number of events to return; capped by the platform maximum page size.
          type: integer
        offset:
          title: Offset
          description: Number of events to skip.
          type: integer
        after:
          title: After
          description: Composite aggregation key to continue from.
          type: integer
        search_after:
          title: Search after
          description: Sort values of the last event of the previous page, for deep paging.
          type: array
          items:
            type: string
        timeline:
          title: Timeline
          description: Number of buckets the timeline should hold.
          type: integer
        timeline_field:
          title: Timeline field
          description: Field the timeline is broken down by.
          type: string
        timeline_interval:
          title: Timeline interval
          description: Bucket size of the timeline, for example `1h`.
          type: string
        is_aggs:
          title: Is aggs
          description: The query is an aggregation; return buckets instead of events.
          type: boolean
        ai_mode:
          title: AI mode
          description: Read `q` as a natural-language question and generate the query from it.
          type: boolean
        es_sql:
          title: ES SQL
          description: Run the query through Elasticsearch SQL.
          type: boolean
        display_query:
          title: Display query
          description: The query as it should be shown back to the user.
          type: string
        id:
          title: Visualization id
          description: Run the query on behalf of a saved visualization; results are cached under it.
          type: string
        update_vs_results:
          title: Update visualization results
          description: Recompute the cached results of the visualization.
          type: boolean
    SearchQueryResponse:
      type: object
      properties:
        events:
          description: The matching events, as returned by Elasticsearch.
          type: array
          items:
            type: object
        fields:
          description: The fields present on the events, with their aliases.
          type: object
        default_fields:
          description: Whether the answer falls back on the default field selection.
          type: boolean
        indices:
          description: Sources the query ran against.
          type: object
        data_source:
          description: The sources, services and entities the query resolved to.
          type: object
        query:
          description: The Elasticsearch query that was executed.
          type: object
        display_query:
          description: The query as it should be shown to the user; the generated one in AI mode.
          type: string
        aggs:
          description: Aggregation results, when the query asked for them.
          type: object
        is_aggs:
          type: boolean
        total:
          description: Number of matching events.
          type: integer
    QueryUpdateBody:
      required:
      - current_query
      type: object
      description: |-
        One rewrite of a query string. Exactly one of the operations is normally
        sent at a time.
      properties:
        current_query:
          title: Current query
          description: The query string to rewrite.
          type: string
        add_filter:
          description: 'Field and value to filter on, for example `{"level": "error"}`.'
          type: object
        remove_filter:
          description: Filter to drop from the query.
          type: object
        add_field:
          description: Field to add to the selection.
          type: string
        select_only_field:
          description: Narrow the selection down to this single field.
          type: string
        add_order_by:
          description: 'Field and direction to order by, for example `{"@timestamp": "desc"}`.'
          type: object
        remove_order_by:
          description: Order-by clause to drop.
          type: object
        negate:
          description: Negate the filter being added.
          type: boolean
    VisualizationQueryBody:
      required:
      - query
      type: object
      properties:
        query:
          description: The Elasticsearch query of the visualization.
          type: object
        q:
          description: The LQL query, when the visualization is driven by the query builder.
          type: string
        indices:
          type: array
          items:
            type: string
        limit:
          type: integer
        max_results:
          description: Maximum number of buckets to return.
          type: integer
        is_aggs:
          type: boolean
        from:
          type: integer
        after:
          description: Composite aggregation key to continue from.
          type: object
        prevs:
          description: Keys of the previous pages, so the chart can page backwards.
          type: object
        is_prev:
          type: boolean
        scroll:
          type: boolean
    CreatePattersBody:
      type: object
      description: Body of the pattern search.
      properties:
        query:
          title: Query
          description: The Elasticsearch query the patterns are collected from. Defaults to everything.
          type: object
        indices:
          description: Sources to search. Defaults to every source the caller may read.
          type: array
          items:
            type: string
        limit:
          title: Limit
          description: Number of patterns to return.
          type: integer
        after_key:
          title: After key
          description: Composite aggregation key to continue from.
          type: integer
        doc_count:
          title: Doc count
          description: Number of documents already counted, carried between pages.
          type: integer
        total_patterns:
          title: Total patterns
          description: Number of patterns already returned, carried between pages.
          type: integer
        order:
          title: Order
          description: '`asc` or `desc`. Defaults to `desc`.'
          type: string
        order_key:
          title: Order key
          description: Field to order on. Defaults to `last_occurrence`.
          type: string
    PlaceholdersBody:
      required:
      - indices
      - pattern_id
      - current_position
      type: object
      properties:
        indices:
          description: Sources the pattern occurs on.
          type: array
          items:
            type: string
        pattern_id:
          title: Pattern id
          type: string
        current_position:
          title: Current position
          description: Token position of the placeholder being expanded.
          type: integer
        previous_positions:
          title: Previous positions
          description: Placeholders already pinned, which narrow the values returned.
          type: array
          items:
            type: object
        left_constant:
          title: Left constant
          description: Text immediately to the left of the placeholder.
          type: string
        right_constant:
          title: Right constant
          description: Text immediately to the right of the placeholder.
          type: string
    RecentQuery:
      type: object
      properties:
        id:
          type: string
        query:
          type: string
        display_query:
          type: string
        times:
          type: object
        ai_mode:
          type: boolean
        check:
          type: boolean
        created_at:
          type: string
          example: Mar 12, 2026 09:00
    SavedQuery:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        query:
          type: string
        times:
          type: object
        vs:
          description: Visualizations saved alongside the query.
          type: object
        ai_mode:
          type: boolean
        is_default:
          description: Applied automatically when the search page opens.
          type: boolean
        last_run:
          type: string
        created_at:
          type: string
    SavedQueryBody:
      required:
      - title
      - query
      type: object
      properties:
        title:
          type: string
        query:
          type: string
        times:
          type: object
        vs:
          type: object
        ai_mode:
          type: boolean
        is_default:
          type: boolean
    Dashboard:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        status:
          type: boolean
        is_live:
          description: The dashboard refreshes itself continuously.
          type: boolean
        grid_layout:
          type: object
        roles:
          description: Roles that may open the dashboard.
          type: array
          items:
            type: string
        indices:
          description: Sources the dashboard reports on.
          type: array
          items:
            type: string
    Rule:
      type: object
      description: An alert rule.
      properties:
        id:
          type: string
        title:
          type: string
        desc:
          type: string
        query:
          description: The query the rule runs.
          type: string
        trigger_every:
          description: How often the rule runs, for example `15M`, `1H`, `1D`, or `Once`.
          type: string
        schedule_from:
          type: string
          format: date-time
        lookback_period:
          description: How far back each run looks.
          type: string
        condition:
          description: Above, Less than, Rised by, Drop by, Not equals.
          type: string
        threshold:
          type: integer
        severity:
          type: string
        notifications:
          type: array
          items:
            type: object
        is_active:
          type: boolean
        alerts:
          description: Number of alerts the rule has raised.
          type: integer
        created_by:
          type: string
        updated_by:
          type: string
        last_run:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    RuleBody:
      required:
      - title
      - query
      - trigger_every
      - condition
      - threshold
      - lookback_period
      - severity
      type: object
      properties:
        title:
          type: string
        desc:
          type: string
        query:
          type: string
        trigger_every:
          type: string
        schedule_from:
          type: string
          format: date-time
        lookback_period:
          type: string
        condition:
          type: string
        threshold:
          type: integer
        severity:
          type: string
        notifications:
          description: Channels the alert is delivered through.
          type: array
          items:
            type: object
        is_active:
          type: boolean
    Alert:
      type: object
      description: One firing of an alert rule.
      properties:
        id:
          type: string
        rule_id:
          type: string
        title:
          type: string
        severity:
          type: string
        sources:
          type: array
          items:
            type: string
        source_types:
          type: array
          items:
            type: string
        notifications:
          type: array
          items:
            type: object
        last_run:
          description: How long ago the alert fired.
          type: string
          example: 20 minutes ago
    BoardListingBody:
      type: object
      description: Body accepted by the hosts and sources listings of the boards page.
      properties:
        q:
          title: Q
          description: |-
            Free text. Matches a host name, a source or a tag. A tag can also be
            given as an object carrying its id.
          type: string
        from:
          title: From
          description: Zero-based page number.
          type: integer
        size:
          title: Size
          description: Page size. Defaults to 20.
          type: integer
        order:
          title: Order
          description: '`asc` or `desc`. Defaults to `desc`.'
          type: string
        order_by:
          title: Order by
          description: 'Field to sort on: `last_occurrence`, `count`, `status`.'
          type: string
        stats:
          title: Stats
          description: |-
            Identifiers of the hosts or sources whose event counts should be read from
            Elasticsearch. When present, the endpoint answers with those counts
            instead of the stored listing.
          type: array
          items:
            type: string
        times:
          title: Times
          description: Period the Elasticsearch counts are computed over.
          type: object
        indices:
          description: Sources to read the counts from.
          type: array
          items:
            type: string
    BoardListingResponse:
      type: object
      properties:
        result:
          type: array
          items:
            type: object
        total:
          type: integer
        total_page:
          type: integer
    Host:
      type: object
      properties:
        id:
          type: string
        host:
          type: string
        hostname:
          type: string
        index:
          description: Sources the host has been seen on.
          type: array
          items:
            type: string
        count:
          description: Number of events recorded for the host.
          type: integer
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        status:
          type: object
          properties:
            active:
              description: Traffic-light state of the host.
              type: string
            last_active:
              description: How long ago the host was last seen.
              type: string
        last_active:
          description: Last activity, in milliseconds.
          type: number
        last_update:
          type: string
          format: date-time
    BoardSource:
      type: object
      properties:
        id:
          type: string
        index:
          type: string
        host_count:
          type: integer
        count:
          type: integer
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        status:
          type: object
        last_active:
          type: number
        last_update:
          type: string
          format: date-time
    Tag:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        values:
          type: string
        host_count:
          type: integer
        source_count:
          type: integer
        event_count:
          type: integer
        hosts:
          type: array
          items:
            type: string
        sources:
          type: array
          items:
            type: string
        created_date:
          type: string
          format: date-time
    PaginatedDocuments:
      type: object
      description: The paginated envelope every listing of the components service answers with.
      properties:
        documents:
          description: The page of documents.
          type: array
          items:
            type: object
        total:
          description: Number of documents matching the request.
          type: integer
        page_count:
          description: Number of pages available.
          type: integer
    FilterPayload:
      type: object
      description: The grouping, search and sorting a components board is displayed with.
      properties:
        group_by:
          type: object
          properties:
            horizontal:
              type: string
            vertical:
              type: string
        search:
          description: Field conditions the documents have to satisfy.
          type: object
        time_filter:
          description: 'Activity window, for example `{"type": "Now"}`.'
          type: object
        order_by:
          type: string
        sort_order:
          description: '`1` ascending, `-1` descending.'
          type: integer
        keyword:
          type: string
    QueryValidateResponse:
      type: object
      properties:
        valid:
          type: boolean
        query:
          type: string
        ast:
          description: The parsed filter tree, when the query is valid.
          type: object
          nullable: true
        error:
          type: string
          nullable: true
        error_position:
          description: Character offset the parser stopped at.
          type: integer
          nullable: true
    Service:
      type: object
      description: A named slice of the log stream.
      properties:
        id:
          type: string
        service_name:
          type: string
        status:
          type: string
          enum:
          - Active
          - Draft
          - Archived
        service_class:
          type: string
          enum:
          - Network
          - Storage
          - Compute
          - Application
        service_origin:
          type: string
          enum:
          - CMDB
          - Dynamic
          - User-defined
        criticality:
          type: string
          enum:
          - high
          - medium
          - low
        indices:
          type: array
          items:
            type: string
        log_query_filter:
          description: Filter tree selecting the logs of the service.
          type: object
        alert_query_filter:
          description: Filter tree selecting the alerts of the service.
          type: object
        insight_log_query_filter:
          description: Extra log conditions applied for insight generation only.
          type: object
        insight_alert_query_filter:
          description: Extra alert conditions applied for insight generation only.
          type: object
        relationship_upstream:
          type: array
          items:
            type: string
        relationship_downstream:
          type: array
          items:
            type: string
        dynamic_filter_id:
          type: string
          nullable: true
        dynamic_filter_description:
          type: string
          nullable: true
        service_groups:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: object
        entities:
          type: array
          items:
            type: object
        entity_count:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ServiceBody:
      required:
      - service_name
      - service_class
      - service_origin
      - criticality
      type: object
      properties:
        service_name:
          type: string
          maxLength: 150
          minLength: 1
        status:
          type: string
          enum:
          - Active
          - Draft
          - Archived
        service_class:
          type: string
          enum:
          - Network
          - Storage
          - Compute
          - Application
        service_origin:
          type: string
          enum:
          - CMDB
          - Dynamic
          - User-defined
        criticality:
          type: string
          enum:
          - high
          - medium
          - low
        indices:
          type: array
          items:
            type: string
        log_query_filter:
          type: object
        alert_query_filter:
          type: object
        insight_log_query_filter:
          type: object
        insight_alert_query_filter:
          type: object
        relationship_upstream:
          type: array
          items:
            type: string
        relationship_downstream:
          type: array
          items:
            type: string
        dynamic_filter_id:
          type: string
        tags:
          type: array
          items:
            type: string
        entities:
          type: array
          items:
            type: string
    ServiceGroup:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
          - Active
          - Draft
          - Archived
        criticality:
          type: string
          enum:
          - high
          - medium
          - low
        assigned_services:
          type: array
          items:
            type: object
        dynamic_filter_ids:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: object
        service_count:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ServiceGroupBody:
      required:
      - name
      - criticality
      type: object
      properties:
        name:
          type: string
          maxLength: 150
          minLength: 2
        description:
          type: string
          maxLength: 150
        status:
          type: string
        criticality:
          type: string
        assigned_services:
          type: array
          items:
            type: string
        dynamic_filter_ids:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
    Entity:
      type: object
      description: A host, device, node, endpoint or user discovered in the logs.
      properties:
        id:
          type: string
        entity_name:
          type: string
        entity_class:
          type: string
          enum:
          - host
          - device
          - node
          - endpoint
          - user
        entity_field:
          description: Field of the source the name was read from.
          type: string
        index_name:
          type: string
        source_name:
          type: string
        total_events:
          type: integer
        service_ids:
          type: array
          items:
            type: string
        service_count:
          type: integer
        tags:
          type: array
          items:
            type: string
        last_tracked_activity:
          type: string
          format: date-time
        activity_status:
          type: string
    ComponentSource:
      type: object
      description: A source of the components service.
      properties:
        id:
          type: string
        index_name:
          type: string
        source_type:
          type: string
        collector_type:
          type: string
        timezone:
          type: string
        entity_class:
          type: string
        entity_field:
          description: Field a host or device name is read from. Defaults to `hostname`.
          type: string
        entity_count:
          type: integer
        total_events:
          type: integer
        topic_name:
          description: Kafka topic the raw logs arrive on.
          type: string
        pipeline_id:
          type: string
          nullable: true
        pipeline_name:
          type: string
          nullable: true
        last_tracked_activity:
          type: string
          format: date-time
        is_deleted:
          type: boolean
    SourceBody:
      required:
      - source_name
      - source_type
      - topic_name
      type: object
      properties:
        source_name:
          type: string
          maxLength: 200
          minLength: 1
        source_type:
          type: string
        collector_type:
          type: string
        topic_name:
          description: Kafka topic to map to this source.
          type: string
        entity_class:
          type: string
        entity_field:
          type: string
        timezone:
          type: string
        pipeline_id:
          type: string
    ComponentTag:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        value:
          type: string
        entities:
          type: array
          items:
            type: string
        services:
          type: array
          items:
            type: string
        service_groups:
          type: array
          items:
            type: string
        entity_count:
          type: integer
        service_count:
          type: integer
        service_group_count:
          type: integer
        event_count:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    DynamicFilterBody:
      required:
      - index
      - index_type
      - field_name
      type: object
      description: |-
        A rule that generates and maintains services automatically, one per value
        found in `field_name` on `index`.
      properties:
        description:
          type: string
        index:
          type: string
          maxLength: 150
          minLength: 1
        index_type:
          description: Whether the filter reads logs or alerts.
          type: string
        field_name:
          type: string
          maxLength: 150
          minLength: 1
        field_values:
          description: Restrict generation to these values.
          type: array
          items:
            type: string
        values_per_service:
          description: Service name mapped to the values it should cover.
          type: object
        query_filter:
          description: Filter tree applied on top of the field condition.
          type: object
        insight_query_filter:
          description: Extra conditions applied for insight generation only.
          type: object
        prefix:
          description: Prepended to every generated service name.
          type: string
        suffix:
          description: Appended to every generated service name.
          type: string
        match_pattern:
          description: Pattern the field value has to match to produce a service.
          type: string
        service_name_mappings:
          description: Explicit renames, as `origin_name` to `new_name`.
          type: array
          items:
            type: object
            properties:
              origin_name:
                type: string
              new_name:
                type: string
        status:
          type: string
        service_class:
          type: string
        relationship_upstream:
          type: array
          items:
            type: string
        relationship_downstream:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
    PipelineBody:
      required:
      - name
      - steps
      type: object
      properties:
        name:
          type: string
          maxLength: 200
          minLength: 1
        description:
          type: string
          maxLength: 1000
        steps:
          description: The ordered steps a log line goes through.
          type: array
          items:
            type: object
            properties:
              function:
                type: string
              params:
                type: object
        on_error:
          description: What to do when a step fails. Defaults to `skip`.
          type: string
          enum:
          - raise
          - skip
          - drop
        sources:
          description: Sources the pipeline is attached to, by name or as a reference.
          type: array
          items:
            type: string
        is_default:
          description: Use this pipeline for sources that have none of their own.
          type: boolean
    PipelinePreviewResponse:
      type: object
      properties:
        success_results:
          type: array
          items:
            $ref: '#/components/schemas/PipelinePreviewResult'
        failed_results:
          type: array
          items:
            $ref: '#/components/schemas/PipelinePreviewResult'
        success_count:
          type: integer
        error_count:
          type: integer
        dropped_count:
          type: integer
    PipelinePreviewResult:
      type: object
      properties:
        output:
          description: The document the line turned into.
          type: object
          nullable: true
        success:
          type: boolean
        dropped:
          description: The line was dropped on purpose by a step.
          type: boolean
        errors:
          type: array
          items:
            type: string
    ChatbotInput:
      required:
      - message
      type: object
      properties:
        message:
          title: Message
          description: The question to put to the assistant, in plain language.
          type: string
          minLength: 1
    PromptResponse:
      required:
      - answer
      type: object
      properties:
        answer:
          title: Answer
          description: The assistant's answer, as text.
          type: string
    ChatHistory:
      required:
      - role
      - content
      type: object
      properties:
        role:
          title: Role
          description: Who spoke — the user, or the assistant.
          type: string
          enum:
          - human
          - ai
        content:
          title: Content
          type: string
  responses:
    ActivityForbidden:
      description: The caller is authenticated but lacks the right this action requires
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ActivityError'
          example:
            message: You don't have permission to perform this action.
    BadRequest:
      description: Error happened processing request
      content:
        application/json:
          schema:
            title: response
            type: object
            properties:
              message:
                title: Message
                description: Error reason
                type: string
                minLength: 1
              mail:
                title: Mail
                description: Email errors
                type: array
                items:
                  type: string
              password:
                title: Password
                description: Password errors
                type: array
                items:
                  type: string
          example:
            message: Invalid data
            mail:
            - Invalid data
            password:
            - Invalid data
    Unauthorized:
      description: Authorized to access resource
      content:
        application/json:
          schema:
            title: response
            required:
            - message
            type: object
            properties:
              message:
                title: Message
                description: Denial reason
                type: string
          examples:
            Invalid Token:
              value:
                message: The access token is invalid or has expired.
            Missing Credentials:
              value:
                message: Authentication credentials were not provided.
    Forbidden:
      description: The caller is authenticated but lacks the right this action requires
      content:
        application/json:
          schema:
            title: response
            type: object
            properties:
              detail:
                title: Detail
                description: Which permission is missing
                type: string
          example:
            detail: You do not have permission to perform this action.
    NotFound:
      description: No resource with this identifier
      content:
        application/json:
          schema:
            title: response
            type: object
            properties:
              detail:
                title: Detail
                type: string
          example:
            detail: Not found.
    ValidationError:
      description: The request body did not pass validation
      content:
        application/json:
          schema:
            title: response
            type: object
            properties:
              detail:
                title: Detail
                description: One entry per field that failed, with its location and reason
                type: array
                items:
                  type: object
                  properties:
                    loc:
                      type: array
                      items:
                        type: string
                    msg:
                      type: string
                    type:
                      type: string
          example:
            detail:
            - loc:
              - body
              - service_name
              msg: Field required
              type: missing
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'The access token returned by `POST /api/account/login/`, sent as `Authorization: Bearer
        <access>`.'
