Clarity Kpi API

openapi: 3.2.0
info:
  title: Fast Kpi API
  version: 0.1.0
tags:
- name: kpi
paths:
  /api/v1/kpi:
    post:
      tags:
      - kpi
      summary: Build Kpi
      description: 'Compute a single KPI value, its baseline, and the delta between them.


        Reuses the `/tables` aggregation engine internally (see `kpi_builder`). The

        current period is defined by `filters` (page-level filters plus the widget''s

        own `ds`); the baseline is computed server-side per `baseline.type`.


        Args:

        body: Filters, optional search query, the aggregation, and the baseline mode.


        Returns:

        The value, the baseline (null when unavailable or `type == ''none''`), and

        the signed delta (null when there''s no baseline to compare against).


        Raises:

        HTTPException: 422 when a non-count aggregation is missing its `field`.'
      operationId: build_kpi_api_v1_kpi_post
      security:
      - HTTPBearer: []
      parameters:
      - name: x-request-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Request-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KpiRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KpiResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    KpiAggregation:
      properties:
        operation:
          type: string
          enum:
          - count
          - sum
          - avg
          - median
          - min
          - max
          - cardinality
          - top_1
          title: Operation
        field:
          anyOf:
          - type: string
          - type: 'null'
          title: Field
          description: Field to aggregate. Ignored for `count`; required for the other operations.
      type: object
      required:
      - operation
      title: KpiAggregation
      description: Which metric to compute.
    KpiDelta:
      properties:
        absolute:
          type: number
          title: Absolute
        percent:
          anyOf:
          - type: number
          - type: 'null'
          title: Percent
        direction:
          type: string
          enum:
          - up
          - down
          - flat
          title: Direction
      type: object
      required:
      - absolute
      - percent
      - direction
      title: KpiDelta
    KpiResponse:
      properties:
        value:
          anyOf:
          - type: number
          - type: 'null'
          title: Value
        baseline:
          anyOf:
          - $ref: '#/components/schemas/KpiBaselineResult'
          - type: 'null'
        delta:
          anyOf:
          - $ref: '#/components/schemas/KpiDelta'
          - type: 'null'
        range:
          anyOf:
          - $ref: '#/components/schemas/src__service__kpi_builder__DateRange'
          - type: 'null'
        overrides_page_range:
          type: boolean
          title: Overrides Page Range
          default: false
      type: object
      required:
      - value
      title: KpiResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    KpiWindow:
      properties:
        type:
          type: string
          const: relative
          title: Type
          default: relative
        unit:
          type: string
          enum:
          - day
          - week
          - month
          - quarter
          - year
          title: Unit
          default: week
        count:
          type: integer
          minimum: 1.0
          title: Count
          description: Trailing length in units.
          default: 1
        offset:
          type: integer
          title: Offset
          default: 0
        align:
          type: string
          enum:
          - complete
          - to_date
          title: Align
          default: complete
        week_start:
          type: string
          enum:
          - monday
          - sunday
          title: Week Start
          default: monday
        anchor:
          type: string
          enum:
          - today
          - dashboard_end
          title: Anchor
          default: today
        override_page_range:
          type: boolean
          title: Override Page Range
          description: Echoed back so the card can badge itself — a widget that ignores the page date range must say so, or it breaks the filter mental model.
          default: true
      type: object
      title: KpiWindow
      description: 'The card''s own period, independent of the dashboard''s date range.


        Without this a week-over-week card is hostage to the page: `previous_period`

        shifts the range back by its own length, so the card only says "week over

        week" when the whole dashboard is set to seven days.'
    src__service__kpi_builder__DateRange:
      properties:
        from:
          type: string
          title: From
        to:
          type: string
          title: To
      type: object
      required:
      - from
      - to
      title: DateRange
      description: Inclusive date window, `YYYY-MM-DD`.
    KpiBaselineResult:
      properties:
        type:
          type: string
          enum:
          - previous_period
          - previous_calendar_month
          - previous_quarter
          - same_period_last_year
          - custom_range
          - fixed_number
          - relative
          title: Type
        value:
          anyOf:
          - type: number
          - type: 'null'
          title: Value
        range:
          anyOf:
          - $ref: '#/components/schemas/src__service__kpi_builder__DateRange'
          - type: 'null'
      type: object
      required:
      - type
      - value
      title: KpiBaselineResult
    KpiRequest:
      properties:
        filters:
          items:
            $ref: '#/components/schemas/QueryFilter'
          type: array
          title: Filters
        query:
          anyOf:
          - type: string
          - type: 'null'
          title: Query
        aggregation:
          $ref: '#/components/schemas/KpiAggregation'
        baseline:
          $ref: '#/components/schemas/KpiBaseline'
        window:
          anyOf:
          - $ref: '#/components/schemas/KpiWindow'
          - type: 'null'
      type: object
      required:
      - aggregation
      title: KpiRequest
      description: Request body for `POST /api/v1/kpi`. `project` comes from the auth token.
    DateRange-Input:
      properties:
        from:
          type: string
          title: From
        to:
          type: string
          title: To
      type: object
      required:
      - from
      - to
      title: DateRange
      description: Inclusive date window, `YYYY-MM-DD`.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    QueryFilter:
      properties:
        type:
          anyOf:
          - type: string
            const: exists
          - type: string
            const: list
          - type: string
            const: nested
          - type: string
            const: range
          - type: string
            const: text
          title: Type
        key:
          type: string
          title: Key
        values:
          anyOf:
          - items:
              type: string
            type: array
          - items:
              type: integer
            type: array
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: string
          - type: 'null'
          title: Values
        min:
          anyOf:
          - type: string
          - type: integer
          - type: number
          - type: 'null'
          title: Min
        max:
          anyOf:
          - type: string
          - type: integer
          - type: number
          - type: 'null'
          title: Max
        operator:
          anyOf:
          - type: string
            const: eq
          - type: string
            const: neq
          - type: string
            const: contains
          title: Operator
          default: eq
        generated:
          type: boolean
          title: Generated
          default: false
      type: object
      required:
      - type
      - key
      title: QueryFilter
    KpiBaseline:
      properties:
        type:
          type: string
          enum:
          - previous_period
          - previous_calendar_month
          - previous_quarter
          - same_period_last_year
          - custom_range
          - fixed_number
          - relative
          - none
          title: Type
          default: none
        range:
          anyOf:
          - $ref: '#/components/schemas/DateRange-Input'
          - type: 'null'
          description: Window for `custom_range`.
        value:
          anyOf:
          - type: number
          - type: 'null'
          title: Value
          description: User-entered baseline for `fixed_number`.
        unit:
          anyOf:
          - type: string
            enum:
            - day
            - week
            - month
            - quarter
            - year
          - type: 'null'
          title: Unit
        offset:
          type: integer
          title: Offset
          default: -1
        align:
          anyOf:
          - type: string
            enum:
            - complete
            - to_date
          - type: 'null'
          title: Align
        week_start:
          anyOf:
          - type: string
            enum:
            - monday
            - sunday
          - type: 'null'
          title: Week Start
      type: object
      title: KpiBaseline
      description: Baseline to compare the value against.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic