Telnyx Assistants API
Configure AI assistant specifications
Telnyx Assistants API is one of 168 APIs that Telnyx publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
Tagged areas include Assistants. The published artifact set on APIs.io includes an OpenAPI specification and API documentation.
This API exposes 45 operations across 26 paths, and defines 97 schemas. It is described by OpenAPI 3.1.0, at version 2.0.0.
Requests are made against a single base URL, https://api.telnyx.com/v2.
45 operations
26 paths
97 schemas
8 DELETE17 GET1 PATCH16 POST3 PUT
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 6
Telnyx Assistants API declares
6 security schemes
for authenticating requests.
It accepts HTTP bearer tokens (bearerAuth).
It accepts HTTP bearer tokens (branded-calling_bearerAuth).
It supports OAuth 2.0 (oauthClientAuth) using the authorizationCode and clientCredentials flows, exposing 1 scope.
It accepts HTTP bearer tokens (JWT) (outbound-voice-profiles_bearerAuth).
It accepts HTTP bearer tokens (pronunciation-dicts_bearerAuth).
It accepts HTTP bearer tokens (JWT) (stored-payment-transactions_bearerAuth).
By default, every request must be authenticated.
branded-calling_bearerAuth— API key passed as a Bearer token in the Authorization headeroauthClientAuth— OAuth 2.0 authentication for Telnyx API and MCP integrationspronunciation-dicts_bearerAuth— Telnyx API v2 key. Obtain from https://portal.telnyx.com
Paths & Operations 45
Across 26 paths, the API surfaces 45 operations — 8 DELETE, 17 GET, 1 PATCH, 16 POST, 3 PUT. Each is listed below with its method, path, parameters, and response codes.
Assistants 45
Configure AI assistant specifications
GET
/ai/assistants
List assistants
POST
/ai/assistants
Create an assistant
POST
/ai/assistants/import
Import assistants from external provider
GET
/ai/assistants/tags
Get All Tags
GET
/ai/assistants/tests
List assistant tests with pagination
POST
/ai/assistants/tests
Create a new assistant test
GET
/ai/assistants/tests/test-suites
Get all test suite names
GET
/ai/assistants/tests/test-suites/{suite_name}/runs
Get test suite run history
POST
/ai/assistants/tests/test-suites/{suite_name}/runs
Trigger test suite execution
DELETE
/ai/assistants/tests/{test_id}
Delete an assistant test
GET
/ai/assistants/tests/{test_id}
Get assistant test by ID
PUT
/ai/assistants/tests/{test_id}
Update an assistant test
GET
/ai/assistants/tests/{test_id}/runs
Get test run history for a specific test
POST
/ai/assistants/tests/{test_id}/runs
Trigger a manual test run
GET
/ai/assistants/tests/{test_id}/runs/{run_id}
Get specific test run details
DELETE
/ai/assistants/{assistant_id}
Delete an assistant
GET
/ai/assistants/{assistant_id}
Get an assistant
POST
/ai/assistants/{assistant_id}
Update an assistant
DELETE
/ai/assistants/{assistant_id}/canary-deploys
Delete Canary Deploy
GET
/ai/assistants/{assistant_id}/canary-deploys
Get Canary Deploy
POST
/ai/assistants/{assistant_id}/canary-deploys
Create Canary Deploy
PUT
/ai/assistants/{assistant_id}/canary-deploys
Update Canary Deploy
POST
/ai/assistants/{assistant_id}/chat
Assistant Chat (BETA)
POST
/ai/assistants/{assistant_id}/chat/sms
Assistant Sms Chat
POST
/ai/assistants/{assistant_id}/clone
Clone Assistant
GET
/ai/assistants/{assistant_id}/scheduled_events
List scheduled events
POST
/ai/assistants/{assistant_id}/scheduled_events
Create a scheduled event
DELETE
/ai/assistants/{assistant_id}/scheduled_events/{event_id}
Delete a scheduled event
GET
/ai/assistants/{assistant_id}/scheduled_events/{event_id}
Get a scheduled event
POST
/ai/assistants/{assistant_id}/tags
Add Assistant Tag
DELETE
/ai/assistants/{assistant_id}/tags/{tag}
Remove Assistant Tag
GET
/ai/assistants/{assistant_id}/texml
Get assistant texml
DELETE
/ai/assistants/{assistant_id}/tools/{tool_id}
Remove Assistant Tool
PUT
/ai/assistants/{assistant_id}/tools/{tool_id}
Add Assistant Tool
POST
/ai/assistants/{assistant_id}/tools/{tool_id}/test
Test Assistant Tool
GET
/ai/assistants/{assistant_id}/versions
Get all versions of an assistant
DELETE
/ai/assistants/{assistant_id}/versions/{version_id}
Delete a specific assistant version
GET
/ai/assistants/{assistant_id}/versions/{version_id}
Get a specific assistant version
POST
/ai/assistants/{assistant_id}/versions/{version_id}
Update a specific assistant version
POST
/ai/assistants/{assistant_id}/versions/{version_id}/promote
Promote an assistant version to main
GET
/ai/tools
List Tools
POST
/ai/tools
Create Tool
DELETE
/ai/tools/{tool_id}
Delete Tool
GET
/ai/tools/{tool_id}
Get Tool
PATCH
/ai/tools/{tool_id}
Update Tool
Schemas 97
The contract defines 97 schemas that model the data the API accepts and returns. The most detailed are inference-embedding_Assistant (33 properties), UpdateAssistantRequest (28 properties), CreateAssistantRequest (27 properties), ScheduledPhoneCallEventResponse (20 properties). Each schema is shown below with its type and property counts.
InviteToolConfig
object
4 properties
1 required
ValidationError
object
3 properties
3 required
AssistantChatReq
object
3 properties
2 required
StartSpeakingPlan
object
Controls when the assistant starts speaking after the user stops. These thresholds primarily apply to non turn-taking transcription models. For turn-taking mod…
2 properties
Meta
object
4 properties
4 required
TestRunResponse
object
Response model containing test run execution details and results. Provides comprehensive information about a test execution including status, timing, logs, and…
12 properties
5 required
CanaryDeployResponse
object
Response shape. Always carries rules (canonical).
4 properties
4 required
ImportAssistantsRequest
object
3 properties
2 required
Rule-Input
object
A targeting rule: match clauses (AND) gate serve. An empty match is a catch-all (always fires).
2 properties
1 required
ScheduledSmsEventResponse
object
14 properties
6 required
DTMFTool
object
2 properties
2 required
TelnyxConversationChannel
string
MessagingSettings
object
3 properties
AssistantsListData
object
1 property
1 required
TriggerTestRunRequest
object
Request model for triggering a single test run. Optional request body for the trigger test run endpoint.
1 property
SendMessageTool
object
The sendmessage tool allows the assistant to send SMS or MMS messages to the end user. The 'to' and 'from' addresses are automatically determined from the conv…
2 properties
2 required
VoiceSettings
object
11 properties
1 required
UpdateAssistantRequestWithPromotion
TestRunDetailResult
object
2 properties
2 required
TriggerTestSuiteRunsRequest
object
Request model for triggering test suite runs. Optional request body for the trigger test suite runs endpoint.
1 property
SkipTurnToolParams
object
1 property
PostConversationSettingsReq
object
Configuration for post-conversation processing. When enabled, the assistant receives one additional LLM turn after the conversation ends, allowing it to execut…
1 property
AddTagRequest
object
1 property
1 required
InviteTool
object
2 properties
2 required
HandoffTool
object
The handoff tool allows the assistant to hand off control of the conversation to another AI assistant. By default, this will happen transparently to the end us…
2 properties
2 required
PaginatedAssistantTestList
object
Paginated list of assistant tests with metadata. Returns a subset of tests based on pagination parameters along with metadata for implementing pagination contr…
2 properties
2 required
FallbackConfig
object
3 properties
CreateAssistantTestRequest
object
Request model for creating a new assistant test. This model defines all the required and optional parameters needed to create a comprehensive test for an AI as…
8 properties
4 required
AssistantIntegration
object
Reference to a connected integration attached to an assistant. Discover available integrations with /ai/integrations and connected integrations with /ai/integr…
2 properties
1 required
CreateSharedToolRequest
object
Request model for creating a shared (org-level) tool.
8 properties
2 required
inference-embedding_InterruptionSettings
object
Settings for interruptions and how the assistant decides the user has finished speaking. These timings are most relevant when using non turn-taking transcripti…
3 properties
TagsResponse
object
1 property
1 required
SIPReferToolParams
object
3 properties
1 required
HandoffToolParams
object
2 properties
1 required
CreateScheduledEventRequest
object
9 properties
4 required
SIPReferTool
object
2 properties
2 required
AssistantScheduledCallAttempt
object
One row in callattempts — captures the terminal outcome of a single dispatch.
5 properties
3 required
AssistantTools
array
Deprecated for new integrations. Inline tool definitions available to the assistant. Prefer toolids to attach shared tools created with the AI Tools endpoints.
AssistantTestResponse
object
Response model containing complete assistant test information. Returns all test configuration details including evaluation criteria, scheduling, and metadata.…
10 properties
5 required
Serve
object
What a rule serves when matched. Exactly one of: - versionid — serve a specific version - rollout — weighted random across versions; weights must sum to less t…
2 properties
HangupTool
object
2 properties
2 required
SharedToolListResponse
object
2 properties
2 required
UpdateAssistantRequest
object
28 properties
Operator
string
InsightSettings
object
1 property
AudioVisualizerConfig
object
2 properties
RolloutSlot
object
One slot in a percentage rollout.
2 properties
2 required
PaginatedTestRunList
object
Paginated list of test runs with metadata. Returns test run execution results with pagination support for handling large numbers of test executions.
2 properties
2 required
Observability
object
8 properties
ScheduledEventResponse
Union type for different scheduled event response types
HTTPValidationError
object
1 property
HangupToolParams
object
1 property
CreateAssistantRequest
object
27 properties
2 required
SkipTurnTool
object
2 properties
2 required
PostConversationSettings
object
Configuration for post-conversation processing. When enabled, the assistant receives one additional LLM turn after the conversation ends, allowing it to execut…
1 property
PromptSyncStatus
string
Whether to auto-publish the assistant's instructions as a Langfuse prompt. When ENABLED + promptname set, every assistant create/update pushes instructions to…
AssistantMCPServer
object
Reference to an MCP server attached to an assistant. Create and manage MCP servers with the /ai/mcpservers endpoints, then attach them to assistants by ID.
2 properties
1 required
UpdateSharedToolRequest
object
Request model for updating a shared tool.
8 properties
UpdateAssistantTestRequest
object
Request model for updating an existing assistant test. All fields are optional, allowing partial updates of test configuration. Only provided fields will be up…
8 properties
PrivacySettings
object
1 property
inference-embedding_Assistant
object
33 properties
5 required
BucketIds
object
2 properties
1 required
AssistantSmsChatResponse
object
1 property
WebhookToolParams
object
11 properties
3 required
inference-embedding_WebhookTool
object
2 properties
2 required
TranscriptionSettingsConfig
object
9 properties
Rule-Output
object
A targeting rule: match clauses (AND) gate serve. An empty match is a catch-all (always fires).
2 properties
1 required
FallbackConfigReq
object
3 properties
PaginatedScheduledEventList
object
2 properties
2 required
TestWebhookToolResponseData
object
Response model for webhook tool test results
1 property
1 required
InferenceEmbeddingTransferToolParams
object
6 properties
2 required
ScheduledPhoneCallEventResponse
object
20 properties
5 required
ObservabilityReq
object
8 properties
AssistantSmsChatReq
object
5 properties
2 required
CanaryDeployRequest
object
Create/update request body. Accepts: - rules — canonical ordered list of routing rules
1 property
TestWebhookToolRequest
object
Request model for testing a webhook tool
2 properties
EnabledFeatures
string
If telephony is enabled, the assistant will be able to make and receive calls. If messaging is enabled, the assistant will be able to send and receive messages.
TestSuitesResponse
object
Response containing all available test suite names. Returns a list of distinct test suite names that can be used for filtering and organizing tests.
1 property
1 required
SharedToolResponse
object
6 properties
3 required
EventStatus
string
Clause
object
A single attribute/operator/values check. A clause matches when the routing context's value for attribute satisfies operator against any of values.
3 properties
3 required
ConversationChannelType
string
TranscriptionEndpointingPlan
object
Endpointing thresholds used to decide when the user has finished speaking. Applies to non turn-taking transcription models. For deepgram/flux, use transcriptio…
3 properties
RetrievalTool
object
2 properties
2 required
TestStatus
string
Represents the lifecycle of a test: - 'pending': Test is waiting to be executed. - 'starting': Test execution is initializing. - 'running': Test is currently e…
ImportMetadata
object
2 properties
WidgetSettings
object
Configuration settings for the assistant's web widget.
11 properties
inference-embedding_TransferTool
object
2 properties
2 required
ExternalLLMReq
object
7 properties
2 required
AuthenticationMethod
string
Authentication method used when connecting to the external LLM endpoint.
TranscriptionSettings
object
5 properties
ObservabilityStatus
string
ExternalLLM
object
7 properties
2 required
AssistantChatResponse
object
1 property
1 required
TelephonySettings
object
9 properties
AssistantDeletedResponse
object
Aligns with the OpenAI API: https://platform.openai.com/docs/api-reference/assistants/deleteAssistant
3 properties
3 required
TestWebhookToolResponse
object
Response model for webhook tool test results
5 properties
5 required
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from Telnyx 12
Other APIs Telnyx publishes across the network.
Telnyx Access Tokens API
Telnyx Addresses API
Telnyx Advanced Number Orders API
Telnyx Audio API
Telnyx Audit Logs API
Telnyx Authentication Providers API
Telnyx AutoRechargePreferences API
Telnyx Billing API
Telnyx Billing Groups API
Telnyx Brands API
Telnyx Bucket SSL Certificate API
Telnyx Bucket Usage API
#Assistants