openapi: 3.1.0
info:
contact:
email: support@telnyx.com
description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
title: Telnyx Access Tokens Assistants API
version: 2.0.0
x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Configure AI assistant specifications
name: Assistants
paths:
/ai/assistants:
get:
description: Retrieve a list of all AI Assistants configured by the user.
operationId: get_assistants_public_assistants_get
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantsListData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: List assistants
tags:
- Assistants
x-latency-category: responsive
post:
description: Create a new AI Assistant.
operationId: create_new_assistant_public_assistants_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAssistantRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/inference-embedding_Assistant'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Create an assistant
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/import:
post:
description: Import assistants from external providers. Any assistant that has already been imported will be overwritten with its latest version from the importing provider.
operationId: import_assistants_public_assistants_import_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImportAssistantsRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantsListData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Import assistants from external provider
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/tags:
get:
operationId: get_all_assistant_tags
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TagsResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get All Tags
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/tests:
get:
description: Retrieves a paginated list of assistant tests with optional filtering capabilities
operationId: get_assistant_tests_public_assistants_tests_get
parameters:
- description: Filter tests by test suite name
in: query
name: test_suite
required: false
schema:
description: Filter tests by test suite name
title: Test Suite
type: string
- description: Filter tests by communication channel (e.g., 'web_chat', 'sms')
in: query
name: telnyx_conversation_channel
required: false
schema:
description: Filter tests by communication channel (e.g., 'web_chat', 'sms')
title: Telnyx Conversation Channel
type: string
- description: Filter tests by destination (phone number, webhook URL, etc.)
in: query
name: destination
required: false
schema:
description: Filter tests by destination (phone number, webhook URL, etc.)
title: Destination
type: string
- description: 'Consolidated page parameter (deepObject style). Originally: page[size], page[number]'
explode: true
in: query
name: page
schema:
properties:
number:
default: 1
description: Page number to retrieve (1-based indexing)
minimum: 1
title: Page[Number]
type: integer
size:
default: 20
description: Number of tests to return per page (1-100)
maximum: 100
minimum: 1
title: Page[Size]
type: integer
type: object
style: deepObject
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedAssistantTestList'
description: Returns paginated test list with metadata for navigation and filtering
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: List assistant tests with pagination
tags:
- Assistants
x-latency-category: responsive
post:
description: Creates a comprehensive test configuration for evaluating AI assistant performance
operationId: create_assistant_test_public_assistants_tests_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAssistantTestRequest'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantTestResponse'
description: Returns the created test configuration with assigned test ID
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Create a new assistant test
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/tests/test-suites:
get:
description: Retrieves a list of all distinct test suite names available to the current user
operationId: fetch_test_suites_public_assistants_tests_test_suites_get
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TestSuitesResponse'
description: Returns an array of unique test suite names for filtering and organization
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get all test suite names
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/tests/test-suites/{suite_name}/runs:
get:
description: Retrieves paginated history of test runs for a specific test suite with filtering options
operationId: get_test_suite_runs_for_test_public_assistants_tests_test_suites__suite_name__runs_get
parameters:
- in: path
name: suite_name
required: true
schema:
title: Suite Name
type: string
- description: Filter runs by execution status (pending, running, completed, failed, timeout)
in: query
name: status
required: false
schema:
description: Filter runs by execution status (pending, running, completed, failed, timeout)
title: Status
type: string
- description: Filter runs by specific suite execution batch ID
in: query
name: test_suite_run_id
required: false
schema:
description: Filter runs by specific suite execution batch ID
title: Test Suite Run Id
type: string
- description: 'Consolidated page parameter (deepObject style). Originally: page[size], page[number]'
explode: true
in: query
name: page
schema:
properties:
number:
default: 1
description: Page number to retrieve (1-based indexing)
minimum: 1
title: Page[Number]
type: integer
size:
default: 20
description: Number of test runs to return per page (1-100)
maximum: 100
minimum: 1
title: Page[Size]
type: integer
type: object
style: deepObject
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedTestRunList'
description: Returns paginated list of test runs within the specified suite
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get test suite run history
tags:
- Assistants
x-latency-category: responsive
post:
description: Executes all tests within a specific test suite as a batch operation
operationId: trigger_test_suite_runs_public_assistants_tests_test_suites__suite_name__runs_post
parameters:
- in: path
name: suite_name
required: true
schema:
title: Suite Name
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerTestSuiteRunsRequest'
title: Request
responses:
'201':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/TestRunResponse'
title: Response Trigger Test Suite Runs Public Assistants Tests Test Suites Suite Name Runs Post
type: array
description: Returns array of created test runs for all tests in the suite
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Trigger test suite execution
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/tests/{test_id}:
delete:
description: Permanently removes an assistant test and all associated data
operationId: delete_assistant_test_public_assistants_tests__test_id__delete
parameters:
- in: path
name: test_id
required: true
schema:
title: Test Id
type: string
responses:
'200':
description: Returns success status when test is successfully deleted
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Delete an assistant test
tags:
- Assistants
x-latency-category: responsive
get:
description: Retrieves detailed information about a specific assistant test
operationId: get_assistant_test_public_assistants_tests__test_id__get
parameters:
- in: path
name: test_id
required: true
schema:
title: Test Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantTestResponse'
description: Returns complete test configuration including rubric, schedule, and metadata
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get assistant test by ID
tags:
- Assistants
x-latency-category: responsive
put:
description: Updates an existing assistant test configuration with new settings
operationId: update_assistant_test_public_assistants_tests__test_id__put
parameters:
- in: path
name: test_id
required: true
schema:
title: Test Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAssistantTestRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantTestResponse'
description: Returns the updated test configuration with all changes applied
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Update an assistant test
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/tests/{test_id}/runs:
get:
description: Retrieves paginated execution history for a specific assistant test with filtering options
operationId: get_test_runs_for_test_public_assistants_tests__test_id__runs_get
parameters:
- in: path
name: test_id
required: true
schema:
title: Test Id
type: string
- description: Filter runs by execution status (pending, running, completed, failed, timeout)
in: query
name: status
required: false
schema:
description: Filter runs by execution status (pending, running, completed, failed, timeout)
title: Status
type: string
- description: 'Consolidated page parameter (deepObject style). Originally: page[size], page[number]'
explode: true
in: query
name: page
schema:
properties:
number:
default: 1
description: Page number to retrieve (1-based indexing)
minimum: 1
title: Page[Number]
type: integer
size:
default: 20
description: Number of test runs to return per page (1-100)
maximum: 100
minimum: 1
title: Page[Size]
type: integer
type: object
style: deepObject
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedTestRunList'
description: Returns paginated list of test runs for the specified test
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get test run history for a specific test
tags:
- Assistants
x-latency-category: responsive
post:
description: Initiates immediate execution of a specific assistant test
operationId: trigger_test_run_public_assistants_tests__test_id__runs_post
parameters:
- in: path
name: test_id
required: true
schema:
title: Test Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerTestRunRequest'
title: Request
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/TestRunResponse'
description: Returns the created test run with execution details and status
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Trigger a manual test run
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/tests/{test_id}/runs/{run_id}:
get:
description: Retrieves detailed information about a specific test run execution
operationId: get_test_run_public_assistants_tests__test_id__runs__run_id__get
parameters:
- in: path
name: test_id
required: true
schema:
title: Test Id
type: string
- in: path
name: run_id
required: true
schema:
title: Run Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TestRunResponse'
description: Returns complete test run details including results, logs, and performance metrics
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get specific test run details
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/{assistant_id}:
delete:
description: Delete an AI Assistant by `assistant_id`.
operationId: delete_assistant_public_assistants__assistant_id__delete
parameters:
- in: path
name: assistant_id
required: true
schema:
title: Assistant Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantDeletedResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Delete an assistant
tags:
- Assistants
x-latency-category: responsive
get:
description: Retrieve an AI Assistant configuration by `assistant_id`.
operationId: get_assistant_public_assistants__assistant_id__get
parameters:
- in: path
name: assistant_id
required: true
schema:
title: Assistant Id
type: string
- in: query
name: fetch_dynamic_variables_from_webhook
required: false
schema:
default: false
title: Fetch Dynamic Variables From Webhook
type: boolean
- in: query
name: from
required: false
schema:
title: From
type: string
- in: query
name: to
required: false
schema:
title: To
type: string
- in: query
name: call_control_id
required: false
schema:
title: Call Control Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/inference-embedding_Assistant'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get an assistant
tags:
- Assistants
x-latency-category: responsive
post:
description: Update an AI Assistant's attributes.
operationId: update_assistant_public_assistants__assistant_id__post
parameters:
- in: path
name: assistant_id
required: true
schema:
title: Assistant Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAssistantRequestWithPromotion'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/inference-embedding_Assistant'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Update an assistant
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/{assistant_id}/canary-deploys:
delete:
description: 'Endpoint to delete a canary deploy configuration for an assistant.
Removes all canary deploy configurations for the specified assistant.'
operationId: delete_canary_deploy_assistants__assistant_id__canary_deploys_delete
parameters:
- in: path
name: assistant_id
required: true
schema:
title: Assistant Id
type: string
responses:
'204':
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Delete Canary Deploy
tags:
- Assistants
x-latency-category: responsive
get:
description: 'Endpoint to get a canary deploy configuration for an assistant.
Retrieves the current canary deploy configuration with all version IDs and their
traffic percentages for the specified assistant.'
operationId: get_canary_deploy_assistants__assistant_id__canary_deploys_get
parameters:
- in: path
name: assistant_id
required: true
schema:
title: Assistant Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CanaryDeployResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get Canary Deploy
tags:
- Assistants
x-latency-category: responsive
post:
description: 'Endpoint to create a canary deploy configuration for an assistant.
Creates a new canary deploy configuration with multiple version IDs and their traffic
percentages for A/B testing or gradual rollouts of assistant versions.'
operationId: create_canary_deploy_assistants__assistant_id__canary_deploys_post
parameters:
- in: path
name: assistant_id
required: true
schema:
title: Assistant Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CanaryDeployRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CanaryDeployResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Create Canary Deploy
tags:
- Assistants
x-latency-category: responsive
put:
description: "Endpoint to update a canary deploy configuration for an assistant.\n\nUpdates the existing canary deploy configuration with new version IDs and percentages.\n All old versions and percentages are replaces by new ones from this request."
operationId: update_canary_deploy_assistants__assistant_id__canary_deploys_put
parameters:
- in: path
name: assistant_id
required: true
schema:
title: Assistant Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CanaryDeployRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CanaryDeployResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Update Canary Deploy
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/{assistant_id}/chat:
post:
description: This endpoint allows a client to send a chat message to a specific AI Assistant. The assistant processes the message and returns a relevant reply based on the current conversation context. Refer to the Conversation API to [create a conversation](https://developers.telnyx.com/api-reference/conversations/create-a-conversation), [filter existing conversations](https://developers.telnyx.com/api-reference/conversations/list-conversations), [fetch messages for a conversation](https://developers.telnyx.com/api-reference/conversations/get-conversation-messages), and [manually add messages to a conversation](https://developers.telnyx.com/api-reference/conversations/create-message).
operationId: assistant_chat_public_assistants__assistant_id__chat_post
parameters:
- in: path
name: assistant_id
required: true
schema:
title: Assistant Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantChatReq'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantChatResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Assistant Chat (BETA)
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/{assistant_id}/chat/sms:
post:
description: "Send an SMS message for an assistant. This endpoint: \n1. Validates the assistant exists and has messaging profile configured \n2. If should_create_conversation is true, creates a new conversation with metadata \n3. Sends the SMS message (If `text` is set, this will be sent. Otherwise, if this is the first message in the conversation and the assistant has a `greeting` configured, this will be sent. Otherwise the assistant will generate the text to send.) \n4. Updates conversation metadata if provided \n5. Returns the conversation ID"
operationId: assistant_sms_chat_assistants__assistant_id__chat_sms_post
parameters:
- in: path
name: assistant_id
required: true
schema:
title: Assistant Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantSmsChatReq'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantSmsChatResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Assistant Sms Chat
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/{assistant_id}/clone:
post:
description: Clone an existing assistant, excluding telephony and messaging settings.
operationId: clone_assistant_public_assistants__assistant_id__clone_post
parameters:
- in: path
name: assistant_id
required: true
schema:
title: Assistant Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/inference-embedding_Assistant'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Clone Assistant
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/{assistant_id}/scheduled_events:
get:
description: Get scheduled events for an assistant with pagination and filtering
operationId: get_scheduled_events
parameters:
- in: path
name: assistant_id
required: true
schema:
title: Assistant Id
type: string
- in: query
name: from_date
required: false
schema:
format: date-time
title: From Date
type: string
- in: query
name: to_date
required: false
schema:
format: date-time
title: To Date
type: string
- in: query
name: conversation_channel
required: false
schema:
$ref: '#/components/schemas/ConversationChannelType'
title: Conversation Channel
- description: 'Consolidated page parameter (deepObject style). Originally: page[size], page[number]'
explode: true
in: query
name: page
schema:
properties:
number:
default: 1
minimum: 1
title: Page[Number]
type: integer
size:
default: 20
maximum: 100
minimum: 1
title: Page[Size]
type: integer
type: object
style: deepObject
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedScheduledEventList'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: List scheduled events
tags:
- Assistants
x-latency-category: responsive
post:
description: Create a scheduled event for an assistant
operationId: create_scheduled_event
parameters:
- in: path
name: assistant_id
required: true
schema:
title: Assistant Id
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScheduledEventRequest'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledEventResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Create a scheduled event
tags:
- Assistants
x-latency-category: responsive
/ai/assistants/{assistant_id}/scheduled_events/{event_id}:
delete:
description: If the event is pending, this will cancel the event. Otherwi
# --- truncated at 32 KB (160 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/telnyx/refs/heads/main/openapi/telnyx-assistants-api-openapi.yml