Skip to content

Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.

70.6 KB
Raw Blame
openapi: 3.0.3
info:
  title: OpenLIT Client API
  description: |
    API specification for the OpenLIT client application.
    Authenticate every request with an OpenLIT API key
    (`Authorization: Bearer openlit-...`).

    ## Request context headers

    OpenLIT scopes data by **Organisation → Project → Environment**.
    **Signal routing** (latest) selects the connector for each signal from the
    active project + environment. Prefer these headers on API calls:

    - `x-openlit-organisation-id` — active organisation
    - `x-openlit-project-id` — active project (bindings are project-scoped)
    - `x-openlit-environment` — active environment (drives signal routing)

    ### Non-SDK APIs (telemetry, Ask Otter, AI Analysis, Scanner, …)
    Use signal routing headers only. Do **not** send
    `x-openlit-database-config-id`. The API key still binds a vault/credential
    database config (middleware injects `x-database-config-id`).

    ### SDK-facing APIs (Prompt Hub, Vault, Rule Engine evaluate)
    Prefer signal routing (`project` + `environment`) to resolve the intelligence
    ClickHouse that stores prompts, secrets, and rules. Existing SDKs that only
    send `Authorization: Bearer …` keep working via the API key's bound database
    config. Those endpoints also accept an explicit
    `x-openlit-database-config-id` when it belongs to the same project as the key.

    ## Authentication

    All documented endpoints require Bearer API key auth (`ApiKeyAuth`), except
    API key management (`/api/api-key`), which requires a signed-in session
    (`SessionAuth`) so a key can't list, create, change, or delete keys.
  version: 1.29.0
servers:
  - url: http://localhost:3000
    description: Local development server
tags:
  - name: Telemetry
    description: Telemetry retrieval and observability querying APIs
  - name: AI Analysis
    description: Structured AI review of traces and spans (strengths, improvements, cost, tokens, path)
  - name: Ask Otter
    description: Conversational assistant for telemetry investigation, SQL execution, and usage
  - name: Prompt Hub
    description: Manage and compile prompt templates
  - name: Secret Vault
    description: Manage credentials and secrets inside Vault
  - name: Rule Engine
    description: Evaluate guardrails and redaction rules
  - name: Controller
    description: Sync state and heartbeat polling for OpenLIT controllers
  - name: Evaluation Engine
    description: Offline LLM evaluations
  - name: API Keys
    description: Manage browser/SDK access keys
  - name: Scanner
    description: Run Trustabl scanner jobs and retrieve findings for GitHub repositories

paths:
  /api/telemetry/logs:
    post:
      tags:
        - Telemetry
      summary: Query logs
      description: Retrieve a paginated list of telemetry logs matching the provided filters. Requires an OpenLIT API key plus organisation/project/environment headers for signal routing.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricParams'
      responses:
        '200':
          description: A list of logs and total count.
          content:
            application/json:
              schema:
                type: object
                properties:
                  records:
                    type: array
                    items:
                      type: object
                  total:
                    type: integer
                    example: 150
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '400':
          $ref: '#/components/responses/BadRequestError'

  /api/telemetry/logs/{id}:
    get:
      tags:
        - Telemetry
      summary: Get log detail by row ID
      description: Retrieve detail of a specific log entry by its hash/row ID.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
        - name: id
          in: path
          required: true
          description: Path parameter. The cityHash64 row ID of the log.
          schema:
            type: string
      responses:
        '200':
          description: Log details retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  record:
                    type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/telemetry/logs/attribute-keys:
    post:
      tags:
        - Telemetry
      summary: Query log attribute keys
      description: Retrieve unique attribute keys for log attributes, resource attributes, and scope attributes.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                timeLimit:
                  $ref: '#/components/schemas/TimeLimit'
      responses:
        '200':
          description: Unique attribute keys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  logAttributeKeys:
                    type: array
                    items:
                      type: string
                  resourceAttributeKeys:
                    type: array
                    items:
                      type: string
                  scopeAttributeKeys:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '400':
          $ref: '#/components/responses/BadRequestError'

  /api/telemetry/logs/config:
    post:
      tags:
        - Telemetry
      summary: Query logs config options
      description: Retrieve configuration metadata such as available service names, severities, and total log rows.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                timeLimit:
                  $ref: '#/components/schemas/TimeLimit'
      responses:
        '200':
          description: Configuration metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  services:
                    type: array
                    items:
                      type: string
                  severities:
                    type: array
                    items:
                      type: string
                  totalRows:
                    type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/telemetry/metrics:
    post:
      tags:
        - Telemetry
      summary: Query metrics list
      description: Retrieve a list of aggregated metrics matching the filters.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricParams'
      responses:
        '200':
          description: A list of metrics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  records:
                    type: array
                    items:
                      type: object
                  total:
                    type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '400':
          $ref: '#/components/responses/BadRequestError'

  /api/telemetry/metrics/{name}:
    post:
      tags:
        - Telemetry
      summary: Get metric detail
      description: Retrieve time-series graph points and detail records for a specific metric name.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
        - name: name
          in: path
          required: true
          description: Path parameter. The name of the metric.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                timeLimit:
                  $ref: '#/components/schemas/TimeLimit'
                metricType:
                  type: string
                serviceName:
                  type: string
                selectedConfig:
                  type: object
      responses:
        '200':
          description: Metric graph and data points.
          content:
            application/json:
              schema:
                type: object
                properties:
                  series:
                    type: array
                    items:
                      type: object
                  points:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/telemetry/metrics/attribute-keys:
    post:
      tags:
        - Telemetry
      summary: Query metric attribute keys
      description: Retrieve unique attribute keys for metrics.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                timeLimit:
                  $ref: '#/components/schemas/TimeLimit'
      responses:
        '200':
          description: Metric attributes keys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  metricAttributeKeys:
                    type: array
                    items:
                      type: string
                  resourceAttributeKeys:
                    type: array
                    items:
                      type: string
                  scopeAttributeKeys:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/telemetry/metrics/config:
    post:
      tags:
        - Telemetry
      summary: Query metrics configuration metadata
      description: Retrieve list of available services, metric names, types, and counts.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                timeLimit:
                  $ref: '#/components/schemas/TimeLimit'
      responses:
        '200':
          description: Config metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  services:
                    type: array
                    items:
                      type: string
                  metricNames:
                    type: array
                    items:
                      type: string
                  metricTypes:
                    type: array
                    items:
                      type: string
                  totalRows:
                    type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/telemetry/summary/{signal}:
    post:
      tags:
        - Telemetry
      summary: Query signal summary data
      description: Retrieve aggregated time-series summary bucketed counts and metrics (e.g. costs, latency, or token counts) for traces, exceptions, logs, or metrics.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
        - name: signal
          in: path
          required: true
          description: Path parameter. The telemetry signal type.
          schema:
            type: string
            enum: [traces, exceptions, logs, metrics]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                timeLimit:
                  $ref: '#/components/schemas/TimeLimit'
                selectedConfig:
                  type: object
      responses:
        '200':
          description: Aggregated summary stats bucketed by time interval.
          content:
            application/json:
              schema:
                type: object
                properties:
                  bucket:
                    type: string
                    example: hour
                  buckets:
                    type: array
                    items:
                      type: object
                  total:
                    type: integer
                  peak:
                    type: number
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '400':
          $ref: '#/components/responses/BadRequestError'

  /api/telemetry/trace:
    post:
      tags:
        - Telemetry
      summary: Query traces list
      description: Retrieve a paginated list of trace spans matching the provided filters. Requires an OpenLIT API key plus organisation/project/environment headers for signal routing.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricParams'
      responses:
        '200':
          description: A list of traces and total count.
          content:
            application/json:
              schema:
                type: object
                properties:
                  records:
                    type: array
                    items:
                      type: object
                  total:
                    type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '400':
          $ref: '#/components/responses/BadRequestError'

  /api/telemetry/exception:
    post:
      tags:
        - Telemetry
      summary: Query exceptions list
      description: Retrieve a paginated list of exceptions matching the provided filters. Requires an OpenLIT API key plus organisation/project/environment headers for signal routing.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricParams'
      responses:
        '200':
          description: A list of exceptions and total count.
          content:
            application/json:
              schema:
                type: object
                properties:
                  records:
                    type: array
                    items:
                      type: object
                  total:
                    type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '400':
          $ref: '#/components/responses/BadRequestError'

  /api/telemetry/trace/span/{id}:
    get:
      tags:
        - Telemetry
      summary: Get span detail by ID
      description: Retrieve details of a specific trace span by its ID (along with optional evaluation summary data).
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
        - name: id
          in: path
          required: true
          description: Path parameter. The ID of the span.
          schema:
            type: string
      responses:
        '200':
          description: Span details retrieved successfully.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '400':
          $ref: '#/components/responses/BadRequestError'

  /api/telemetry/trace/trace/{id}:
    get:
      tags:
        - Telemetry
      summary: Get trace detail by Trace ID
      description: Retrieve details of a trace (such as its root span or transaction info) using the Trace ID.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
        - name: id
          in: path
          required: true
          description: Path parameter. The ID of the trace (Trace ID).
          schema:
            type: string
      responses:
        '200':
          description: Trace details retrieved successfully.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '400':
          $ref: '#/components/responses/BadRequestError'

  /api/telemetry/trace/span/{id}/heirarchy:
    get:
      tags:
        - Telemetry
      summary: Get trace span hierarchy tree
      description: Retrieve the tree hierarchy representation of all related spans (e.g. parents, subagents, child operations) associated with a trace span.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
        - name: id
          in: path
          required: true
          description: Path parameter. The ID of the root/anchor span.
          schema:
            type: string
      responses:
        '200':
          description: Span hierarchy tree.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '400':
          $ref: '#/components/responses/BadRequestError'

  /api/api-key:
    get:
      tags:
        - API Keys
      summary: List all API Keys
      description: >-
        Retrieve the API keys for the user's active database configuration,
        with a preview of each key and its access. Requires a signed-in
        session; Bearer API keys are rejected with `403`.
      security:
        - SessionAuth: []
      responses:
        '200':
          description: A list of API Keys.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKey'
        '403':
          description: Bearer API keys can't manage API keys, or the user lacks permission.
    post:
      tags:
        - API Keys
      summary: Generate an API Key
      description: >-
        Create a new API key prefixed with `openlit-` linked to the active
        database configuration. Omit `scopes` for full access. Restricting a
        key with `scopes` requires OpenLIT Enterprise with role-based access
        control; the community edition ignores `scopes`. Requires a signed-in
        session.
      security:
        - SessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  example: my-sdk-key
                scopes:
                  description: Features the key may use. Omit for full access.
                  type: array
                  minItems: 1
                  items:
                    $ref: '#/components/schemas/ApiKeyScope'
                  example: ["ingest", "prompts"]
      responses:
        '200':
          description: API key created successfully. The key is shown only once.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  apiKey:
                    type: string
                    example: openlit-uHpx834Jsa...
                  databaseConfigId:
                    type: string
                    example: db-config-id
                  organisationId:
                    type: string
                    nullable: true
                  projectId:
                    type: string
                    nullable: true
                  environment:
                    type: string
                    example: production
        '400':
          description: Invalid JSON, an invalid name, or an invalid list of features.
        '403':
          description: >-
            Bearer API keys can't manage API keys, the user lacks permission, or
            the edition/license or the user's role doesn't allow the requested access.

  /api/api-key/{id}:
    patch:
      tags:
        - API Keys
      summary: Update API Key access
      description: >-
        Change which features an existing key can use. Send `scopes: null` for
        full access or a list of features to restrict the key. Requires OpenLIT
        Enterprise with role-based access control and a signed-in session; the
        community edition responds with `403`.
      security:
        - SessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Path parameter. API key ID to update.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - scopes
              properties:
                scopes:
                  description: '`null` for full access, or the features the key may use.'
                  type: array
                  nullable: true
                  minItems: 1
                  items:
                    $ref: '#/components/schemas/ApiKeyScope'
                  example: ["prompts", "vault"]
      responses:
        '200':
          description: The key's updated access.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  scopes:
                    type: array
                    nullable: true
                    items:
                      $ref: '#/components/schemas/ApiKeyScope'
        '400':
          description: Invalid JSON or an invalid list of features.
        '401':
          description: No signed-in user.
        '403':
          description: Not available in this edition or license, or the user lacks permission.
        '404':
          description: No such key in the active database configuration.
    delete:
      tags:
        - API Keys
      summary: Delete an API Key
      description: Mark an API key as deleted. Requires a signed-in session.
      security:
        - SessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Path parameter. API key ID to delete.
          schema:
            type: string
      responses:
        '200':
          description: API key deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '400':
          description: Bad request or key not found.

  /api/db-config:
    get:
      summary: List database configurations
      description: Retrieve database configurations the current user has access to.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      responses:
        '200':
          description: Database configurations list.
    post:
      summary: Save database configuration
      description: Create or update a ClickHouse database configuration connection parameters.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - host
                - port
                - username
                - password
              properties:
                host:
                  type: string
                port:
                  type: integer
                username:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: Saved successfully.

  /api/prompt:
    post:
      tags:
        - Prompt Hub
      summary: Create a prompt
      description: Create a new prompt entry or version.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptInput'
      responses:
        '200':
          description: Prompt created successfully.

  /api/prompt/get:
    post:
      tags:
        - Prompt Hub
      summary: Retrieve a prompt by name or ID
      description: Retrieve details of a prompt version.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        '200':
          description: Prompt details.

  /api/prompt/get-compiled:
    get:
      tags:
        - Prompt Hub
      summary: Fetch compiled prompt
      description: Fetch and compile a prompt by name with dynamic variable interpolation. Prefer project/environment signal routing for the intelligence ClickHouse; existing API-key-only clients and optional `x-openlit-database-config-id` remain supported.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectIdOptional'
        - $ref: '#/components/parameters/OpenLitEnvironmentOptional'
        - $ref: '#/components/parameters/OpenLitDatabaseConfigId'
        - name: name
          in: query
          required: true
          description: Query parameter. Prompt template identifier name.
          schema:
            type: string
      responses:
        '200':
          description: Compiled prompt text.

  /api/vault/get-secrets:
    get:
      tags:
        - Secret Vault
      summary: Fetch secrets from Vault
      description: Safely retrieve API keys or credentials stored in the OpenLIT Vault. Prefer project/environment signal routing; existing API-key-only clients and optional `x-openlit-database-config-id` remain supported.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectIdOptional'
        - $ref: '#/components/parameters/OpenLitEnvironmentOptional'
        - $ref: '#/components/parameters/OpenLitDatabaseConfigId'
      responses:
        '200':
          description: Key-value secrets retrieved.

  /api/rule-engine/evaluate:
    post:
      tags:
        - Rule Engine
      summary: Evaluate rule engine config
      description: Evaluate rules (e.g. redaction, prompts, guardrails) against inputs. Prefer project/environment signal routing; existing API-key-only clients and optional `x-openlit-database-config-id` remain supported.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectIdOptional'
        - $ref: '#/components/parameters/OpenLitEnvironmentOptional'
        - $ref: '#/components/parameters/OpenLitDatabaseConfigId'
      responses:
        '200':
          description: Rules evaluated.

  /api/evaluation/offline:
    post:
      tags:
        - Evaluation Engine
      summary: Run offline LLM evaluation
      description: Run LLM evaluation (e.g. toxicity, hallucination, bias, pii) on user-provided prompt and response. Requires an OpenLIT API key.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfflineEvaluationInput'
      responses:
        '200':
          description: Evaluation results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfflineEvaluationResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '400':
          $ref: '#/components/responses/BadRequestError'

  /api/controller/poll:
    post:
      tags:
        - Controller
      summary: Controller poll heartbeat
      description: Heartbeat and state synchronization endpoint for OpenLIT controllers.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      responses:
        '200':
          description: Acknowledged.


  /api/chat/improvement/{spanId}:
    get:
      tags:
        - AI Analysis
      summary: Get AI Analysis runs for a trace or span
      description: |
        Retrieve saved AI Analysis runs for a trace hierarchy (`scope=trace`) or a single span (`scope=span`).
        Requires an OpenLIT API key. Pass organisation, project, environment, and optionally `traceId`.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
        - name: spanId
          in: path
          required: true
          schema:
            type: string
          description: Path parameter. Anchor span ID used to resolve the analysis target.
        - name: scope
          in: query
          required: false
          schema:
            type: string
            enum: [trace, span]
            default: trace
          description: Query parameter. Analyze the full hierarchy (`trace`) or only the given span (`span`).
        - name: traceId
          in: query
          required: false
          schema:
            type: string
          description: Query parameter. Optional Trace ID to disambiguate the hierarchy lookup.
      responses:
        '200':
          description: Saved analysis runs for the target.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiAnalysisRunsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
    post:
      tags:
        - AI Analysis
      summary: Run AI Analysis for a trace or span
      description: |
        Start a streaming AI Analysis run for a trace hierarchy or span.
        Returns an NDJSON/text stream of progress and completed dimension findings.
        Requires Chat Settings (provider + Vault API key) and an intelligence ClickHouse connector.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
        - name: spanId
          in: path
          required: true
          description: Path parameter. Anchor span ID used to resolve the analysis target.
          schema:
            type: string
        - name: scope
          in: query
          required: false
          description: Query parameter. Analyze the full hierarchy (`trace`) or only the given span (`span`).
          schema:
            type: string
            enum: [trace, span]
            default: trace
        - name: traceId
          in: query
          required: false
          description: Query parameter. Optional Trace ID to disambiguate the hierarchy lookup.
          schema:
            type: string
      responses:
        '200':
          description: Streaming analysis progress and results.
          content:
            text/plain:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/chat/config:
    get:
      tags:
        - Ask Otter
      summary: Get Ask Otter chat configuration
      description: Return the organisation chat provider/model/Vault binding (API key redacted).
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      responses:
        '200':
          description: Chat configuration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ChatConfig'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
    post:
      tags:
        - Ask Otter
      summary: Upsert Ask Otter chat configuration
      description: Save the AI provider, model, and Vault secret used by Ask Otter and AI Analysis.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [provider, model, vaultId]
              properties:
                provider:
                  type: string
                  example: openai
                model:
                  type: string
                  example: gpt-4o
                vaultId:
                  type: string
                  description: Vault secret ID that stores the provider API key.
                meta:
                  type: string
                  description: Optional JSON string of provider-specific metadata.
                  example: '{}'
      responses:
        '200':
          description: Configuration saved.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/chat/conversation:
    get:
      tags:
        - Ask Otter
      summary: List Ask Otter conversations
      description: List chat conversations for the current user.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      responses:
        '200':
          description: Conversation list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChatConversation'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
    post:
      tags:
        - Ask Otter
      summary: Create an Ask Otter conversation
      description: Create a new conversation with optional title, provider, and model.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example: Investigate high cost traces
                provider:
                  type: string
                  example: openai
                model:
                  type: string
                  example: gpt-4o
      responses:
        '200':
          description: Created conversation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ChatConversation'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/chat/conversation/{id}:
    get:
      tags:
        - Ask Otter
      summary: Get conversation with messages
      description: Retrieve a conversation and its message history.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
        - name: id
          in: path
          required: true
          description: Path parameter. Conversation ID.
          schema:
            type: string
      responses:
        '200':
          description: Conversation and messages.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
    delete:
      tags:
        - Ask Otter
      summary: Delete a conversation
      description: Delete a conversation and its messages.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
        - name: id
          in: path
          required: true
          description: Path parameter. Conversation ID to delete.
          schema:
            type: string
      responses:
        '200':
          description: Conversation deleted.
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/chat/message:
    post:
      tags:
        - Ask Otter
      summary: Send an Ask Otter message
      description: |
        Stream an assistant reply for a conversation. Returns NDJSON events
        (`delta`, `step`, `done`, `error`). Requires an OpenLIT API key and Chat Settings.
        Used by the Chat page, Memory Ask Otter panel, and Try in Chat from AI Analysis.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [conversationId, content]
              properties:
                conversationId:
                  type: string
                content:
                  type: string
                  example: Analyze the slowest traces from the last 24 hours
      responses:
        '200':
          description: NDJSON stream of assistant tokens and tool steps.
          content:
            application/x-ndjson:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/chat/message/execute:
    post:
      tags:
        - Ask Otter
      summary: Execute validated SQL from Ask Otter
      description: |
        Run a read-only SQL query proposed by Ask Otter against the intelligence ClickHouse connector.
        Returns 409 when the active environment is not routed to a ClickHouse intelligence source.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query]
              properties:
                messageId:
                  type: string
                  description: Optional chat message ID to attach query results to.
                query:
                  type: string
                  example: SELECT SpanName, Duration FROM otel_traces LIMIT 10
      responses:
        '200':
          description: Query rows and execution stats.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  stats:
                    type: object
                    properties:
                      rowsRead:
                        type: integer
                      executionTimeMs:
                        type: integer
                      bytesRead:
                        type: integer
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: Native SQL chat unavailable for the routed intelligence source.

  /api/chat/message/save-widget:
    post:
      tags:
        - Ask Otter
      summary: Save an Ask Otter query as a dashboard widget
      description: Persist a validated chat SQL query as a dashboard widget.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title, type, query]
              properties:
                title:
                  type: string
                description:
                  type: string
                type:
                  type: string
                  example: table
                query:
                  type: string
                properties:
                  type: object
                boardId:
                  type: string
      responses:
        '200':
          description: Widget saved.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/chat/usage:
    get:
      tags:
        - Ask Otter
      summary: Get Ask Otter usage stats
      description: Aggregate token and cost usage for Otter chat and analysis runs.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
        - name: start
          in: query
          required: false
          description: Query parameter. Inclusive start of the usage window (ISO-8601).
          schema:
            type: string
            format: date-time
        - name: end
          in: query
          required: false
          description: Query parameter. Inclusive end of the usage window (ISO-8601).
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Usage summary.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/prompt/improve:
    post:
      tags:
        - Prompt Hub
      summary: Improve a prompt with Otter
      description: |
        Ask Otter to propose precise prompt edits. Requires an OpenLIT API key and Chat Settings.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                prompt:
                  type: string
                promptId:
                  type: string
                  description: Optional Prompt Hub ID when improving a saved prompt.
                criteria:
                  type: array
                  items:
                    type: string
                  description: Optional review criteria override.
      responses:
        '200':
          description: Improvement suggestions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      suggestions:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            dimension:
                              type: string
                            rationale:
                              type: string
                            original:
                              type: string
                            replacement:
                              type: string
                      provider:
                        type: string
                      model:
                        type: string
                      criteria:
                        type: array
                        items:
                          type: string
                      usage:
                        type: object
                        properties:
                          promptTokens:
                            type: integer
                          completionTokens:
                            type: integer
                          cost:
                            type: number
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/scanners:
    get:
      tags:
        - Scanner
      summary: List scanner connectors and scan jobs
      description: |
        Return scanner connectors for the current project and environment, including
        recent scan jobs and their findings. Use this to read the data of a scan after
        `POST /api/scanners/{id}/scan`. Jobs are environment-scoped. Secrets are never
        returned.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
      responses:
        '200':
          description: Scanner connectors with recent jobs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScannerListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/scanners/{id}/scan:
    post:
      tags:
        - Scanner
      summary: Run a scanner job
      description: |
        Start a Trustabl scan for the connector. Missing body fields fall back to the
        connector defaults. The scan target must be an `https://github.com/owner/repo`
        URL (optional `/tree/<ref>`). Local filesystem paths are rejected.

        The response includes the finished job and its findings. The request can take
        several minutes (up to 300 seconds). A second scan is rejected while one is
        already running on the same connector. Tokens stay on the connector and must
        not be sent in the body.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
        - name: id
          in: path
          required: true
          description: Scanner connector ID (`scanner:<uuid>`).
          schema:
            type: string
            example: scanner:3f1c9a2b-4d6e-4a11-9c8f-1b2a3c4d5e6f
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScannerScanRequest'
      responses:
        '200':
          description: Scan job result, including findings when the job finished.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScannerScanResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/scanners/findings:
    get:
      tags:
        - Scanner
      summary: Get latest scan findings for a repository
      description: |
        Return the latest succeeded scan in the current project and environment whose
        target matches `repoUrl`. Accepts `https://github.com/owner/repo`, `.git`,
        `/tree/<ref>`, and `[email protected]:owner/repo` forms. Medium+ findings are
        listed first (up to 25). When no scan matches, `matched` is false.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OpenLitOrganisationId'
        - $ref: '#/components/parameters/OpenLitProjectId'
        - $ref: '#/components/parameters/OpenLitEnvironment'
        - name: repoUrl
          in: query
          required: true
          description: GitHub repository URL from `vcs.repository.url.full` or the scanner target.
          schema:
            type: string
            example: https://github.com/acme/checkout-agent
      responses:
        '200':
          description: Latest matching scan findings, or a miss when none exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScannerFindingsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

