openapi: 3.1.0
info:
  title: Convai Chat History API
  version: "1.0"
  description: |
    Retrieve historical conversation sessions and full interaction transcripts
    for Convai characters. Used for analytics, debugging, evaluation, and
    auditing of NPC conversations. Scale tier and above.
servers:
- url: https://api.convai.com
security:
- ConvaiApiKey: []
paths:
  /character/chat-history/list-sessions:
    post:
      summary: List Character Sessions
      operationId: listSessions
      tags: [Chat History]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [charID]
              properties:
                charID: { type: string }
                limit: { type: integer, default: 50 }
      responses:
        '200':
          description: Session list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    sessionID: { type: string }
                    startTime: { type: string, format: date-time }
                    duration: { type: integer }
                    messageCount: { type: integer }
  /character/chat-history/get-session:
    post:
      summary: Get Session Transcript
      operationId: getSession
      tags: [Chat History]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [charID, sessionID]
              properties:
                charID: { type: string }
                sessionID: { type: string }
      responses:
        '200':
          description: Session transcript
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionID: { type: string }
                  interactions:
                    type: array
                    items:
                      type: object
                      properties:
                        role: { type: string, enum: [user, character] }
                        text: { type: string }
                        timestamp: { type: string, format: date-time }
components:
  securitySchemes:
    ConvaiApiKey:
      type: apiKey
      in: header
      name: CONVAI-API-KEY