openapi.yaml

openapi: 3.1.0
info:
  title: Uptrace JSON API
  version: "1.0.0"
  description: |
    REST API for managing Uptrace resources including monitors and dashboards.
    This API allows you to create, update, retrieve, and delete monitors and dashboards programmatically.

    ## Authentication

    To use the API, you need a project ID (`<project_id>`) and a user authentication token (`<user_token>`).

    You can create an authentication token on your user profile page. The token has the same permissions as the user account, allowing access to the same resources.

    ### SSO

    User auth tokens do not work with Single Sign-On (SSO) because SSO requires Uptrace to redirect users to the SSO provider, which is not viable for the JSON API.

    If your organization uses SSO, you need to create a separate user account and statically grant it access to projects without relying on SSO authentication.

    ## Usage Limits

    Uptrace Cloud provides this API free of charge for occasional use to read small fractions of ingested data. For example, a few requests per hour to read data from the last few hours is acceptable.

    If you need higher usage limits, please contact [support](mailto:support@uptrace.dev) to discuss your use case.
  contact:
    name: Uptrace
    url: https://uptrace.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.uptrace.dev
    description: Public API server
security:
  - bearerAuth: []
  - authTokenQuery: []

paths:
  /api/v1/annotations:
    post:
      summary: Create annotation
      operationId: create_annotation
      description: Create a chart annotation.
      tags: [Annotations]
      security:
        - uptraceDSNHeader: []
        - dsnQuery: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnnotationCreateRequest"
            example:
              name: Deployed to production
              fingerprint: v1.2.3
              attrs:
                service.version: v1.2.3
      responses:
        "200":
          description: Annotation created.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"
  /api/v1/tracing/{project_id}/spans:
    get:
      summary: List spans
      x-badges:
        - name: global
      operationId: public_list_spans
      description: >-
        List spans (public API). Stable API for listing spans by trace_id, span_id, or parent_id.
        Best for retrieving known spans when you already have an ID.
        For advanced filtering with UQL queries (WHERE, search, system filtering),
        use list_spans instead.
        Documentation: https://uptrace.dev/features/querying/spans
      tags: [Querying]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/TimeStart"
        - $ref: "#/components/parameters/TimeEnd"
        - name: trace_id
          in: query
          description: Filter spans by trace ID.
          schema:
            type: string
          example: 17706d68ea23cf9bc8976ca57d22ee31
        - name: id
          in: query
          description: Filter spans by span ID.
          schema:
            type: integer
          example: 12345
        - name: parent_id
          in: query
          description: Filter spans by parent span ID.
          schema:
            type: integer
          example: 12345
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: List of spans.
          content:
            application/json:
              schema:
                type: object
                properties:
                  spans:
                    type: array
                    description: Array of span objects.
                    items:
                      $ref: "#/components/schemas/Span"
                  hasMore:
                    type: boolean
                    description: Whether more results exist beyond the limit.
                required: [spans]
              example:
                spans:
                  - id: "acb4d95e58413013"
                    traceId: "17706d68ea23cf9bc8976ca57d22ee31"
                    parentId: ""
                    name: GET /api/v1/orders
                    kind: server
                    time: 1688947201000.0
                    duration: 1.2
                    statusCode: ok
                hasMore: false
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"
  /api/v1/tracing/{project_id}/groups:
    get:
      summary: List groups
      x-badges:
        - name: global
      operationId: public_list_span_groups
      description: >-
        List span groups (public API). Stable API for listing aggregated span groups.
        Supports basic search and duration filtering.
        For advanced aggregation with UQL queries (GROUP BY, HAVING, aggregate functions),
        use list_span_groups instead.
        Documentation: https://uptrace.dev/features/querying/spans
      tags: [Querying]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/TimeStart"
        - $ref: "#/components/parameters/TimeEnd"
        - name: query
          in: query
          description: Aggregate spans using the specified query.
          schema:
            type: string
          example: group by host_name
        - $ref: "#/components/parameters/Limit"
        - name: search
          in: query
          description: Search for spans containing option1 or option2.
          schema:
            type: string
          example: option1|option2
        - name: duration_gte
          in: query
          description: Duration greater than or equal to N (milliseconds).
          schema:
            type: integer
            format: int64
          example: 1000
        - name: duration_lt
          in: query
          description: Duration less than N (milliseconds).
          schema:
            type: integer
            format: int64
          example: 5000
      responses:
        "200":
          description: Aggregated spans.
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    description: Array of group rows with dynamic columns based on the query.
                    items:
                      type: object
                      additionalProperties: true
                  hasMore:
                    type: boolean
                    description: Whether more results exist beyond the limit.
                required: [groups]
              example:
                groups:
                  - host_name: host-1
                    count: 1240
                    errorCount: 12
                    p50: 850
                    p95: 2400
                hasMore: false
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/tracing/{project_id}/spans:
    get:
      summary: List spans
      operationId: list_spans
      description: >-
        List individual spans using UQL (Uptrace Query Language).
        Use this to inspect specific span details, search for errors, or browse recent operations.
        Supports WHERE filters (e.g. where service_name = 'myservice', where _status_code = 'error',
        where _dur_ms > 100ms), full-text search (e.g. word1|word2 -excluded),
        system filtering (e.g. httpserver:all, db:postgresql, log:error),
        duration filtering in milliseconds, and sorting by any span field.
        Span fields use underscore prefix: _name, _dur_ms, _status_code, _time, _trace_id, _kind.
        Attributes use dot-to-underscore: service.name becomes service_name.
        Returns individual span objects with attrs, timing, and status.
        Use list_span_groups instead when you need aggregated metrics (count, avg, p99).
        Use list_traces instead when you need to find traces matching multi-span criteria.
        Documentation: https://uptrace.dev/features/querying/spans
      tags: [Querying]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/TimeStart"
        - $ref: "#/components/parameters/TimeEnd"
        - name: query
          in: query
          description: UQL query to filter spans (e.g., where service_name = 'myservice').
          schema:
            type: string
          example: "where service_name = 'myservice'"
        - name: where
          in: query
          description: Additional WHERE clause appended to the query.
          schema:
            type: string
          example: "service_name = 'myservice'"
        - name: search
          in: query
          description: Full-text search for spans containing the given text.
          schema:
            type: string
          example: "GET /api"
        - name: search_attrs
          in: query
          description: Attribute names to search within when using search. Can be repeated for multiple attributes.
          schema:
            type: array
            items:
              type: string
          example: ["display_name"]
        - name: system
          in: query
          description: Filter by system (e.g., log:error, db:postgresql). Can be repeated for multiple systems.
          schema:
            type: array
            items:
              type: string
          example: ["log:error"]
        - name: sort_by
          in: query
          description: Column names to sort by. Can be repeated for multi-column sort. Defaults to time.
          schema:
            type: array
            items:
              type: string
          example: ["_time"]
        - name: sort_dir
          in: query
          description: Sort direction for each sort_by column. Must match sort_by count. Defaults to DESC.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SortDirection'
          example: ["DESC"]
        - name: duration_gte
          in: query
          description: Duration greater than or equal to N (milliseconds).
          schema:
            type: integer
            format: int64
          example: 1000
        - name: duration_lt
          in: query
          description: Duration less than N (milliseconds).
          schema:
            type: integer
            format: int64
          example: 5000
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: List of matching spans.
          content:
            application/json:
              schema:
                type: object
                properties:
                  spans:
                    type: array
                    description: Array of span objects.
                    items:
                      $ref: "#/components/schemas/Span"
                  count:
                    type: integer
                    format: int64
                    description: Total count of matching spans.
                  query:
                    type: array
                    description: Parsed query parts with error state.
                    items:
                      type: object
                      additionalProperties: true
                  sorting:
                    type: array
                    description: Applied sorting configuration.
                    items:
                      $ref: '#/components/schemas/OrderItem'
                  search:
                    type: array
                    description: Applied search matchers.
                    items:
                      type: object
                      additionalProperties: true
                  whereAttrs:
                    type: object
                    description: Map of WHERE attribute names to their matched values.
                    additionalProperties: true
                required: [spans, count]
              example:
                spans:
                  - id: "acb4d95e58413013"
                    traceId: "07f3834da9d146dd4d6aea67fe5b1e95"
                    parentId: "6a1445d6b82b6c5d"
                    name: GET /api/v1/orders
                    kind: server
                    time: 1770985573458.9
                    duration: 1.2
                    statusCode: ok
                count: 1
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/tracing/{project_id}/groups:
    get:
      summary: List groups
      operationId: list_span_groups
      description: >-
        Aggregate spans into groups using UQL queries.
        Use this to get aggregated metrics like request count, error rate, or latency percentiles.
        Aggregate functions: count(), avg(), sum(), min(), max(),
        p50(), p75(), p90(), p99(), uniq(), apdex().
        Supports GROUP BY (e.g. group by service_name), HAVING (e.g. having p50(_dur_ms) > 100ms),
        WHERE filters, full-text search, system filtering (e.g. httpserver:all, db:postgresql),
        and duration filtering. Example query: 'perMin(count()) | group by host_name'.
        Returns grouped rows with dynamic columns based on the query.
        Use list_spans instead when you need individual span details.
        Use timeseries instead when you need time-bucketed data for charts.
        Documentation: https://uptrace.dev/features/querying/spans
      tags: [Querying]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/TimeStart"
        - $ref: "#/components/parameters/TimeEnd"
        - name: query
          in: query
          description: UQL aggregation query (e.g., perMin(count()) | group by host_name).
          schema:
            type: string
          example: "perMin(count()) | group by host_name"
        - name: where
          in: query
          description: Additional WHERE clause appended to the query.
          schema:
            type: string
          example: "service_name = 'myservice'"
        - name: search
          in: query
          description: Full-text search for spans containing the given text.
          schema:
            type: string
          example: "GET /api"
        - name: search_attrs
          in: query
          description: Attribute names to search within when using search. Can be repeated for multiple attributes.
          schema:
            type: array
            items:
              type: string
          example: ["display_name"]
        - name: system
          in: query
          description: Filter by system (e.g., log:error, db:postgresql). Can be repeated for multiple systems.
          schema:
            type: array
            items:
              type: string
          example: ["spans:all"]
        - name: sort_by
          in: query
          description: Column names to sort by. Can be repeated for multi-column sort.
          schema:
            type: array
            items:
              type: string
          example: ["count"]
        - name: sort_dir
          in: query
          description: Sort direction for each sort_by column. Must match sort_by count. Defaults to DESC.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SortDirection'
          example: ["DESC"]
        - name: duration_gte
          in: query
          description: Duration greater than or equal to N (milliseconds).
          schema:
            type: integer
            format: int64
          example: 1000
        - name: duration_lt
          in: query
          description: Duration less than N (milliseconds).
          schema:
            type: integer
            format: int64
          example: 5000
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Aggregated span groups.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GroupsResult"
              example:
                groups:
                  - host_name: host-1
                    count: 1240
                    errorCount: 12
                    p50: 850
                    p95: 2400
                columns:
                  - name: count
                    isNum: true
                hasMore: false
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/tracing/{project_id}/timeseries:
    get:
      summary: Timeseries
      operationId: query_timeseries
      description: >-
        Query time-bucketed aggregation data for spans.
        Use this to analyze trends over time, detect anomalies, or build charts.
        Returns aligned timestamps with auto-computed interval based on the time range.
        Use UQL aggregation query (e.g. perMin(count()) | group by service_name)
        with aggregate functions: count(), avg(), sum(), p50(), p90(), p99(), etc.
        Use column parameter to select specific aggregate columns for the timeseries.
        Supports WHERE filters, full-text search, system filtering, and duration filtering.
        Returns groups with arrays of float values aligned with the time array.
        Use list_span_groups instead when you need a single aggregated snapshot (not time-bucketed).
        Use quantiles instead when you only need latency percentiles (p50/p90/p99).
        Documentation: https://uptrace.dev/features/querying/spans
      tags: [Querying]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/TimeStart"
        - $ref: "#/components/parameters/TimeEnd"
        - name: query
          in: query
          description: UQL aggregation query (e.g., perMin(count()) | group by service_name).
          schema:
            type: string
          example: "perMin(count()) | group by service_name"
        - name: where
          in: query
          description: Additional WHERE clause appended to the query.
          schema:
            type: string
          example: "service_name = 'myservice'"
        - name: search
          in: query
          description: Full-text search for spans containing the given text.
          schema:
            type: string
          example: "GET /api"
        - name: search_attrs
          in: query
          description: Attribute names to search within when using search. Can be repeated for multiple attributes.
          schema:
            type: array
            items:
              type: string
          example: ["display_name"]
        - name: system
          in: query
          description: Filter by system (e.g., log:error, db:postgresql). Can be repeated for multiple systems.
          schema:
            type: array
            items:
              type: string
          example: ["spans:all"]
        - name: column
          in: query
          description: Aggregate column names to include in the timeseries. Can be repeated for multiple columns.
          schema:
            type: array
            items:
              type: string
          example: ["count"]
        - name: duration_gte
          in: query
          description: Duration greater than or equal to N (milliseconds).
          schema:
            type: integer
            format: int64
          example: 10000
        - name: duration_lt
          in: query
          description: Duration less than N (milliseconds).
          schema:
            type: integer
            format: int64
          example: 100000
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Timeseries data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    description: Array of group rows. Aggregated columns contain arrays of float values aligned with the time array.
                    items:
                      type: object
                      additionalProperties: true
                  columns:
                    type: array
                    description: Column definitions for the result.
                    items:
                      $ref: "#/components/schemas/QueryColumn"
                  time:
                    type: array
                    description: Array of aligned timestamps as unix milliseconds.
                    items:
                      type: number
                      format: double
                  interval:
                    type: integer
                    format: int64
                    description: Time interval between data points in milliseconds.
                  query:
                    type: array
                    description: Parsed query parts with error state.
                    items:
                      type: object
                      additionalProperties: true
                  sorting:
                    type: array
                    description: Applied sorting configuration.
                    items:
                      $ref: '#/components/schemas/OrderItem'
                  whereAttrs:
                    type: object
                    description: Map of WHERE attribute names to their matched values.
                    additionalProperties: true
                required: [groups, time, interval]
              example:
                groups:
                  - service_name: myservice
                    "perMin(count())": [10.5, 20.3, 15.1, 30.7]
                time: [1688947200000, 1688947260000, 1688947320000, 1688947380000]
                interval: 60000
                columns:
                  - expr: "perMin(count())"
                    name: "perMin(count())"
                    isAgg: true
                    isNum: true
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/tracing/{project_id}/quantiles:
    get:
      summary: Quantiles
      operationId: query_quantiles
      description: >-
        Query duration percentiles (p50, p90, p99) and count/error rate over time.
        Use this to identify latency outliers, track performance degradation, or compare SLO compliance.
        Returns named timeseries: count, countPerMin, errorCount, errorCountPerMin,
        durationP50, durationP90, durationP99, durationMax.
        Supports WHERE filters (e.g. where service_name = 'myservice'),
        full-text search, system filtering (e.g. httpserver:all), and duration filtering.
        Use timeseries instead when you need custom aggregation queries with GROUP BY.
        Use list_span_groups instead when you need a single aggregated snapshot.
        Documentation: https://uptrace.dev/features/querying/spans
      tags: [Querying]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/TimeStart"
        - $ref: "#/components/parameters/TimeEnd"
        - name: query
          in: query
          description: UQL query to filter spans (e.g., where service_name = 'myservice').
          schema:
            type: string
          example: "where service_name = 'myservice'"
        - name: where
          in: query
          description: Additional WHERE clause appended to the query.
          schema:
            type: string
          example: "service_name = 'myservice'"
        - name: search
          in: query
          description: Full-text search for spans containing the given text.
          schema:
            type: string
          example: "GET /api"
        - name: search_attrs
          in: query
          description: Attribute names to search within when using search. Can be repeated for multiple attributes.
          schema:
            type: array
            items:
              type: string
          example: ["display_name"]
        - name: system
          in: query
          description: Filter by system (e.g., log:error, db:postgresql). Can be repeated for multiple systems.
          schema:
            type: array
            items:
              type: string
          example: ["spans:all"]
        - name: duration_gte
          in: query
          description: Duration greater than or equal to N (milliseconds).
          schema:
            type: integer
            format: int64
          example: 10000
        - name: duration_lt
          in: query
          description: Duration less than N (milliseconds).
          schema:
            type: integer
            format: int64
          example: 100000
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Quantile timeseries data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  timeseries:
                    type: array
                    description: >-
                      Array of named timeseries. Names include: count, countPerMin, errorCount, errorCountPerMin,
                      durationP50, durationP90, durationP99, durationMax.
                    items:
                      $ref: "#/components/schemas/Timeseries"
                required: [timeseries]
              example:
                timeseries:
                  - name: durationP50
                    value: [1.2, 1.3, 1.1]
                    time: [1688947200000, 1688947260000, 1688947320000]
                  - name: countPerMin
                    value: [100, 120, 90]
                    time: [1688947200000, 1688947260000, 1688947320000]
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/tracing/{project_id}/trace-groups:
    get:
      summary: List trace groups
      operationId: list_trace_groups
      description: >-
        Aggregate traces into groups using correlated sub-queries.
        Use this to find trace patterns and get aggregated trace metrics.
        Requires parallel arrays: query[], alias[], system[] with matching lengths.
        One alias must be 'root' to identify the root span query.
        Additional sub-queries filter traces where child spans match specific criteria.
        Systems: spans:all, httpserver:all, db:postgresql, log:error, etc.
        Returns grouped rows with dynamic columns.
        Use list_traces instead when you need individual trace details.
        Use list_span_groups instead when you don't need cross-span trace correlation.
        Documentation: https://uptrace.dev/features/querying/spans
      tags: [Querying]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/TimeStart"
        - $ref: "#/components/parameters/TimeEnd"
        - name: query
          in: query
          description: UQL query for each sub-query. Must have the same count as alias and system. Can be repeated.
          schema:
            type: array
            items:
              type: string
          example: ["where service_name = 'myservice'"]
        - name: alias
          in: query
          description: Alias for each sub-query. One alias must be 'root'. Can be repeated.
          schema:
            type: array
            items:
              type: string
          example: ["root"]
        - name: system
          in: query
          description: System for each sub-query (e.g., spans:all, log:error). Can be repeated.
          schema:
            type: array
            items:
              type: string
          example: ["spans:all"]
        - name: sort_by
          in: query
          description: Column names to sort by. Can be repeated for multi-column sort.
          schema:
            type: array
            items:
              type: string
          example: ["count"]
        - name: sort_dir
          in: query
          description: Sort direction for each sort_by column. Must match sort_by count. Defaults to DESC.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SortDirection'
          example: ["DESC"]
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Trace groups result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GroupsResult"
              example:
                groups:
                  - _group_id: "100"
                    count: 42
                    errorCount: 2
                columns:
                  - name: count
                    isNum: true
                hasMore: false
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/tracing/{project_id}/traces:
    get:
      summary: List traces
      operationId: list_traces
      description: >-
        List individual traces using correlated sub-queries.
        Use this to find specific traces matching complex multi-span criteria.
        Requires parallel arrays: query[], alias[], system[] with matching lengths.
        One alias must be 'root' to identify the root span query.
        Additional sub-queries filter traces where child spans match specific criteria.
        Systems: spans:all, httpserver:all, db:postgresql, log:error, etc.
        Returns root spans for matching traces sorted by time (DESC by default).
        Use list_trace_groups instead when you need aggregated trace metrics.
        Use list_spans instead when you don't need cross-span trace correlation.
        Documentation: https://uptrace.dev/features/querying/spans
      tags: [Querying]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/TimeStart"
        - $ref: "#/components/parameters/TimeEnd"
        - name: query
          in: query
          description: UQL query for each sub-query. Must have the same count as alias and system. Can be repeated.
          schema:
            type: array
            items:
              type: string
          example: ["where service_name = 'myservice'"]
        - name: alias
          in: query
          description: Alias for each sub-query. One alias must be 'root'. Can be repeated.
          schema:
            type: array
            items:
              type: string
          example: ["root"]
        - name: system
          in: query
          description: System for each sub-query (e.g., spans:all, log:error). Can be repeated.
          schema:
            type: array
            items:
              type: string
          example: ["spans:all"]
        - name: sort_by
          in: query
          description: Column names to sort by. Can be repeated for multi-column sort. Defaults to time.
          schema:
            type: array
            items:
              type: string
          example: ["_time"]
        - name: sort_dir
          in: query
          description: Sort direction for each sort_by column. Must match sort_by count. Defaults to DESC.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SortDirection'
          example: ["DESC"]
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: List of matching traces.
          content:
            application/json:
              schema:
                type: object
                properties:
                  spans:
                    type: array
                    description: Root spans for matching traces.
                    items:
                      $ref: "#/components/schemas/Span"
                  count:
                    type: integer
                    format: int64
                    description: Total count of matching traces.
                  query:
                    type: array
                    description: Parsed query parts with error state.
                    items:
                      type: object
                      additionalProperties: true
                  sorting:
                    type: array
                    description: Applied sorting configuration.
                    items:
                      $ref: '#/components/schemas/OrderItem'
                  search:
                    type: array
                    description: Applied search matchers.
                    items:
                      type: object
                      additionalProperties: true
                  whereAttrs:
                    type: object
                    description: Map of WHERE attribute names to their matched values.
                    additionalProperties: true
                required: [spans, count]
              example:
                spans:
                  - id: "298ec3d46392d4b7"
                    traceId: "103ba7cd7900cdf2b04e842e15ad9702"
                    name: GET /api/v1/orders
                    displayName: GET /api/v1/orders
                    time: 1770985602526.471
                    duration: 1.634
                    statusCode: ok
                count: 1
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/fixtures:
    put:
      summary: Sync fixtures
      operationId: sync_fixtures
      description:
        Create, update, or delete users, orgs, projects, and related resources
        using fixture keys.
      tags: [Fixtures]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SeedDataRequest"
            example:
              users:
                - key: admin_user
                  name: System Administrator
                  email: admin@company.com
                  password: change_me_immediately
              orgs:
                - key: main_org
                  name: Acme Corporation
              orgUsers:
                - key: admin_membership
                  orgKey: main_org
                  userKey: admin_user
                  role: owner
              projects:
                - key: web_app_project
                  name: Web Application
                  orgKey: main_org
      responses:
        "200":
          description: Fixtures applied successfully.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/fixtures/bindings:
    put:
      summary: Bind existing resources to fixture keys
      operationId: bind_fixture_keys
      description: Assign fixture keys to existing resources created outside of fixtures.
      tags: [Fixtures]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LinkDataRequest"
            example:
              orgs:
                - id: 123
                  key: legacy_org
              projects:
                - id: 456
                  key: existing_project
      responses:
        "200":
          description: Bindings applied successfully.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/projects/{project_id}/monitors:
    get:
      summary: List monitors
      x-badges:
        - name: beta
      operationId: list_monitors
      description: >-
        List monitoring rules and alerts configured in Uptrace.
        Use this to review alert configurations, check notification channels,
        and understand monitoring thresholds.
        Returns monitors with their type, state, query, and notification settings.
        Use list_dashboards instead when looking for visualization dashboards.
        Documentation: https://uptrace.dev/features/alerting
      tags: [Monitors]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: List of monitors.
          content:
            application/json:
              schema:
                type: object
                required:
                  - monitors
                properties:
                  monitors:
                    type: array
                    items:
                      $ref: "#/components/schemas/Monitor"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      summary: Create a monitor
      x-badges:
        - name: beta
      operationId: create_monitor
      description: Create a metric or error monitor.
      tags: [Monitors]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/MetricMonitorRequest"
                - $ref: "#/components/schemas/ErrorMonitorRequest"
            examples:
              metricMonitor:
                summary: Metric monitor
                value:
                  name: Number of spans per minute
                  type: metric
                  notifyEveryoneByEmail: true
                  teamIds: [123]
                  channelIds: [123]
                  repeatInterval:
                    strategy: default
                  params:
                    metrics:
                      - name: uptrace_tracing_spans
                        alias: $spans
                    query:
                      "perMin(count($spans)) as spans | where service_name =
                      'myservice'"
                    columnName: spans
                    minAllowedValue: 100
                    maxAllowedValue: 1000
                    nullsMode: convert
              errorMonitor:
                summary: Error monitor
                value:
                  name: Number of spans per minute
                  type: error
                  notifyEveryoneByEmail: true
                  teamIds: [123]
                  channelIds: [123]
                  repeatInterval:
                    strategy: default
                  params:
                    metrics:
                      - name: uptrace_tracing_logs
                        alias: $logs
                    query: "group by _group_id | where _system in ('log:error', 'log:fatal')"
      responses:
        "200":
          description: Monitor created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MonitorResponse"
              example:
                monitor:
                  id: 3807
                  name: Number of spans per minute
                  type: metric
                  status: active
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"
  /internal/v1/projects/{project_id}/monitors/{monitor_id}:
    get:
      summary: Get a monitor
      x-badges:
        - name: beta
      operationId: get_monitor
      description: Retrieve a specific monitor by ID.
      tags: [Monitors]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/MonitorId"
      responses:
        "200":
          description: Monitor details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MonitorResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      summary: Update a monitor
      x-badges:
        - name: beta
      operationId: update_monitor
      description: Update a metric or error monitor by ID.
      tags: [Monitors]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/MonitorId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/MetricMonitorRequest"
                - $ref: "#/components/schemas/ErrorMonitorRequest"
            examples:
              metricMonitor:
                summary: Metric monitor
                value:
                  name: Number of spans per minute
                  type: metric
                  notifyEveryoneByEmail: true
                  teamIds: [123]
                  channelIds: [123]
                  repeatInterval:
                    strategy: default
                  params:
                    metrics:
                      - name: uptrace_tracing_spans
                        alias: $spans
                    query:
                      "perMin(count($spans)) as spans | where service_name =
                      'myservice'"
                    columnName: spans
                    minAllowedValue: 100
                    maxAllowedValue: 1000
                    nullsMode: convert
              errorMonitor:
                summary: Error monitor
                value:
                  name: Number of spans per minute
                  type: error
                  notifyEveryoneByEmail: true
                  teamIds: [123]
                  channelIds: [123]
                  repeatInterval:
                    strategy: default
                  params:
                    metrics:
                      - name: uptrace_tracing_logs
                        alias: $logs
                    query: "group by _group_id | where _system in ('log:error', 'log:fatal')"
      responses:
        "200":
          description: Monitor updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MonitorResponse"
              example:
                monitor:
                  id: 3807
                  name: Number of spans per minute
                  type: metric
                  status: active
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      summary: Delete a monitor
      x-badges:
        - name: beta
      operationId: delete_monitor
      description: Delete a metric or error monitor by ID.
      tags: [Monitors]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/MonitorId"
      responses:
        "200":
          description: Monitor deleted.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}:
    get:
      summary: List dashboards
      x-badges:
        - name: beta
      operationId: list_dashboards
      description: >-
        List dashboards configured in Uptrace.
        Use this to browse available dashboards for monitoring and visualization.
        Returns dashboard summaries with ID, name, and tags.
        Use get_dashboard with a specific ID to retrieve full dashboard details including grid rows and items.
        Use create_dashboard to create a new dashboard from YAML.
        Documentation: https://uptrace.dev/features/dashboards
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: List of dashboards.
          content:
            application/json:
              schema:
                type: object
                required:
                  - dashboards
                properties:
                  dashboards:
                    type: array
                    items:
                      $ref: "#/components/schemas/Dashboard"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}/tags:
    get:
      summary: List dashboard tags
      x-badges:
        - name: beta
      operationId: list_dashboard_tags
      description: >-
        List all available dashboard tags for a project.
        Tags are simple string labels used for categorizing and filtering dashboards.
        Use these tags when creating new dashboards to ensure consistent categorization.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: List of available tags.
          content:
            application/json:
              schema:
                type: object
                required:
                  - tags
                properties:
                  tags:
                    type: array
                    items:
                      type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboard-templates/schema:
    get:
      summary: Get dashboard template JSON Schema
      operationId: get_dashboard_template_schema
      description: >-
        Get the JSON Schema for validating dashboard template YAML files.
        Returns the schema as application/schema+json.
      tags: [Dashboards]
      responses:
        "200":
          description: Dashboard template JSON Schema.
          content:
            application/schema+json:
              schema:
                type: object

  /internal/v1/dashboard-templates/{project_id}:
    get:
      summary: List dashboard templates
      operationId: list_dashboard_templates
      description: >-
        List all available built-in dashboard templates.
        Returns template ID, name, and description for each template.
        Use this to discover available templates before creating dashboards.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: Dashboard templates list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListDashboardTemplatesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /internal/v1/dashboard-templates/{project_id}/{template_id}:
    get:
      summary: Get dashboard template
      operationId: get_dashboard_template
      description: >-
        Get a specific dashboard template by ID.
        Returns the template ID, name, description, and tags.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - name: template_id
          in: path
          required: true
          description: Dashboard template ID.
          schema:
            type: string
      responses:
        "200":
          description: Dashboard template.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetDashboardTemplateResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /internal/v1/metrics/{project_id}/explore:
    get:
      summary: Explore metrics
      operationId: explore_metrics
      description: >-
        Discover available metrics and their metadata.
        Returns metric names, instrument types (histogram, counter, gauge, additive),
        units, descriptions, available attributes, and library info.
        Use the instrument type to choose the correct aggregate function:
        histogram metrics support count(), p50(), p90(), p99();
        counter metrics support sum(), perMin(sum());
        gauge metrics support sum(), avg(), max(), min();
        additive metrics support sum(), perMin(sum()).
        Use the search parameter to filter by metric name.
        Use this tool before creating dashboards to discover metrics and their attributes.
      tags: [Metrics]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/TimeStart"
        - $ref: "#/components/parameters/TimeEnd"
        - name: search
          in: query
          required: false
          description: Search string to filter metrics by name.
          schema:
            type: string
      responses:
        "200":
          description: Metrics list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExploreMetricsResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /internal/v1/metrics/{project_id}/attributes:
    get:
      summary: List metric attributes
      operationId: list_metric_attributes
      description: >-
        List available attribute keys for metrics.
        Returns attribute keys with their kind (str, int, float), unit, and count (how many metrics use each attribute).
        Use the search parameter to filter by metric name.
        Use this to discover which attributes are available for group by in dashboard queries.
      tags: [Metrics]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/TimeStart"
        - $ref: "#/components/parameters/TimeEnd"
        - name: search
          in: query
          required: false
          description: Search string to filter metrics by name.
          schema:
            type: string
      responses:
        "200":
          description: Attribute keys list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListMetricAttributesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /internal/v1/metrics/{project_id}/attributes/{attr_key}:
    get:
      summary: List attribute values
      operationId: list_metric_attribute_values
      description: >-
        List values for a specific metric attribute key.
        Returns distinct attribute values with their occurrence count.
        Use the search parameter to filter by metric name.
      tags: [Metrics]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/TimeStart"
        - $ref: "#/components/parameters/TimeEnd"
        - name: attr_key
          in: path
          required: true
          description: "Attribute key including type suffix (e.g. host_name::str, http_status_code::int)."
          schema:
            type: string
        - name: search
          in: query
          required: false
          description: Search string to filter metrics by name.
          schema:
            type: string
      responses:
        "200":
          description: Attribute values list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListMetricAttributeValuesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /internal/v1/dashboards/{project_id}/yaml:
    post:
      summary: Create dashboard from YAML
      x-badges:
        - name: beta
      operationId: create_dashboard_from_yaml
      description: >-
        Create a new dashboard from YAML definition.
        Use this to create visualization dashboards for spans, events, logs, and metrics.
        Supports grid-based and table-based layouts with PromQL-style metric queries.
        The YAML body must include: schema (v2 or v3) and name. Optional fields: version, tags.
        Use get_dashboard_yaml on an existing dashboard to see the exact YAML format before creating.
        The API strictly rejects unknown fields.
        Table and table_grid_items overrides use column (required, must match a query alias) + properties (array of {name, value}).
        Grid item overrides (in grid_rows) use matchers + properties (array of {name, value}).
        Sparkline is a table column property ({name: sparkline, value: true}), not a top-level field.
        Documentation: https://uptrace.dev/features/dashboards
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      requestBody:
        required: true
        content:
          text/yaml:
            schema:
              type: string
              description: YAML dashboard definition.
      responses:
        "200":
          description: Dashboard created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DashboardResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}/{dashboard_id}:
    get:
      summary: Get a dashboard
      x-badges:
        - name: beta
      operationId: get_dashboard
      description: >-
        Get a dashboard by ID from Uptrace.
        Use this to retrieve full dashboard details including grid rows, items, and metric queries.
        Requires a dashboard_id -- use list_dashboards first to find available dashboard IDs.
        Documentation: https://uptrace.dev/features/dashboards
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
      responses:
        "200":
          description: Dashboard details.
          content:
            application/json:
              schema:
                type: object
                required:
                  - dashboard
                properties:
                  dashboard:
                    $ref: "#/components/schemas/Dashboard"
                  tableItems:
                    type: array
                    items:
                      $ref: "#/components/schemas/GridItem"
                  gridRows:
                    type: array
                    items:
                      $ref: "#/components/schemas/GridRow"
                  gridMetrics:
                    type: array
                    items:
                      type: string
                  yamlUrl:
                    type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      summary: Delete a dashboard
      x-badges:
        - name: beta
      operationId: delete_dashboard
      description: Delete a dashboard by ID.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
      responses:
        "200":
          description: Dashboard deleted.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}/{dashboard_id}/yaml:
    get:
      summary: Get dashboard YAML
      x-badges:
        - name: beta
      operationId: get_dashboard_yaml
      description: Retrieve the YAML representation of a dashboard.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
      responses:
        "200":
          description: Dashboard YAML.
          content:
            text/yaml:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      summary: Update dashboard from YAML
      x-badges:
        - name: beta
      operationId: update_dashboard_from_yaml
      description: >-
        Update an existing dashboard from YAML definition.
        Use get_dashboard_yaml first to retrieve the current YAML, then modify and submit.
        The API strictly rejects unknown fields.
        Table overrides use column + properties (array of {name, value}).
        Grid item overrides use matchers + properties (array of {name, value}).
        Documentation: https://uptrace.dev/features/dashboards
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
      requestBody:
        required: true
        content:
          text/yaml:
            schema:
              type: string
              description: YAML dashboard definition.
      responses:
        "200":
          description: Dashboard updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DashboardResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}/{dashboard_id}/clone:
    post:
      summary: Clone a dashboard
      x-badges:
        - name: beta
      operationId: clone_dashboard
      description: Create a copy of an existing dashboard.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
      responses:
        "200":
          description: Dashboard cloned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DashboardResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}/{dashboard_id}/reset:
    put:
      summary: Reset a dashboard
      x-badges:
        - name: beta
      operationId: reset_dashboard
      description: Reset dashboard to template or reset layout.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
      responses:
        "200":
          description: Dashboard reset.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}/{dashboard_id}/pinned:
    put:
      summary: Pin a dashboard
      x-badges:
        - name: beta
      operationId: pin_dashboard
      description: Pin dashboard to top of dashboard list.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
      responses:
        "200":
          description: Dashboard pinned.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}/{dashboard_id}/unpinned:
    put:
      summary: Unpin a dashboard
      x-badges:
        - name: beta
      operationId: unpin_dashboard
      description: Unpin dashboard from top of dashboard list.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
      responses:
        "200":
          description: Dashboard unpinned.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}/{dashboard_id}/table:
    put:
      summary: Update dashboard table
      x-badges:
        - name: beta
      operationId: update_dashboard_table
      description: Update the table configuration of a dashboard.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DashboardTableUpdate"
      responses:
        "200":
          description: Dashboard table updated.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}/{dashboard_id}/grid:
    put:
      summary: Update dashboard grid query
      x-badges:
        - name: beta
      operationId: update_dashboard_grid
      description: Update the global grid query filter for a dashboard.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                gridQuery:
                  type: string
      responses:
        "200":
          description: Dashboard grid query updated.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      summary: Create grid item
      x-badges:
        - name: beta
      operationId: create_grid_item
      description: Create a new grid item in the dashboard.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GridItemRequest"
      responses:
        "200":
          description: Grid item created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GridItemResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}/{dashboard_id}/grid/{grid_item_id}:
    put:
      summary: Update grid item
      x-badges:
        - name: beta
      operationId: update_grid_item
      description: Update an existing grid item.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
        - $ref: "#/components/parameters/GridItemId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GridItemRequest"
      responses:
        "200":
          description: Grid item updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GridItemResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      summary: Delete grid item
      x-badges:
        - name: beta
      operationId: delete_grid_item
      description: Delete a grid item from the dashboard.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
        - $ref: "#/components/parameters/GridItemId"
      responses:
        "200":
          description: Grid item deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GridItemResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}/{dashboard_id}/rows:
    post:
      summary: Create grid row
      x-badges:
        - name: beta
      operationId: create_grid_row
      description: Create a new grid row in the dashboard.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GridRowRequest"
      responses:
        "200":
          description: Grid row created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GridRowResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}/{dashboard_id}/rows/{row_id}:
    put:
      summary: Update grid row
      x-badges:
        - name: beta
      operationId: update_grid_row
      description: Update an existing grid row.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
        - $ref: "#/components/parameters/RowId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GridRow"
      responses:
        "200":
          description: Grid row updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GridRowResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      summary: Delete grid row
      x-badges:
        - name: beta
      operationId: delete_grid_row
      description: Delete a grid row and all its items.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
        - $ref: "#/components/parameters/RowId"
      responses:
        "200":
          description: Grid row deleted.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}/{dashboard_id}/rows/{row_id}/up:
    put:
      summary: Move grid row up
      x-badges:
        - name: beta
      operationId: move_grid_row_up
      description: Move a grid row up in the dashboard.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
        - $ref: "#/components/parameters/RowId"
      responses:
        "200":
          description: Grid row moved up.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GridRowResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/dashboards/{project_id}/{dashboard_id}/rows/{row_id}/down:
    put:
      summary: Move grid row down
      x-badges:
        - name: beta
      operationId: move_grid_row_down
      description: Move a grid row down in the dashboard.
      tags: [Dashboards]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DashboardId"
        - $ref: "#/components/parameters/RowId"
      responses:
        "200":
          description: Grid row moved down.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GridRowResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/projects/{project_id}/notification-channels:
    get:
      summary: List notification channels
      x-badges:
        - name: beta
      operationId: list_notification_channels
      description: Retrieve all notification channels for a project.
      tags: [NotificationChannels]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: List of notification channels.
          content:
            application/json:
              schema:
                type: object
                required:
                  - channels
                properties:
                  channels:
                    type: array
                    items:
                      $ref: "#/components/schemas/NotificationChannel"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      summary: Create notification channel
      x-badges:
        - name: beta
      operationId: create_notification_channel
      description: Create a new notification channel.
      tags: [NotificationChannels]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationChannelRequest"
      responses:
        "200":
          description: Notification channel created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationChannelResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /internal/v1/projects/{project_id}/notification-channels/{channel_id}:
    get:
      summary: Get notification channel
      x-badges:
        - name: beta
      operationId: get_notification_channel
      description: Retrieve a specific notification channel by ID.
      tags: [NotificationChannels]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/ChannelId"
      responses:
        "200":
          description: Notification channel details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationChannelResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      summary: Update notification channel
      x-badges:
        - name: beta
      operationId: update_notification_channel
      description: Update an existing notification channel.
      tags: [NotificationChannels]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/ChannelId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationChannelRequest"
      responses:
        "200":
          description: Notification channel updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationChannelResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      summary: Delete notification channel
      x-badges:
        - name: beta
      operationId: delete_notification_channel
      description: Delete an existing notification channel.
      tags: [NotificationChannels]
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/ChannelId"
      responses:
        "200":
          description: Notification channel deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationChannelResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    authTokenQuery:
      type: apiKey
      in: query
      name: auth_token
    uptraceDSNHeader:
      type: apiKey
      in: header
      name: uptrace-dsn
    dsnQuery:
      type: apiKey
      in: query
      name: dsn

  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Uptrace project ID.
      schema:
        type: integer
        format: int64
    MonitorId:
      name: monitor_id
      in: path
      required: true
      description: Monitor ID.
      schema:
        type: integer
        format: int64
    TimeStart:
      name: time_start
      in: query
      required: true
      description: Start time (inclusive) as RFC3339 timestamp.
      schema:
        type: string
        format: date-time
        description: RFC3339 timestamp.
      example: 2023-07-10T00:00:00Z
    TimeEnd:
      name: time_end
      in: query
      required: true
      description: End time (exclusive) as RFC3339 timestamp.
      schema:
        type: string
        format: date-time
        description: RFC3339 timestamp.
      example: 2023-07-11T00:00:00Z
    Limit:
      name: limit
      in: query
      required: false
      description: Limit number of results.
      schema:
        type: integer
        format: int32
      example: 10000
    DashboardId:
      name: dashboard_id
      in: path
      required: true
      description: Dashboard ID.
      schema:
        type: integer
        format: int64
    ChannelId:
      name: channel_id
      in: path
      required: true
      description: Notification channel ID.
      schema:
        type: integer
        format: int64
    GridItemId:
      name: grid_item_id
      in: path
      required: true
      description: Grid item ID.
      schema:
        type: integer
        format: int64
    RowId:
      name: row_id
      in: path
      required: true
      description: Grid row ID.
      schema:
        type: integer
        format: int64

  schemas:
    SortDirection:
      type: string
      enum: [ASC, DESC]
      description: Sort direction.

    OrderItem:
      type: object
      properties:
        key:
          type: string
        order:
          type: string
          enum: [asc, desc]

    Span:
      type: object
      description: A span representing an individual operation in a distributed trace.
      properties:
        id:
          type: string
          description: Span ID (hex-encoded).
        parentId:
          type: string
          description: Parent span ID (hex-encoded, empty for root spans).
        traceId:
          type: string
          description: Trace ID (hex-encoded).
        standalone:
          type: boolean
          description: Whether the span is standalone (not part of a trace).
        projectId:
          type: integer
          format: uint32
          description: Project ID.
        groupId:
          type: string
          description: Group ID (uint64 as string).
        type:
          type: string
          description: Telemetry type (spans, events, logs, funcs).
        system:
          type: string
          description: Detected system (e.g., httpserver:all, db:postgresql, log:error).
        kind:
          type: string
          description: Span kind (client, server, producer, consumer, internal).
        name:
          type: string
          description: Span name.
        eventName:
          type: string
          description: Event name (for event spans).
        displayName:
          type: string
          description: Human-readable operation summary.
        time:
          type: number
          format: double
          description: Span start time as unix milliseconds.
        duration:
          type: number
          format: double
          description: Duration in milliseconds.
        statusCode:
          type: string
          description: Status code (ok, error, unset).
        statusMessage:
          type: string
          description: Optional status message.
        attrs:
          type: object
          additionalProperties: true
          description: Span attributes as key-value map. Keys include type suffix (e.g., service_name::str, count::int).
        events:
          type: array
          description: Child event spans.
          items:
            type: object
            additionalProperties: true
        logs:
          type: array
          description: Child log spans.
          items:
            type: object
            additionalProperties: true
        links:
          type: array
          description: Span links to other spans.
          items:
            type: object
            properties:
              traceId:
                type: string
              spanId:
                type: string
              attrs:
                type: object
                additionalProperties: true
      required: [id, traceId, name, time, duration, statusCode]

    GroupsResult:
      type: object
      description: Result of a span group aggregation query.
      properties:
        groups:
          type: array
          description: Array of group rows with dynamic columns. Each row may contain __hash, __name, __query metadata fields.
          items:
            type: object
            additionalProperties: true
        columns:
          type: array
          description: Column definitions describing the result schema.
          items:
            $ref: "#/components/schemas/QueryColumn"
        hasMore:
          type: boolean
          description: Whether more results exist beyond the limit.
        query:
          type: array
          description: Parsed query parts with error state.
          items:
            type: object
            additionalProperties: true
        sorting:
          type: array
          description: Applied sorting configuration.
          items:
            $ref: '#/components/schemas/OrderItem'
        search:
          type: array
          description: Applied search matchers.
          items:
            type: object
            additionalProperties: true
        whereAttrs:
          type: object
          description: Map of WHERE attribute names to their matched values.
          additionalProperties: true
      required: [groups]

    QueryColumn:
      type: object
      description: Column definition for a query result.
      properties:
        name:
          type: string
          description: Column name.
        expr:
          type: string
          description: Column expression as written in the query.
        unit:
          type: string
          description: Column unit (e.g., ms, bytes).
        isNum:
          type: boolean
          description: Whether the column contains numeric values.
        isAgg:
          type: boolean
          description: Whether the column is an aggregation.
        isGroup:
          type: boolean
          description: Whether the column is a GROUP BY key.
        aggFunc:
          type: string
          description: Aggregation function applied to this column.
      required: [name]

    Timeseries:
      type: object
      description: A named timeseries with values aligned to timestamps.
      properties:
        name:
          type: string
          description: Metric name (e.g., countPerMin, errorCountPerMin, durationP50, durationP90, durationP99).
        value:
          type: array
          description: Array of metric values.
          items:
            type: number
            format: double
        time:
          type: array
          description: Array of timestamps as unix milliseconds.
          items:
            type: number
            format: double
      required: [name, value, time]

    AnnotationCreateRequest:
      type: object
      properties:
        name:
          type: string
          description: Annotation name.
        description:
          type: string
          description: Annotation description text in Markdown format.
        color:
          type: string
          description: Color to be used in charts.
        attrs:
          type: object
          additionalProperties:
            type: string
          description: Key-value metadata.
        fingerprint:
          type: string
          description: Unique string used for deduplication.
        time:
          type: string
          format: date-time
          description: Overrides annotation time in RFC3339 format.
      required:
        - name
    ListDashboardTemplatesResponse:
      type: object
      properties:
        templates:
          type: array
          items:
            $ref: "#/components/schemas/DashboardTemplateItem"
        tags:
          type: array
          items:
            type: string
          description: All unique tags across templates.
      required: [templates]

    DashboardTemplateItem:
      type: object
      properties:
        id:
          type: string
          description: Template ID.
        name:
          type: string
          description: Template name.
        description:
          type: string
          description: Template description.
        tags:
          type: array
          items:
            type: string
          description: Template tags.
        version:
          type: string
          description: Template version.
        setupLink:
          type: string
          description: Link to setup instructions.
        docLink:
          type: string
          description: Link to documentation.
        status:
          $ref: "#/components/schemas/TemplateStatus"
        dashboardId:
          type: integer
          description: ID of the dashboard created from this template, if any.
      required: [id, name, description, status]

    GetDashboardTemplateResponse:
      type: object
      properties:
        template:
          $ref: "#/components/schemas/DashboardTemplate"
        yaml:
          type: string
          description: Full dashboard template YAML definition.
      required: [template]

    DashboardTemplate:
      type: object
      properties:
        id:
          type: string
          description: Template ID.
        name:
          type: string
          description: Template name.
        description:
          type: string
          description: Template description.
        tags:
          type: array
          items:
            type: string
          description: Template tags.
        version:
          type: string
          description: Template version.
        setupLink:
          type: string
          description: Link to setup instructions.
        docLink:
          type: string
          description: Link to documentation.
        status:
          $ref: "#/components/schemas/TemplateStatus"
        dashboardId:
          type: integer
          description: ID of the dashboard created from this template, if any.
        yaml:
          type: string
          description: Template YAML definition.
      required: [id, name, description, status]

    TemplateStatus:
      type: string
      description: Template availability status.
      enum: [ready, pending, installed]

    ExploreMetricsResponse:
      type: object
      properties:
        metrics:
          type: array
          items:
            $ref: "#/components/schemas/ExploredMetric"
        hasMore:
          type: boolean
      required: [metrics, hasMore]

    ExploredMetric:
      type: object
      properties:
        name:
          type: string
          description: Metric name.
        instrument:
          type: string
          enum: [histogram, summary, counter, prom-counter, gauge, additive]
          description: OpenTelemetry instrument type.
        unit:
          type: string
          description: Metric unit.
        description:
          type: string
          description: Metric description.
        attrKeys:
          type: array
          items:
            type: string
          description: Available attribute keys for grouping.
        libraryName:
          type: string
          description: Instrumentation library name.
        libraryVersion:
          type: string
          description: Instrumentation library version.
        numTimeseries:
          type: integer
          description: Number of active timeseries.
      required: [name, instrument]

    ListMetricAttributesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/MetricAttributeKey"
      required: [items]

    MetricAttributeKey:
      type: object
      properties:
        value:
          type: string
          description: "Attribute key with type suffix (e.g. host_name::str)."
        kind:
          type: string
          description: "Attribute type: str, int, float."
        unit:
          type: string
          description: Attribute unit.
        pinned:
          type: boolean
          description: Whether the attribute is pinned.
        count:
          type: integer
          description: Number of metrics using this attribute.
      required: [value, kind, count]

    ListMetricAttributeValuesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/MetricAttributeValue"
        hasMore:
          type: boolean
      required: [items, hasMore]

    MetricAttributeValue:
      type: object
      properties:
        value:
          type: string
          description: Attribute value.
        count:
          type: integer
          description: Occurrence count.
      required: [value, count]

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required: [code, message]

    SeedDataRequest:
      type: object
      description: Fixture data used to create, update, or delete resources by key.
      properties:
        users:
          type: array
          items:
            $ref: "#/components/schemas/UserFixture"
        userTokens:
          type: array
          items:
            $ref: "#/components/schemas/UserTokenFixture"
        orgs:
          type: array
          items:
            $ref: "#/components/schemas/OrgFixture"
        orgUsers:
          type: array
          items:
            $ref: "#/components/schemas/OrgUserFixture"
        projects:
          type: array
          items:
            $ref: "#/components/schemas/ProjectFixture"
        projectTokens:
          type: array
          items:
            $ref: "#/components/schemas/ProjectTokenFixture"
        projectUsers:
          type: array
          items:
            $ref: "#/components/schemas/ProjectUserFixture"

    LinkDataRequest:
      type: object
      description: Links existing resources to fixture keys.
      properties:
        orgs:
          type: array
          items:
            $ref: "#/components/schemas/LinkFixture"
        orgUsers:
          type: array
          items:
            $ref: "#/components/schemas/LinkFixture"
        projects:
          type: array
          items:
            $ref: "#/components/schemas/LinkFixture"
        projectTokens:
          type: array
          items:
            $ref: "#/components/schemas/LinkFixture"

    UserFixture:
      type: object
      properties:
        key:
          type: string
          description: Unique fixture key.
        name:
          type: string
          description: Display name.
        email:
          type: string
          format: email
        password:
          type: string
          description: Plain-text password (hashed by Uptrace).
      required:
        - key
        - name
        - email
        - password

    UserTokenFixture:
      type: object
      properties:
        key:
          type: string
        userKey:
          type: string
          description: References users.key.
        token:
          type: string
        name:
          type: string
          description: Human-readable token name.
      required:
        - key
        - userKey
        - token

    OrgFixture:
      type: object
      properties:
        key:
          type: string
        name:
          type: string
        description:
          type: string
      required:
        - key
        - name

    OrgUserFixture:
      type: object
      properties:
        key:
          type: string
        orgKey:
          type: string
          description: References orgs.key.
        userKey:
          type: string
          description: References users.key.
        role:
          type: string
          enum:
            - owner
            - admin
            - viewer
            - member
            - collaborator
            - billing_manager
            - billing-manager
      required:
        - key
        - orgKey
        - userKey
        - role

    ProjectFixture:
      type: object
      properties:
        key:
          type: string
        name:
          type: string
        orgKey:
          type: string
          description: References orgs.key.
        description:
          type: string
      required:
        - key
        - name
        - orgKey

    ProjectTokenFixture:
      type: object
      properties:
        key:
          type: string
        projectKey:
          type: string
          description: References projects.key.
        token:
          type: string
        name:
          type: string
      required:
        - key
        - projectKey
        - token

    ProjectUserFixture:
      type: object
      properties:
        key:
          type: string
        projectKey:
          type: string
          description: References projects.key.
        orgUserKey:
          type: string
          description: References orgUsers.key.
        permLevel:
          type: string
          enum:
            - admin
            - maintain
            - view
            - none
      required:
        - key
        - projectKey
        - orgUserKey
        - permLevel

    LinkFixture:
      type: object
      properties:
        id:
          type: integer
          format: int64
        key:
          type: string
      required:
        - id
        - key

    MonitorResponse:
      type: object
      properties:
        monitor:
          $ref: "#/components/schemas/Monitor"
      required:
        - monitor
    BaseMonitorRequest:
      type: object
      properties:
        name:
          type: string
        notifyEveryoneByEmail:
          type: boolean
        teamIds:
          type: array
          items:
            type: integer
        channelIds:
          type: array
          items:
            type: integer
        repeatInterval:
          $ref: "#/components/schemas/RepeatInterval"
      required:
        - name
    MetricMonitorRequest:
      allOf:
        - $ref: "#/components/schemas/BaseMonitorRequest"
        - type: object
          properties:
            type:
              type: string
              enum:
                - metric
            params:
              $ref: "#/components/schemas/MetricMonitorParams"
          required:
            - type
            - params
    ErrorMonitorRequest:
      allOf:
        - $ref: "#/components/schemas/BaseMonitorRequest"
        - type: object
          properties:
            type:
              type: string
              enum:
                - error
            params:
              $ref: "#/components/schemas/ErrorMonitorParams"
          required:
            - type
            - params
    MetricMonitorParams:
      type: object
      properties:
        metrics:
          type: array
          items:
            $ref: "#/components/schemas/MonitorMetric"
        query:
          type: string
        columnName:
          type: string
        columnUnit:
          type: string
        boundsSource:
          type: string
          enum:
            - manual
            - auto
        resolution:
          type: number
          description: Resolution in milliseconds.
        numEvalPoints:
          type: integer
        minAllowedValue:
          type: number
        maxAllowedValue:
          type: number
        flapping:
          $ref: "#/components/schemas/FlappingParams"
        tolerance:
          type: string
          enum:
            - low
            - medium
            - high
        trainingPeriod:
          type: number
          description: Training period in milliseconds.
        minDevFraction:
          type: number
        minDevValue:
          type: number
        nullsMode:
          type: string
          enum:
            - allow
            - forbid
            - convert
        timeOffset:
          type: number
          description: Time offset in milliseconds.
      required:
        - metrics
        - query
    ErrorMonitorParams:
      type: object
      properties:
        metrics:
          type: array
          items:
            $ref: "#/components/schemas/MonitorMetric"
        query:
          type: string
      required:
        - metrics
        - query
    FlappingParams:
      type: object
      properties:
        minAllowedValue:
          type: number
        maxAllowedValue:
          type: number
    MonitorMetric:
      type: object
      properties:
        name:
          type: string
        alias:
          type: string
      required:
        - name

    RepeatInterval:
      type: object
      description: Monitor repeat interval configuration.
      oneOf:
        - $ref: "#/components/schemas/DefaultRepeatInterval"
        - $ref: "#/components/schemas/FixedRepeatInterval"
        - $ref: "#/components/schemas/LinearRepeatInterval"
        - $ref: "#/components/schemas/ExponentialRepeatInterval"

    DefaultRepeatInterval:
      type: object
      properties:
        strategy:
          type: string
          enum: [default]

    FixedRepeatInterval:
      type: object
      properties:
        strategy:
          type: string
          enum: [fixed]
        interval:
          type: number
          description: Fixed interval in milliseconds.
      required:
        - strategy
        - interval

    LinearRepeatInterval:
      type: object
      properties:
        strategy:
          type: string
          enum: [linear]
        min:
          type: number
          description: Minimum interval in milliseconds.
        max:
          type: number
          description: Maximum interval in milliseconds.
      required:
        - strategy
        - min
        - max

    ExponentialRepeatInterval:
      type: object
      properties:
        strategy:
          type: string
          enum: [exponential]
        min:
          type: number
          description: Minimum interval in milliseconds.
        max:
          type: number
          description: Maximum interval in milliseconds.
      required:
        - strategy
        - min
        - max

    Monitor:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        type:
          type: string
          enum: [metric, error]
        status:
          type: string
          enum: [active, paused, firing, no_data, disabled]
        notifyEveryoneByEmail:
          type: boolean
        teamIds:
          type: array
          items:
            type: integer
        channelIds:
          type: array
          items:
            type: integer
        repeatInterval:
          $ref: "#/components/schemas/RepeatInterval"
        params:
          type: object
          additionalProperties: true
        createdAt:
          type: number
        updatedAt:
          type: number
      required:
        - id
        - name
        - type
        - status

    Dashboard:
      type: object
      properties:
        id:
          type: integer
          format: int64
        projectId:
          type: integer
          format: int64
        templateId:
          type: string
        name:
          type: string
        pinned:
          type: boolean
        minInterval:
          type: number
        timeOffset:
          type: number
        gridQuery:
          type: string
        gridMaxWidth:
          type: integer
        tableMetrics:
          type: array
          items:
            $ref: "#/components/schemas/MetricAlias"
        tableQuery:
          type: string
        tableGrouping:
          type: array
          items:
            type: string
        tableColumnMap:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/TableColumn"
        createdAt:
          type: number
        updatedAt:
          type: number
      required:
        - id
        - projectId
        - name

    DashboardResponse:
      type: object
      properties:
        dashboard:
          $ref: "#/components/schemas/Dashboard"
      required:
        - dashboard

    DashboardTableUpdate:
      type: object
      properties:
        name:
          type: string
        tableMetrics:
          type: array
          items:
            $ref: "#/components/schemas/MetricAlias"
        tableQuery:
          type: string
        tableColumnMap:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/TableColumn"

    MetricAlias:
      type: object
      properties:
        name:
          type: string
        alias:
          type: string
      required:
        - name
        - alias

    TableColumn:
      type: object
      properties:
        unit:
          type: string
        color:
          type: string
        aggFunc:
          type: string
          enum: [min, max, sum, avg, avg_zero, median, last]
        sparklineDisabled:
          type: boolean

    GridRow:
      type: object
      properties:
        id:
          type: integer
          format: int64
        dashboardId:
          type: integer
          format: int64
        title:
          type: string
        description:
          type: string
        expanded:
          type: boolean
        index:
          type: integer
        items:
          type: array
          items:
            $ref: "#/components/schemas/GridItem"
        createdAt:
          type: number
        updatedAt:
          type: number
      required:
        - id
        - dashboardId
        - title
        - index

    GridRowRequest:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        expanded:
          type: boolean
      required:
        - title

    GridRowResponse:
      type: object
      properties:
        gridRow:
          $ref: "#/components/schemas/GridRow"
      required:
        - gridRow

    GridItem:
      type: object
      properties:
        id:
          type: integer
          format: int64
        title:
          type: string
        description:
          type: string
        dashboardId:
          type: integer
          format: int64
        dashboardKind:
          type: string
          enum: [grid, table]
        rowId:
          type: integer
          format: int64
        width:
          type: integer
        height:
          type: integer
        xAxis:
          type: integer
        yAxis:
          type: integer
        type:
          type: string
          enum: [chart, table, heatmap, gauge]
        params:
          type: object
          additionalProperties: true
        createdAt:
          type: number
        updatedAt:
          type: number
      required:
        - id
        - title
        - dashboardId
        - dashboardKind
        - type

    GridItemRequest:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        dashboardKind:
          type: string
          enum: [grid, table]
        rowId:
          type: integer
          format: int64
        width:
          type: integer
        height:
          type: integer
        xAxis:
          type: integer
        yAxis:
          type: integer
        type:
          type: string
          enum: [chart, table, heatmap, gauge]
        params:
          type: object
          additionalProperties: true
      required:
        - title
        - dashboardKind
        - rowId
        - type

    GridItemResponse:
      type: object
      properties:
        gridItem:
          $ref: "#/components/schemas/GridItem"
      required:
        - gridItem

    SlackParams:
      type: object
      description: Slack params. When authMethod=webhook, webhookUrl is required. When authMethod=token, token and channel are required.
      properties:
        webhookUrl:
          type: string
        token:
          type: string
        channel:
          type: string
        authMethod:
          type: string
          enum: [webhook, token]

    GoogleChatParams:
      type: object
      properties:
        webhookUrl:
          type: string
      required:
        - webhookUrl

    MattermostParams:
      type: object
      properties:
        webhookUrl:
          type: string
      required:
        - webhookUrl

    PagerdutyParams:
      type: object
      properties:
        routingKey:
          type: string
        severity:
          type: string
          enum: [critical, error, warning, info]
      required:
        - routingKey
        - severity

    ServicenowParams:
      type: object
      properties:
        url:
          type: string
        username:
          type: string
        password:
          type: string
        category:
          type: string
        subcategory:
          type: string
        impact:
          type: string
          enum: ["1", "2", "3"]
        urgency:
          type: string
          enum: ["1", "2", "3"]
        severity:
          type: string
          enum: ["1", "2", "3", "4", "5"]
        callerId:
          type: string
        group:
          type: string
        assignedTo:
          type: string
        openedBy:
          type: string
        notify:
          type: string
          enum: ["1", "2"]
        dueDate:
          type: string
      required:
        - url
        - username
        - password

    OpsgenieParams:
      type: object
      properties:
        apiKey:
          type: string
        priority:
          type: string
          enum: [P1, P2, P3, P4, P5]
      required:
        - apiKey
        - priority

    TelegramParams:
      type: object
      properties:
        chatId:
          type: integer
          format: int64
      required:
        - chatId

    TeamsParams:
      type: object
      properties:
        webhookUrl:
          type: string
      required:
        - webhookUrl

    WebhookParams:
      type: object
      properties:
        url:
          type: string
        payload:
          type: object
          additionalProperties: true
      required:
        - url

    NotificationChannel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        projectId:
          type: integer
          format: int64
        name:
          type: string
        type:
          type: string
          enum:
            [
              slack,
              google_chat,
              mattermost,
              pagerduty,
              servicenow,
              opsgenie,
              telegram,
              teams,
              webhook,
              alertmanager,
            ]
        status:
          type: string
          enum: [draft, delivering, paused, disabled]
        error:
          type: string
        matchAll:
          type: boolean
        condition:
          type: string
        priorities:
          type: array
          items:
            type: string
            enum: [info, low, medium, high]
        params:
          oneOf:
            - $ref: "#/components/schemas/SlackParams"
            - $ref: "#/components/schemas/GoogleChatParams"
            - $ref: "#/components/schemas/MattermostParams"
            - $ref: "#/components/schemas/PagerdutyParams"
            - $ref: "#/components/schemas/ServicenowParams"
            - $ref: "#/components/schemas/OpsgenieParams"
            - $ref: "#/components/schemas/TelegramParams"
            - $ref: "#/components/schemas/TeamsParams"
            - $ref: "#/components/schemas/WebhookParams"
        monitorIds:
          type: array
          items:
            type: integer
            format: int64
        monitorCount:
          type: integer
        sentCount:
          type: integer
        lastSentAt:
          type: string
          format: date-time
      required:
        - id
        - projectId
        - name
        - type
        - status
        - params

    NotificationChannelRequest:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          enum:
            [
              slack,
              google_chat,
              mattermost,
              pagerduty,
              servicenow,
              opsgenie,
              telegram,
              teams,
              webhook,
              alertmanager,
            ]
        matchAll:
          type: boolean
        monitorIds:
          type: array
          items:
            type: integer
            format: int64
        condition:
          type: string
        priorities:
          type: array
          items:
            type: string
            enum: [info, low, medium, high]
        params:
          oneOf:
            - $ref: "#/components/schemas/SlackParams"
            - $ref: "#/components/schemas/GoogleChatParams"
            - $ref: "#/components/schemas/MattermostParams"
            - $ref: "#/components/schemas/PagerdutyParams"
            - $ref: "#/components/schemas/ServicenowParams"
            - $ref: "#/components/schemas/OpsgenieParams"
            - $ref: "#/components/schemas/TelegramParams"
            - $ref: "#/components/schemas/TeamsParams"
            - $ref: "#/components/schemas/WebhookParams"
      required:
        - name
        - type
        - priorities
        - params

    NotificationChannelResponse:
      type: object
      properties:
        channel:
          $ref: "#/components/schemas/NotificationChannel"
      required:
        - channel

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"