Clarity Copilot Audits Admin API

openapi: 3.2.0
info:
  title: Fast Copilot Audits Admin API
  version: 0.1.0
tags:
- name: copilot_audits_admin
paths:
  /api/admin/v1/copilot-audits/dispatch:
    post:
      tags:
      - copilot_audits_admin
      summary: Dispatch
      description: 'Select the settled customer conversations and fire the audit routine once with all of them.


        The scheduled tick sends no body. ``{"dry_run": true}`` shows what would be dispatched (plus

        ``active`` conversations that look stuck) without writing or firing; ``{"session_ids": [...]}``

        audits exactly those conversations. A refused fire still answers 200 with ``fired: false``

        and the rows released, so the Scheduler doesn''t retry against a rate limit.'
      operationId: dispatch_api_admin_v1_copilot_audits_dispatch_post
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/DispatchRequest'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DispatchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    StaleActiveSession:
      properties:
        provider_session_id:
          type: string
          title: Provider Session Id
        project_id:
          type: integer
          title: Project Id
        settled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Settled At
      type: object
      required:
      - provider_session_id
      - project_id
      title: StaleActiveSession
      description: '``active`` with no progress for IDLE_HOURS: likely a missed provider webhook.'
    DispatchedSession:
      properties:
        provider_session_id:
          type: string
          title: Provider Session Id
        project_id:
          type: integer
          title: Project Id
        status:
          type: string
          title: Status
          description: The conversation's status when it was selected.
        turn_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Turn Count
        settled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Settled At
      type: object
      required:
      - provider_session_id
      - project_id
      - status
      title: DispatchedSession
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DispatchRequest:
      properties:
        dry_run:
          type: boolean
          title: Dry Run
          description: 'Return what would be dispatched; write nothing, fire nothing. With `session_ids`, a conversation already audited in its current state is still listed: only the real run skips it.'
          default: false
        session_ids:
          anyOf:
          - items:
              type: string
              pattern: ^sesn_[A-Za-z0-9]+$
            type: array
            maxItems: 500
          - type: 'null'
          title: Session Ids
          description: Audit exactly these conversations, skipping the eligibility rules (trigger='manual'). Ids that already have an open audit are skipped unless `force`; a conversation already audited in its current state is always skipped.
          examples:
          - - sesn_011CZabc
        force:
          type: boolean
          title: Force
          description: Re-dispatch explicit ids even when an audit is already open (never a posted one).
          default: false
        fire:
          type: boolean
          title: Fire
          description: Fire the routine. False only records the rows (for a manual run).
          default: true
      type: object
      title: DispatchRequest
      description: Body of the dispatcher tick. The scheduled tick sends none (all defaults).
    SkippedSession:
      properties:
        provider_session_id:
          type: string
          title: Provider Session Id
        reason:
          type: string
          title: Reason
      type: object
      required:
      - provider_session_id
      - reason
      title: SkippedSession
    DispatchResponse:
      properties:
        skipped:
          anyOf:
          - type: string
            enum:
            - disabled
            - locked
          - type: 'null'
          title: Skipped
          description: 'Set when nothing ran: the feature is off, or another dispatch holds the lock.'
        dry_run:
          type: boolean
          title: Dry Run
          default: false
        sessions:
          items:
            $ref: '#/components/schemas/DispatchedSession'
          type: array
          title: Sessions
        skipped_sessions:
          items:
            $ref: '#/components/schemas/SkippedSession'
          type: array
          title: Skipped Sessions
        stale_active:
          items:
            $ref: '#/components/schemas/StaleActiveSession'
          type: array
          title: Stale Active
          description: Dry runs only.
        fired:
          type: boolean
          title: Fired
          description: Whether the routine accepted the batch.
          default: false
        routine_session_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Routine Session Url
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Why the routine wasn't fired (the rows were released).
      type: object
      title: DispatchResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic