telnyx-missions-ruby

<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

# Telnyx Missions - Ruby

## Installation

```bash
gem install telnyx
```

## Setup

```ruby
require "telnyx"

client = Telnyx::Client.new(
  api_key: ENV["TELNYX_API_KEY"], # This is the default and can be omitted
)
```

All examples below assume `client` is already initialized as shown above.

## 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:

```ruby
begin
  result = client.messages.send_(to: "+13125550001", from: "+13125550002", text: "Hello")
rescue Telnyx::Errors::APIConnectionError
  puts "Network error — check connectivity and retry"
rescue Telnyx::Errors::RateLimitError
  # 429: rate limited — wait and retry with exponential backoff
  sleep(1) # Check Retry-After header for actual delay
rescue Telnyx::Errors::APIStatusError => e
  puts "API error #{e.status}: #{e.message}"
  if e.status == 422
    puts "Validation error — check required fields and formats"
  end
end
```

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:** Use `.auto_paging_each` for automatic iteration: `page.auto_paging_each { |item| puts item.id }`.

## List missions

List all missions for the organization

`GET /ai/missions`

```ruby
page = client.ai.missions.list

puts(page)
```

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)

```ruby
mission = client.ai.missions.create(name: "my-resource")

puts(mission)
```

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`

```ruby
page = client.ai.missions.list_events

puts(page)
```

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`

```ruby
page = client.ai.missions.runs.list_runs

puts(page)
```

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}`

```ruby
mission = client.ai.missions.retrieve("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(mission)
```

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)

```ruby
response = client.ai.missions.update_mission("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(response)
```

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}`

```ruby
result = client.ai.missions.delete_mission("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(result)
```

## Clone mission

Clone an existing mission

`POST /ai/missions/{mission_id}/clone`

```ruby
response = client.ai.missions.clone_mission("mission_id")

puts(response)
```

## List knowledge bases

List all knowledge bases for a mission

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

```ruby
response = client.ai.missions.knowledge_bases.list_knowledge_bases("mission_id")

puts(response)
```

## Create knowledge base

Create a new knowledge base for a mission

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

```ruby
response = client.ai.missions.knowledge_bases.create_knowledge_base("mission_id")

puts(response)
```

## Get knowledge base

Get a specific knowledge base by ID

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

```ruby
response = client.ai.missions.knowledge_bases.get_knowledge_base("knowledge_base_id", mission_id: "550e8400-e29b-41d4-a716-446655440000")

puts(response)
```

## Update knowledge base

Update a knowledge base definition

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

```ruby
response = client.ai.missions.knowledge_bases.update_knowledge_base("knowledge_base_id", mission_id: "550e8400-e29b-41d4-a716-446655440000")

puts(response)
```

## Delete knowledge base

Delete a knowledge base from a mission

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

```ruby
result = client.ai.missions.knowledge_bases.delete_knowledge_base("knowledge_base_id", mission_id: "550e8400-e29b-41d4-a716-446655440000")

puts(result)
```

## List MCP servers

List all MCP servers for a mission

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

```ruby
response = client.ai.missions.mcp_servers.list_mcp_servers("mission_id")

puts(response)
```

## Create MCP server

Create a new MCP server for a mission

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

```ruby
response = client.ai.missions.mcp_servers.create_mcp_server("mission_id")

puts(response)
```

## Get MCP server

Get a specific MCP server by ID

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

```ruby
response = client.ai.missions.mcp_servers.get_mcp_server("mcp_server_id", mission_id: "550e8400-e29b-41d4-a716-446655440000")

puts(response)
```

## Update MCP server

Update an MCP server definition

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

```ruby
response = client.ai.missions.mcp_servers.update_mcp_server("mcp_server_id", mission_id: "550e8400-e29b-41d4-a716-446655440000")

puts(response)
```

## Delete MCP server

Delete an MCP server from a mission

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

```ruby
result = client.ai.missions.mcp_servers.delete_mcp_server("mcp_server_id", mission_id: "550e8400-e29b-41d4-a716-446655440000")

puts(result)
```

## List runs for mission

List all runs for a specific mission

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

```ruby
page = client.ai.missions.runs.list("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(page)
```

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)

```ruby
run = client.ai.missions.runs.create("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(run)
```

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}`

```ruby
run = client.ai.missions.runs.retrieve(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(run)
```

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)

```ruby
run = client.ai.missions.runs.update(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(run)
```

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`

```ruby
response = client.ai.missions.runs.cancel_run(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(response)
```

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`

```ruby
page = client.ai.missions.runs.events.list(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(page)
```

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)

```ruby
response = client.ai.missions.runs.events.log(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  summary: "Brief task summary",
  type: :status_change
)

puts(response)
```

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}`

```ruby
response = client.ai.missions.runs.events.get_event_details(
  "event_id",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  run_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(response)
```

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`

```ruby
response = client.ai.missions.runs.pause_run(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(response)
```

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`

```ruby
plan = client.ai.missions.runs.plan.retrieve(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(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`

```ruby
plan = client.ai.missions.runs.plan.create(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  steps: [{description: "description", sequence: 0, step_id: "550e8400-e29b-41d4-a716-446655440000"}]
)

puts(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`

```ruby
response = client.ai.missions.runs.plan.add_steps_to_plan(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  steps: [{description: "description", sequence: 0, step_id: "550e8400-e29b-41d4-a716-446655440000"}]
)

puts(response)
```

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}`

```ruby
response = client.ai.missions.runs.plan.get_step_details(
  "step_id",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  run_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(response)
```

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)

```ruby
response = client.ai.missions.runs.plan.update_step(
  "step_id",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  run_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(response)
```

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`

```ruby
response = client.ai.missions.runs.resume_run(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(response)
```

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`

```ruby
telnyx_agents = client.ai.missions.runs.telnyx_agents.list(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(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`

```ruby
response = client.ai.missions.runs.telnyx_agents.link(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  telnyx_agent_id: "550e8400-e29b-41d4-a716-446655440000"
)

puts(response)
```

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}`

```ruby
result = client.ai.missions.runs.telnyx_agents.unlink(
  "telnyx_agent_id",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  run_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(result)
```

## List tools

List all tools for a mission

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

```ruby
response = client.ai.missions.tools.list_tools("mission_id")

puts(response)
```

## Create tool

Create a new tool for a mission

`POST /ai/missions/{mission_id}/tools`

```ruby
response = client.ai.missions.tools.create_tool("mission_id")

puts(response)
```

## Get tool

Get a specific tool by ID

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

```ruby
response = client.ai.missions.tools.get_tool("tool_id", mission_id: "550e8400-e29b-41d4-a716-446655440000")

puts(response)
```

## Update tool

Update a tool definition

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

```ruby
response = client.ai.missions.tools.update_tool("tool_id", mission_id: "550e8400-e29b-41d4-a716-446655440000")

puts(response)
```

## Delete tool

Delete a tool from a mission

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

```ruby
result = client.ai.missions.tools.delete_tool("tool_id", mission_id: "550e8400-e29b-41d4-a716-446655440000")

puts(result)
```