Simple AI Interactions API

openapi: 3.2.0
info:
  title: Public API v1 Interactions API
  description: 'Public API v1 requiring API keys.


    **Timestamps:** All datetime fields in API responses are returned in UTC using ISO 8601 format (e.g., `2024-01-15T14:30:00Z`). When filtering by date parameters, provide timestamps in ISO 8601 format.'
  version: 0.1.0
servers:
- url: https://api.usesimple.ai/api/v1
  description: Production API Server
tags:
- name: Interactions
paths:
  /interactions:
    get:
      tags:
      - Interactions
      summary: List Interactions
      description: 'List all interactions (calls, text conversations, and external-channel interactions) associated with the API key''s account.

        Includes pagination support and filtering by status, modality, transferred state, external-channel inclusion, and creation date.

        Date filters accept ISO 8601 format (e.g., 2024-01-15T09:30:00Z).'
      operationId: list_interactions_interactions_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          default: 1
          title: Page
      - name: page_size
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          default: 20
          title: Page Size
      - name: status
        in: query
        required: false
        schema:
          type: string
          title: Status
        description: Filter by interaction status. Multiple values can be provided separated by commas.
      - name: modality
        in: query
        required: false
        schema:
          type: string
          enum:
          - voice
          - text
          title: Modality
        description: Filter by interaction modality (voice or text)
      - name: agent_id
        in: query
        required: false
        schema:
          type: string
          title: Agent ID
        description: Filter by agent group UUID. Multiple values can be provided separated by commas. Returns interactions from all versions of the specified agent(s).
      - name: agent_version_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
          title: Agent Version ID
        description: Filter by specific agent version UUID. Returns interactions from only the specified agent version.
      - name: transferred
        in: query
        required: false
        schema:
          type: boolean
          title: Transferred
        description: Filter by whether the interaction was transferred
      - name: include_external_channels
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include External Channels
        description: External-channel calls (uploaded or ingested from external sources, grouped as one interaction per session) are excluded by default. Pass `true` to include them alongside native calls and conversations.
      - name: created_at_gte
        in: query
        required: false
        schema:
          type: string
          format: date-time
          title: Created At Greater Than or Equal
        description: Filter interactions created at or after this datetime (ISO 8601 format). For external-channel interactions this compares against the call (leg start) time rather than the returned `created_at` ingestion timestamp.
      - name: created_at_lte
        in: query
        required: false
        schema:
          type: string
          format: date-time
          title: Created At Less Than or Equal
        description: Filter interactions created at or before this datetime (ISO 8601 format). For external-channel interactions this compares against the call (leg start) time rather than the returned `created_at` ingestion timestamp.
      - name: updated_at_gte
        in: query
        required: false
        schema:
          type: string
          format: date-time
          title: Updated At Greater Than or Equal
        description: Filter interactions last updated at or after this datetime (ISO 8601 format). Reflects the last change to the interaction record itself. For external-channel interactions this compares against the underlying session's last update time.
      - name: updated_at_lte
        in: query
        required: false
        schema:
          type: string
          format: date-time
          title: Updated At Less Than or Equal
        description: Filter interactions last updated at or before this datetime (ISO 8601 format).
      - name: sort_by
        in: query
        required: false
        schema:
          type: string
          enum:
          - created_at
          - updated_at
          - started_at
          - ended_at
          - duration
          - status
          default: created_at
          title: Sort By
        description: Field to sort results by
      - name: sort_direction
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
          title: Sort Direction
        description: Sort direction
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /interactions/{uuid}:
    get:
      tags:
      - Interactions
      summary: Get Interaction Details
      description: 'Get details for a specific interaction.

        Only returns interactions associated with the API key''s account.'
      operationId: get_interaction_details_interactions__uuid__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Uuid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionDetailsResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    default: Interaction not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Five9HandoffMetadata:
      type: object
      title: Five9HandoffMetadata
      description: Details of a transfer to Five9.
      properties:
        conversation_id:
          type: string
          title: Conversation ID
          description: The Five9 conversation ID. Use this to correlate with Five9's API.
        tenant_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Tenant Name
          description: The Five9 tenant name used for the transfer.
        campaign_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Campaign Name
          description: The Five9 campaign the conversation was routed to.
        transferred_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Transferred At
          description: When the transfer occurred (ISO 8601).
    InteractionDetailsResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        type:
          type: string
          enum:
          - call
          - conversation
          - email
          - sms
          - external_channel
          title: Type
          description: Identifies whether the interaction is a native call/conversation or an external-channel interaction.
        modality:
          anyOf:
          - $ref: '#/components/schemas/ModalityEnum'
          - type: 'null'
          description: Native interactions return `voice` or `text`. External-channel interactions return `null`.
        language:
          $ref: '#/components/schemas/LanguageEnum'
        from_number:
          anyOf:
          - type: string
            title: From Number
          - type: 'null'
          title: From Number
          description: Phone number for native interactions. External-channel interactions return `null`.
        to_number:
          anyOf:
          - type: string
            title: To Number
          - type: 'null'
          title: To Number
          description: Phone number for native interactions. External-channel interactions return `null`.
        status:
          type: string
          title: Status
        transferred:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Transferred
          description: Indicates if the interaction was transferred. External-channel interactions return `null`.
        handoff_metadata:
          anyOf:
          - $ref: '#/components/schemas/HandoffMetadata'
          - type: 'null'
          title: Handoff Metadata
          description: Metadata about the handoff when the interaction was transferred to an external provider (e.g. Five9). External-channel interactions return `null`.
        direction:
          anyOf:
          - type: string
            title: Direction
          - type: 'null'
          title: Direction
          description: The direction of the interaction (inbound/outbound). External-channel interactions return `null`.
        tags:
          type: array
          title: Tags
          description: Tags associated with the interaction
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              description:
                type: string
              color:
                type: string
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        ended_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Ended At
        duration:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration
        created_at:
          type: string
          format: date-time
          title: Created At
          description: 'For native interactions this is the record creation time. For external-channel interactions this is the underlying session''s ingestion time. Note: `created_at` sorting and the `created_at_gte`/`created_at_lte` filters order external-channel interactions by their call (leg start) time, not by this ingestion timestamp, so a returned `created_at` value may fall outside the requested filter window.'
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Time the interaction record was last updated. For external-channel interactions this is the underlying session's last update time.
        external_identifiers:
          anyOf:
          - type: object
            additionalProperties:
              type: string
          - type: 'null'
          title: External Identifiers
          description: External identifiers associated with the interaction
        params:
          anyOf:
          - type: object
            additionalProperties:
              type: string
          - type: 'null'
          title: Params
          description: Parameters associated with the interaction
        transcripts:
          items:
            anyOf:
            - $ref: '#/components/schemas/CallTranscriptResponse'
            - $ref: '#/components/schemas/ExternalChannelTranscriptResponse'
          type: array
          title: Transcripts
          description: Transcript item shape depends on the interaction `type`.
        recording_presigned_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Recording Presigned Url
          description: Presigned URL for the recording (for voice modality only). External-channel interactions return `null`.
        answered_by:
          anyOf:
          - $ref: '#/components/schemas/AnsweredByEnum'
          - type: 'null'
          title: Answered By
          description: Answered-by classification for native voice interactions. External-channel interactions return `null`.
        analyzers:
          type: array
          title: Analyzers
          description: List of analyzers configured for this interaction
          items:
            $ref: '#/components/schemas/AnalyzerResponse'
        analysis_results:
          type: array
          title: Analysis Results
          description: Results from analyzers that have completed
          items:
            $ref: '#/components/schemas/AnalysisResultResponse'
        summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary
          description: The summary of the interaction if available
        recording_presigned_urls:
          type: array
          items:
            type: string
            format: uri
          description: Presigned URLs for all playable recordings in chronological order. External calls can have multiple recordings per session. URLs expire after one hour. Deleted, excluded, and recordings awaiting required audio redaction are omitted; an empty array means no recordings are currently playable. If URL signing fails for a recording, its URL is omitted and the call data is still returned.
      type: object
      required:
      - id
      - type
      - status
      - started_at
      - created_at
      - updated_at
      - transcripts
      - recording_presigned_urls
      title: InteractionDetailsResponse
    AnsweredByEnum:
      type: string
      enum:
      - voicemail
      - human
      - no_answer
      - unknown
      title: Answered By
      description: Indicates how the call was answered - by a human, voicemail, or if there was no answer
    LanguageEnum:
      type: string
      enum:
      - en
      - es
      - ar
      title: Language
      description: The language to use for the call - English (en) or Spanish (es)
    AnalyzerResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique identifier for the analyzer
        prompt:
          type: string
          title: Prompt
          description: The prompt used for analysis
        output_config:
          type: object
          title: Output Config
          description: Configuration for the expected output format
          properties:
            type:
              type: string
              enum:
              - string
              - boolean
              - datetime
              - object
              description: The type of output expected
            properties:
              type: object
              description: Required when type is 'object'. Defines the structure of the object
              additionalProperties:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                    - string
                    - boolean
                    - datetime
      required:
      - id
      - prompt
      - output_config
      title: AnalyzerResponse
    CallTranscriptResponse:
      properties:
        text:
          anyOf:
          - type: string
          - type: 'null'
          title: Text
        role:
          anyOf:
          - type: string
          - type: 'null'
          title: Role
        timestamp:
          type: number
          title: Timestamp
          description: When the entry was recorded, as a Unix timestamp in seconds
        function_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Function Name
        arguments:
          anyOf:
          - type: object
          - type: 'null'
          title: Arguments
      type: object
      required:
      - text
      - role
      - timestamp
      - function_name
      - arguments
      title: CallTranscriptResponse
    ModalityEnum:
      type: string
      enum:
      - voice
      - text
      title: Modality
      description: The modality of the interaction - voice calls or text conversations
    InteractionListResponse:
      properties:
        interactions:
          items:
            $ref: '#/components/schemas/InteractionDetailsResponse'
          type: array
          title: Interactions
        total_count:
          type: integer
          title: Total Count
        page:
          type: integer
          title: Page
        page_size:
          type: integer
          title: Page Size
        total_pages:
          type: integer
          title: Total Pages
        filters:
          type: object
          properties:
            status:
              anyOf:
              - type: string
              - type: 'null'
              title: Status
            modality:
              anyOf:
              - type: string
                enum:
                - voice
                - text
              - type: 'null'
              title: Modality
            agent_id:
              anyOf:
              - type: string
                format: uuid
              - type: 'null'
              title: Agent ID
            agent_version_id:
              anyOf:
              - type: string
                format: uuid
              - type: 'null'
              title: Agent Version ID
            transferred:
              anyOf:
              - type: boolean
              - type: 'null'
              title: Transferred
            created_at_gte:
              anyOf:
              - type: string
                format: date-time
              - type: 'null'
              title: Created At Greater Than or Equal
            created_at_lte:
              anyOf:
              - type: string
                format: date-time
              - type: 'null'
              title: Created At Less Than or Equal
            updated_at_gte:
              anyOf:
              - type: string
                format: date-time
              - type: 'null'
              title: Updated At Greater Than or Equal
            updated_at_lte:
              anyOf:
              - type: string
                format: date-time
              - type: 'null'
              title: Updated At Less Than or Equal
          title: Filters
        sorting:
          type: object
          properties:
            sort_by:
              type: string
              title: Sort By
            sort_direction:
              type: string
              title: Sort Direction
          title: Sorting
      type: object
      required:
      - interactions
      - total_count
      - page
      - page_size
      - total_pages
      title: InteractionListResponse
    ExternalChannelTranscriptResponse:
      properties:
        speaker:
          type: string
          title: Speaker
        text:
          type: string
          title: Text
        start:
          type: number
          title: Start
        end:
          type: number
          title: End
        confidence:
          type: number
          title: Confidence
        channel:
          type: string
          title: Channel
      type: object
      required:
      - speaker
      - text
      - start
      - end
      - confidence
      title: ExternalChannelTranscriptResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    HandoffMetadata:
      type: object
      title: HandoffMetadata
      description: Metadata about a transfer to an external provider.
      properties:
        five9:
          anyOf:
          - $ref: '#/components/schemas/Five9HandoffMetadata'
          - type: 'null'
          title: Five9
          description: Five9 handoff details. Present when the transfer was to Five9.
    AnalysisResultResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique identifier for the analysis result
        analyzer_id:
          type: string
          format: uuid
          title: Analyzer Id
          description: Identifier of the analyzer that produced this result
        prompt:
          type: string
          title: Prompt
          description: The prompt used for analysis
        output_config:
          type: object
          title: Output Config
          description: Configuration for the expected output format
        result:
          type: object
          title: Result
          description: The analysis result, structure depends on the output_config
      required:
      - id
      - analyzer_id
      - prompt
      - output_config
      - result
      title: AnalysisResultResponse
  securitySchemes:
    APIKeyHeader:
      type: http
      scheme: bearer
      description: 'Your API key, sent as `Authorization: Bearer YOUR_API_KEY`'