telnyx-missions-curl

Telnyx Missions - curl

Installation

# curl is pre-installed on macOS, Linux, and Windows 10+

Setup

export TELNYX_API_KEY="YOUR_API_KEY_HERE"

All examples below use $TELNYX_API_KEY for authentication.

Error Handling

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

# Check HTTP status code in response
response=$(curl -s -w "\n%{http_code}" \
  -X POST "https://api.telnyx.com/v2/messages" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+13125550001", "from": "+13125550002", "text": "Hello"}')

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')

case $http_code in
  2*) echo "Success: $body" ;;
  422) echo "Validation error — check required fields and formats" ;;
  429) echo "Rate limited — retry after delay"; sleep 1 ;;
  401) echo "Authentication failed — check TELNYX_API_KEY" ;;
  *)   echo "Error $http_code: $body" ;;
esac

Common error codes: 401 invalid API key, 403 insufficient permissions, 404 resource not found, 422 validation error (check field formats), 429 rate limited (retry with exponential backoff).

Important Notes

• Pagination: List endpoints return paginated results. Use page[number] and page[size] query parameters to navigate pages. Check meta.total_pages in the response.

List missions

List all missions for the organization

GET /ai/missions

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions"

Returns: created_at (date-time), description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), mission_id (uuid), model (string), name (string), updated_at (date-time)

Create mission

Create a new mission definition

POST /ai/missions — Required: name

Optional: description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), model (string)

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-resource"
}' \
  "https://api.telnyx.com/v2/ai/missions"

Returns: created_at (date-time), description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), mission_id (uuid), model (string), name (string), updated_at (date-time)

List recent events

List recent events across all missions

GET /ai/missions/events

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/events"

Returns: agent_id (string), event_id (string), idempotency_key (string), payload (object), run_id (string), step_id (string), summary (string), timestamp (date-time), type (enum: status_change, step_started, step_completed, step_failed, tool_call, tool_result, message, error, custom)

List recent runs

List recent runs across all missions

GET /ai/missions/runs

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/runs"

Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)

Get mission

Get a mission by ID (includes tools, knowledge_bases, mcp_servers)

GET /ai/missions/{mission_id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/{mission_id}"

Returns: created_at (date-time), description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), mission_id (uuid), model (string), name (string), updated_at (date-time)

Update mission

Update a mission definition

PUT /ai/missions/{mission_id}

Optional: description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), model (string), name (string)

curl \
  -X PUT \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}"

Returns: created_at (date-time), description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), mission_id (uuid), model (string), name (string), updated_at (date-time)

Delete mission

Delete a mission

DELETE /ai/missions/{mission_id}

curl \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}"

Clone mission

Clone an existing mission

POST /ai/missions/{mission_id}/clone

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/clone"

List knowledge bases

List all knowledge bases for a mission

GET /ai/missions/{mission_id}/knowledge-bases

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/{mission_id}/knowledge-bases"

Create knowledge base

Create a new knowledge base for a mission

POST /ai/missions/{mission_id}/knowledge-bases

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/knowledge-bases"

Get knowledge base

Get a specific knowledge base by ID

GET /ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}"

Update knowledge base

Update a knowledge base definition

PUT /ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}

curl \
  -X PUT \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}"

Delete knowledge base

Delete a knowledge base from a mission

DELETE /ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}

curl \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}"

List MCP servers

List all MCP servers for a mission

GET /ai/missions/{mission_id}/mcp-servers

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/{mission_id}/mcp-servers"

Create MCP server

Create a new MCP server for a mission

POST /ai/missions/{mission_id}/mcp-servers

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/mcp-servers"

Get MCP server

Get a specific MCP server by ID

GET /ai/missions/{mission_id}/mcp-servers/{mcp_server_id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/{mission_id}/mcp-servers/{mcp_server_id}"

Update MCP server

Update an MCP server definition

PUT /ai/missions/{mission_id}/mcp-servers/{mcp_server_id}

curl \
  -X PUT \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/mcp-servers/{mcp_server_id}"

Delete MCP server

Delete an MCP server from a mission

DELETE /ai/missions/{mission_id}/mcp-servers/{mcp_server_id}

curl \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/mcp-servers/{mcp_server_id}"

List runs for mission

List all runs for a specific mission

GET /ai/missions/{mission_id}/runs

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs"

Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)

Start a run

Start a new run for a mission

POST /ai/missions/{mission_id}/runs

Optional: input (object), metadata (object)

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs"

Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)

Get run details

Get details of a specific run

GET /ai/missions/{mission_id}/runs/{run_id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}"

Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)

Update run

Update run status and/or result

PATCH /ai/missions/{mission_id}/runs/{run_id}