components:
  parameters:
    OpenLitOrganisationId:
      name: x-openlit-organisation-id
      in: header
      required: false
      description: |
        Header parameter. Active organisation ID. Send with project and environment so the request
        matches Organisation → Project → Environment signal routing.
      schema:
        type: string
        example: org_01HXYZ
    OpenLitProjectId:
      name: x-openlit-project-id
      in: header
      required: true
      description: |
        Header parameter. Active project ID. Telemetry source bindings are project-scoped; required
        for correct signal routing with `x-openlit-environment`.
      schema:
        type: string
        example: proj_01HXYZ
    OpenLitEnvironment:
      name: x-openlit-environment
      in: header
      required: true
      description: |
        Header parameter. Active project environment (for example `production` or `staging`).
        Required for signal routing (traces/logs/metrics/intelligence connectors),
        AI Analysis, Ask Otter SQL, and scanner jobs. Defaults to `production` on some routes
        when omitted, which may hit the wrong source.
      schema:
        type: string
        example: production
    OpenLitProjectIdOptional:
      name: x-openlit-project-id
      in: header
      required: false
      description: |
        Header parameter. Preferred with `x-openlit-environment` for signal routing. When omitted,
        the API key's bound database config project is used for routing.
      schema:
        type: string
        example: proj_01HXYZ
    OpenLitEnvironmentOptional:
      name: x-openlit-environment
      in: header
      required: false
      description: |
        Header parameter. Preferred for signal routing. When omitted, SDK endpoints fall back to
        the API key's bound database config (legacy).
      schema:
        type: string
        example: production
    OpenLitDatabaseConfigId:
      name: x-openlit-database-config-id
      in: header
      required: false
      description: |
        Header parameter. SDK-facing endpoints only. Optional explicit ClickHouse database config.
        Must belong to the same project as the API key. Prefer signal routing
        (`x-openlit-project-id` + `x-openlit-environment`) instead.
      schema:
        type: string
        example: dbcfg_01HXYZ
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: OPENLIT_API_KEY
      description: |
        Required. Bearer token format (`Authorization: Bearer openlit-...`).
        The key binds a database configuration; clients do not need to send
        `x-openlit-database-config-id`.
    SessionAuth:
      type: apiKey
      in: cookie
      name: next-auth.session-token
      description: Signed-in OpenLIT browser session.

  schemas:
    TimeLimit:
      type: object
      required:
        - start
        - end
        - type
      properties:
        start:
          type: string
          format: date-time
          example: '2026-07-01T00:00:00.000Z'
        end:
          type: string
          format: date-time
          example: '2026-07-02T00:00:00.000Z'
        type:
          type: string
          enum: [24H, 7D, 1M, 3M, CUSTOM]
          example: 24H

    MetricParams:
      type: object
      required:
        - timeLimit
      properties:
        timeLimit:
          $ref: '#/components/schemas/TimeLimit'
        limit:
          type: integer
          default: 25
          example: 50
        offset:
          type: integer
          default: 0
          example: 0
        selectedConfig:
          type: object
          description: "Filters telemetry records by matching key-value criteria."
          properties:
            models:
              type: array
              description: "Filter telemetry by model names (e.g. ['gpt-4o', 'claude-3-5-sonnet'])."
              items:
                type: string
              example: ["gpt-4o", "claude-3-5-sonnet"]
            providers:
              type: array
              description: "Filter telemetry by provider names (e.g. ['openai', 'anthropic', 'cohere', 'ollama'])."
              items:
                type: string
              example: ["openai", "anthropic"]
            serviceNames:
              type: array
              description: "Filter telemetry by service names (e.g. ['web-app', 'backend-api'])."
              items:
                type: string
              example: ["web-app"]
            environments:
              type: array
              description: "Filter telemetry by deployment environment names (e.g. ['production', 'staging'])."
              items:
                type: string
              example: ["production"]
            severities:
              type: array
              description: "Filter logs by severity levels (e.g. ['INFO', 'ERROR', 'WARN'])."
              items:
                type: string
              example: ["ERROR", "WARN"]
        sorting:
          type: object
          description: "Defines the sorting column and order for returned records."
          properties:
            type:
              type: string
              description: "Field name to sort by (e.g. Timestamp, cost, duration, prompt_tokens, completion_tokens, total_tokens)."
              example: Timestamp
            direction:
              type: string
              description: "Sort order direction."
              enum: [asc, desc]
              example: desc

    PromptInput:
      type: object
      required:
        - name
        - prompt
      properties:
        name:
          type: string
        prompt:
          type: string
        version:
          type: string
        status:
          type: string
        tags:
          type: array
          items:
            type: string
        metaProperties:
          type: object

    ApiKey:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        apiKeyPreview:
          type: string
          example: openlit-uHpx…x7Qp2A
        createdAt:
          type: string
          format: date-time
        createdByUser:
          type: object
          properties:
            email:
              type: string
        scopes:
          description: '`null` for full access, otherwise the features the key may use.'
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ApiKeyScope'

    ApiKeyScope:
      type: string
      description: >-
        A feature an API key can use: `ingest` (OTLP telemetry ingestion),
        `telemetry` (`/api/telemetry/*`, `/api/metrics/*`), `prompts`
        (`/api/prompt/*`), `vault` (`/api/vault/*`), `rule_engine`
        (`/api/rule-engine/*`), `evaluation` (`/api/evaluation/*`), `chat`
        (`/api/chat/*`), `controller` (`/api/controller/*`), `db_config`
        (`/api/db-config*`).
      enum:
        - ingest
        - telemetry
        - prompts
        - vault
        - rule_engine
        - evaluation
        - chat
        - controller
        - db_config

    OfflineEvaluationInput:
      type: object
      required:
        - prompt
        - response
      properties:
        prompt:
          type: string
          description: "The prompt text to evaluate."
          example: "I need to reset my password, my email is [email protected]"
        response:
          type: string
          description: "The LLM generated response to evaluate."
          example: "I can help with that. Please verify your identity."
        contexts:
          type: array
          description: "Retrieved context document texts used by the LLM."
          items:
            type: string
          example: ["User password reset procedure document."]
        eval_types:
          type: array
          description: "Scorers to execute. Can be toxicity, hallucination, bias, pii."
          items:
            type: string
          example: ["toxicity", "pii"]
        threshold_score:
          type: number
          default: 0.5
          description: "Minimum score required to trigger validation flags."
          example: 0.5
        store_results:
          type: boolean
          default: true
          description: "Persist the evaluation metrics run results to ClickHouse."
          example: true
        run_id:
          type: string
          description: "Optional external execution or batch tracking ID."
          example: "run-998877"
        metadata:
          type: object
          description: "Custom metadata key-value properties dictionary (max 20 entries)."
          additionalProperties:
            type: string
          example: { "environment": "production", "version": "1.0" }
        attributes:
          type: object
          description: "Custom payload attributes dictionary."

    OfflineEvaluationResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        evaluations:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                example: toxicity
              score:
                type: number
                example: 0.1
              verdict:
                type: string
                example: passed
              classification:
                type: string
                example: safe
              explanation:
                type: string
                example: "No toxic language detected in the input."
        context_applied:
          type: boolean
          example: false
        metadata:
          type: object

    AiAnalysisRunsResponse:
      type: object
      properties:
        data:
          type: object
          nullable: true
          properties:
            rootSpanId:
              type: string
            runs:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  scope:
                    type: string
                    enum: [trace, span]
                  summary:
                    type: string
                  createdAt:
                    type: string
                    format: date-time

    ChatConfig:
      type: object
      properties:
        provider:
          type: string
          example: openai
        model:
          type: string
          example: gpt-4o
        vaultId:
          type: string
        meta:
          type: string

    ChatConversation:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        provider:
          type: string
        model:
          type: string
        totalMessages:
          type: integer
        totalPromptTokens:
          type: integer
        totalCompletionTokens:
          type: integer
        totalCost:
          type: number
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    ScannerFinding:
      type: object
      properties:
        id:
          type: string
        ruleId:
          type: string
          example: MCP-004
        severity:
          type: string
          example: medium
        category:
          type: string
        scope:
          type: string
        toolName:
          type: string
        path:
          type: string
          example: src/mcp/server.ts
        line:
          type: integer
        endLine:
          type: integer
        title:
          type: string
        message:
          type: string
        helpUrl:
          type: string
        fix:
          type: string
        confidence:
          type: string

    ScannerReportSummary:
      type: object
      properties:
        scanId:
          type: string
        repo:
          type: string
        overallScore:
          type: number
          example: 0.72
        rulesSource:
          type: string
          example: production
        rulesVersion:
          type: string
        languages:
          type: array
          items:
            type: string
        sdks:
          type: array
          items:
            type: string
        toolCount:
          type: integer
        agentCount:
          type: integer
        mcpCount:
          type: integer
        vulnerabilityCount:
          type: integer
        secretCount:
          type: integer
        filesParsed:
          type: integer
        noAgentSurfaces:
          type: boolean

    ScannerScanParams:
      type: object
      description: Resolved Trustabl scan flags persisted on the job. Secrets are never included.
      properties:
        detectors:
          type: string
          example: claude_sdk,mcp
        strict:
          type: boolean
        secretScan:
          type: boolean
        vulnScan:
          type: boolean
        licenseScan:
          type: boolean
        requireSigned:
          type: boolean
        rulesRepo:
          type: string
        rulesRef:
          type: string
        rulesSource:
          type: string
          enum: [production, staging, git]
        noRulesUpdate:
          type: boolean
        verbose:
          type: boolean

    ScannerScanRequest:
      type: object
      description: |
        Optional per-run overrides. Omitted fields use the scanner connector defaults.
        Do not send GitHub tokens in this body.
      properties:
        target:
          type: string
          description: GitHub repository URL. Falls back to the connector setting.
          example: https://github.com/acme/checkout-agent
        ref:
          type: string
          description: Branch, tag, or commit. Falls back to the URL `/tree/<ref>` or the connector setting.
          example: main
        detectors:
          type: string
        strict:
          type: boolean
        secretScan:
          type: boolean
        vulnScan:
          type: boolean
        licenseScan:
          type: boolean
        requireSigned:
          type: boolean
        rulesRepo:
          type: string
        rulesRef:
          type: string
        rulesSource:
          type: string
          enum: [environment, production, staging, git]
        noRulesUpdate:
          type: boolean
        verbose:
          type: boolean

    ScannerJob:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [queued, running, succeeded, failed, runtime-missing]
        target:
          type: string
          example: https://github.com/acme/checkout-agent
        ref:
          type: string
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
        durationMs:
          type: integer
        exitCode:
          type: integer
        error:
          type: string
        findingCount:
          type: integer
        mediumPlusCount:
          type: integer
        findings:
          type: array
          items:
            $ref: '#/components/schemas/ScannerFinding'
        params:
          $ref: '#/components/schemas/ScannerScanParams'
        report:
          $ref: '#/components/schemas/ScannerReportSummary'
        cliVersion:
          type: string
          example: v0.1.8

    ScannerConnector:
      type: object
      properties:
        id:
          type: string
          example: scanner:3f1c9a2b-4d6e-4a11-9c8f-1b2a3c4d5e6f
        name:
          type: string
        type:
          type: string
          example: trustabl
        environment:
          type: string
          example: production
        settings:
          type: string
          description: JSON object of non-secret connector settings.
        hasSecret:
          type: boolean
        category:
          type: string
          example: scanner
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/ScannerJob'

    ScannerListResponse:
      type: object
      properties:
        connectors:
          type: array
          items:
            $ref: '#/components/schemas/ScannerConnector'

    ScannerScanResponse:
      type: object
      properties:
        connector:
          $ref: '#/components/schemas/ScannerConnector'
        job:
          $ref: '#/components/schemas/ScannerJob'

    ScannerFindingsResponse:
      type: object
      properties:
        matched:
          type: boolean
        repoKey:
          type: string
          nullable: true
          example: github.com/acme/checkout-agent
        connectorId:
          type: string
        connectorName:
          type: string
        jobId:
          type: string
        target:
          type: string
        ref:
          type: string
        scannedAt:
          type: string
          format: date-time
        findingCount:
          type: integer
        mediumPlusCount:
          type: integer
        findings:
          type: array
          items:
            $ref: '#/components/schemas/ScannerFinding'
        url:
          type: string
          description: Scanner workspace deep link (`/scanner?connectorId=&jobId=`).
          example: /scanner?connectorId=scanner%3Aabc&jobId=job%3A1

  responses:
    UnauthorizedError:
      description: Authentication failed or credentials missing.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Unauthorized
    BadRequestError:
      description: Invalid request parameters or body.
      content:
        application/json:
          schema:
            type: string
            example: Start date or End date missing!