Clarity Copilot Audits API

openapi: 3.2.0
info:
  title: Fast Copilot Audits API
  version: 0.1.0
tags:
- name: copilot_audits
paths:
  /api/v1/copilot-audits/sessions/{provider_session_id}/bundle:
    get:
      tags:
      - copilot_audits
      summary: Get Bundle
      description: 'Everything ``fetch_session.py`` writes except the events (page them with ``/events``).


        The session as the provider stores it, the agent snapshot it ran (system prompt, tools, model,

        advisor roster), its threads, the agent''s latest version, where it lives in Clarity, and the

        links of earlier audits of the same conversation. Credentials are masked (``redactions``).'
      operationId: get_bundle_api_v1_copilot_audits_sessions__provider_session_id__bundle_get
      security:
      - HTTPBearer: []
      parameters:
      - name: provider_session_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^sesn_[A-Za-z0-9]+$
          description: Provider session id (sesn_…)
          title: Provider Session Id
        description: Provider session id (sesn_…)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditBundle'
        '401':
          description: Missing or invalid audit PSK
        '404':
          description: No open audit for this session
        '409':
          description: The conversation is running again; it is audited once it settles
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/copilot-audits/sessions/{provider_session_id}/events:
    get:
      tags:
      - copilot_audits
      summary: Get Events
      description: One page of the session's events, oldest first, credentials masked.
      operationId: get_events_api_v1_copilot_audits_sessions__provider_session_id__events_get
      security:
      - HTTPBearer: []
      parameters:
      - name: provider_session_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^sesn_[A-Za-z0-9]+$
          description: Provider session id (sesn_…)
          title: Provider Session Id
        description: Provider session id (sesn_…)
      - name: page
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
          description: '`next_page` of the previous call'
          title: Page
        description: '`next_page` of the previous call'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEventsPage'
        '401':
          description: Missing or invalid audit PSK
        '404':
          description: No open audit for this session
        '409':
          description: The conversation is running again; it is audited once it settles
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/copilot-audits/sessions/{provider_session_id}/result:
    post:
      tags:
      - copilot_audits
      summary: Post Result
      description: 'Record the audit''s outcome: ``posted`` (verdict, outcome, Slack permalink) or ``failed``.'
      operationId: post_result_api_v1_copilot_audits_sessions__provider_session_id__result_post
      security:
      - HTTPBearer: []
      parameters:
      - name: provider_session_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^sesn_[A-Za-z0-9]+$
          description: Provider session id (sesn_…)
          title: Provider Session Id
        description: Provider session id (sesn_…)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuditResultRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditResultResponse'
        '401':
          description: Missing or invalid audit PSK
        '404':
          description: No open (or expired) audit with this id for this session
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PreviousAudit:
      properties:
        slack_permalink:
          type: string
          title: Slack Permalink
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
        verdict:
          anyOf:
          - type: string
          - type: 'null'
          title: Verdict
        outcome:
          anyOf:
          - type: string
          - type: 'null'
          title: Outcome
      type: object
      required:
      - slack_permalink
      title: PreviousAudit
    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
    AuditResultResponse:
      properties:
        audit_id:
          type: integer
          title: Audit Id
        provider_session_id:
          type: string
          title: Provider Session Id
        status:
          type: string
          title: Status
      type: object
      required:
      - audit_id
      - provider_session_id
      - status
      title: AuditResultResponse
    AuditResultRequest:
      properties:
        audit_id:
          type: integer
          title: Audit Id
          description: The `audit_id` the bundle returned.
        status:
          type: string
          enum:
          - posted
          - failed
          title: Status
        verdict:
          anyOf:
          - type: string
            enum:
            - passes
            - fails
          - type: 'null'
          title: Verdict
        outcome:
          anyOf:
          - type: string
            enum:
            - 'yes'
            - partly
            - 'no'
          - type: 'null'
          title: Outcome
        never_rules:
          items:
            type: string
            pattern: ^N[1-6]$
          type: array
          title: Never Rules
        violations:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Violations
        slack_permalink:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Slack Permalink
        error:
          anyOf:
          - type: string
            maxLength: 4000
          - type: 'null'
          title: Error
      type: object
      required:
      - audit_id
      - status
      title: AuditResultRequest
    AuditEventsPage:
      properties:
        events:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Events
        next_page:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Page
          description: Pass back as `page`; null on the last page.
        redactions:
          additionalProperties:
            type: integer
          type: object
          title: Redactions
      type: object
      required:
      - events
      title: AuditEventsPage
    VocContext:
      properties:
        env:
          anyOf:
          - type: string
          - type: 'null'
          title: Env
        project_id:
          type: integer
          title: Project Id
        project_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Name
        conversation_id:
          type: integer
          title: Conversation Id
          description: managed_agent_sessions.id
        conversation_url:
          type: string
          title: Conversation Url
        user_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: User Id
        surface:
          anyOf:
          - type: string
          - type: 'null'
          title: Surface
        status:
          type: string
          title: Status
        turn_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Turn Count
        warmup_cutoff_event_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Warmup Cutoff Event Id
        deleted:
          type: boolean
          title: Deleted
          description: The customer deleted the conversation (soft delete).
          default: false
      type: object
      required:
      - project_id
      - conversation_id
      - conversation_url
      - status
      title: VocContext
      description: Where the conversation lives in Clarity.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AuditBundle:
      properties:
        audit_id:
          type: integer
          title: Audit Id
          description: Send it back with the result.
        session:
          additionalProperties: true
          type: object
          title: Session
          description: The provider session, without its agent snapshot.
        agent:
          additionalProperties: true
          type: object
          title: Agent
          description: The agent snapshot the session ran, without system/tools.
        system_prompt:
          type: string
          title: System Prompt
        tools:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Tools
        threads:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Threads
          description: None when the listing failed.
        latest_agent_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Latest Agent Version
        voc:
          $ref: '#/components/schemas/VocContext'
        previous_audits:
          items:
            $ref: '#/components/schemas/PreviousAudit'
          type: array
          title: Previous Audits
        redactions:
          additionalProperties:
            type: integer
          type: object
          title: Redactions
          description: Secrets masked in this response, by kind.
      type: object
      required:
      - audit_id
      - session
      - agent
      - system_prompt
      - tools
      - voc
      title: AuditBundle
      description: What ``fetch_session.py`` needs, minus the events (paged separately).
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic