Simple AI Interactions API
The Interactions API from Simple AI — 2 operation(s) for interactions.
The Interactions API from Simple AI — 2 operation(s) for interactions.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/simple-ai:simple-ai-interactions-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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`'