Optional: error (string), metadata (object), result_payload (object), result_summary (string), status (enum: pending, running, paused, succeeded, failed, cancelled)

curl \
  -X PATCH \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}"

Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)

Cancel run

Cancel a running or paused run

POST /ai/missions/{mission_id}/runs/{run_id}/cancel

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}/cancel"

Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)

List events

List events for a run (paginated)

GET /ai/missions/{mission_id}/runs/{run_id}/events

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}/events"

Returns: agent_id (string), event_id (string), idempotency_key (string), payload (object), run_id (string), step_id (string), summary (string), timestamp (date-time), type (enum: status_change, step_started, step_completed, step_failed, tool_call, tool_result, message, error, custom)

Log event

Log an event for a run

POST /ai/missions/{mission_id}/runs/{run_id}/events — Required: type, summary

Optional: agent_id (string), idempotency_key (string), payload (object), step_id (string)

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "status_change",
  "summary": "Brief task summary"
}' \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}/events"

Returns: agent_id (string), event_id (string), idempotency_key (string), payload (object), run_id (string), step_id (string), summary (string), timestamp (date-time), type (enum: status_change, step_started, step_completed, step_failed, tool_call, tool_result, message, error, custom)

Get event details

Get details of a specific event

GET /ai/missions/{mission_id}/runs/{run_id}/events/{event_id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}/events/{event_id}"

Returns: agent_id (string), event_id (string), idempotency_key (string), payload (object), run_id (string), step_id (string), summary (string), timestamp (date-time), type (enum: status_change, step_started, step_completed, step_failed, tool_call, tool_result, message, error, custom)

Pause run

Pause a running run

POST /ai/missions/{mission_id}/runs/{run_id}/pause

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}/pause"

Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)

Get plan

Get the plan (all steps) for a run

GET /ai/missions/{mission_id}/runs/{run_id}/plan

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}/plan"

Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)

Create initial plan

Create the initial plan for a run

POST /ai/missions/{mission_id}/runs/{run_id}/plan — Required: steps

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "steps": [
    "Initiate the task"
  ]
}' \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}/plan"

Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)

Add step(s) to plan

Add one or more steps to an existing plan

POST /ai/missions/{mission_id}/runs/{run_id}/plan/steps — Required: steps

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "steps": [
    "Initiate the task"
  ]
}' \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}/plan/steps"

Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)

Get step details

Get details of a specific plan step

GET /ai/missions/{mission_id}/runs/{run_id}/plan/steps/{step_id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}/plan/steps/{step_id}"

Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)

Update step status

Update the status of a plan step

PATCH /ai/missions/{mission_id}/runs/{run_id}/plan/steps/{step_id}

Optional: metadata (object), status (enum: pending, in_progress, completed, skipped, failed)

curl \
  -X PATCH \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}/plan/steps/{step_id}"

Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)

Resume run

Resume a paused run

POST /ai/missions/{mission_id}/runs/{run_id}/resume

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}/resume"

Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)

List linked Telnyx agents

List all Telnyx agents linked to a run

GET /ai/missions/{mission_id}/runs/{run_id}/telnyx-agents

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}/telnyx-agents"

Returns: created_at (date-time), run_id (string), telnyx_agent_id (string)

Link Telnyx agent to run

Link a Telnyx AI agent (voice/messaging) to a run

POST /ai/missions/{mission_id}/runs/{run_id}/telnyx-agents — Required: telnyx_agent_id

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "telnyx_agent_id": "550e8400-e29b-41d4-a716-446655440000"
}' \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}/telnyx-agents"

Returns: created_at (date-time), run_id (string), telnyx_agent_id (string)

Unlink Telnyx agent

Unlink a Telnyx agent from a run

DELETE /ai/missions/{mission_id}/runs/{run_id}/telnyx-agents/{telnyx_agent_id}

curl \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/runs/{run_id}/telnyx-agents/{telnyx_agent_id}"

List tools

List all tools for a mission

GET /ai/missions/{mission_id}/tools

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/{mission_id}/tools"

Create tool

Create a new tool for a mission

POST /ai/missions/{mission_id}/tools

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/tools"

Get tool

Get a specific tool by ID

GET /ai/missions/{mission_id}/tools/{tool_id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/missions/{mission_id}/tools/{tool_id}"

Update tool

Update a tool definition

PUT /ai/missions/{mission_id}/tools/{tool_id}

curl \
  -X PUT \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/tools/{tool_id}"

Delete tool

Delete a tool from a mission

DELETE /ai/missions/{mission_id}/tools/{tool_id}

curl \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/ai/missions/{mission_id}/tools/{tool_id}"