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:

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 all clusters

GET /ai/clusters

page = client.ai.clusters.list

puts(page)

Returns: bucket (string), created_at (date-time), finished_at (date-time), min_cluster_size (integer), min_subcluster_size (integer), status (enum: pending, starting, running, completed, failed), task_id (string)

Compute new clusters

Starts a background task to compute how the data in an embedded storage bucket is clustered. This helps identify common themes and patterns in the data.

POST /ai/clusters — Required: bucket

Optional: files (array[string]), min_cluster_size (integer), min_subcluster_size (integer), prefix (string)

response = client.ai.clusters.compute(bucket: "my-bucket")

puts(response)

Returns: task_id (string)

Fetch a cluster

GET /ai/clusters/{task_id}

cluster = client.ai.clusters.retrieve("task_id")

puts(cluster)

Returns: bucket (string), clusters (array[object]), status (enum: pending, starting, running, completed, failed)

Delete a cluster

DELETE /ai/clusters/{task_id}

result = client.ai.clusters.delete("task_id")

puts(result)

Fetch a cluster visualization

GET /ai/clusters/{task_id}/graph

response = client.ai.clusters.fetch_graph("task_id")

puts(response)

List Integrations

List all available integrations.

GET /ai/integrations

integrations = client.ai.integrations.list

puts(integrations)

Returns: available_tools (array[string]), description (string), display_name (string), id (string), logo_url (string), name (string), status (enum: disconnected, connected)

List User Integrations

List user setup integrations

GET /ai/integrations/connections

connections = client.ai.integrations.connections.list

puts(connections)

Returns: allowed_tools (array[string]), id (string), integration_id (string)

Get User Integration connection By Id

Get user setup integrations

GET /ai/integrations/connections/{user_connection_id}

connection = client.ai.integrations.connections.retrieve("user_connection_id")

puts(connection)

Returns: allowed_tools (array[string]), id (string), integration_id (string)

Delete Integration Connection

Delete a specific integration connection.

DELETE /ai/integrations/connections/{user_connection_id}

result = client.ai.integrations.connections.delete("user_connection_id")

puts(result)

List Integration By Id

Retrieve integration details

GET /ai/integrations/{integration_id}

integration = client.ai.integrations.retrieve("integration_id")

puts(integration)

Returns: available_tools (array[string]), description (string), display_name (string), id (string), logo_url (string), name (string), status (enum: disconnected, connected)

List all Global IP Allowed Ports

GET /global_ip_allowed_ports

global_ip_allowed_ports = client.global_ip_allowed_ports.list

puts(global_ip_allowed_ports)

Returns: first_port (integer), id (uuid), last_port (integer), name (string), protocol_code (string), record_type (string)

Global IP Assignment Health Check Metrics

GET /global_ip_assignment_health

global_ip_assignment_health = client.global_ip_assignment_health.retrieve

puts(global_ip_assignment_health)

Returns: global_ip (object), global_ip_assignment (object), health (object), timestamp (date-time)

List all Global IP assignments

List all Global IP assignments.

GET /global_ip_assignments

page = client.global_ip_assignments.list

puts(page)

Returns: created_at (string), global_ip_id (uuid), id (uuid), is_announced (boolean), is_connected (boolean), is_in_maintenance (boolean), record_type (string), status (enum: created, provisioning, provisioned, deleting), updated_at (string), wireguard_peer_id (uuid)

Create a Global IP assignment

Create a Global IP assignment.

POST /global_ip_assignments

Optional: created_at (string), global_ip_id (uuid), id (uuid), is_announced (boolean), is_connected (boolean), is_in_maintenance (boolean), record_type (string), status (enum: created, provisioning, provisioned, deleting), updated_at (string), wireguard_peer_id (uuid)

global_ip_assignment = client.global_ip_assignments.create

puts(global_ip_assignment)

Retrieve a Global IP

Retrieve a Global IP assignment.

GET /global_ip_assignments/{id}

global_ip_assignment = client.global_ip_assignments.retrieve("6a09cdc3-8948-47f0-aa62-74ac943d6c58")

puts(global_ip_assignment)

Update a Global IP assignment

Update a Global IP assignment.

PATCH /global_ip_assignments/{id}

Optional: created_at (string), global_ip_id (string), id (uuid), is_announced (boolean), is_connected (boolean), is_in_maintenance (boolean), record_type (string), status (enum: created, provisioning, provisioned, deleting), updated_at (string), wireguard_peer_id (string)

global_ip_assignment = client.global_ip_assignments.update(
  "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
  global_ip_assignment_update_request: {}
)

puts(global_ip_assignment)

Delete a Global IP assignment

Delete a Global IP assignment.

DELETE /global_ip_assignments/{id}

global_ip_assignment = client.global_ip_assignments.delete("6a09cdc3-8948-47f0-aa62-74ac943d6c58")

puts(global_ip_assignment)

Global IP Assignment Usage Metrics

GET /global_ip_assignments_usage

global_ip_assignments_usage = client.global_ip_assignments_usage.retrieve

puts(global_ip_assignments_usage)

Returns: global_ip (object), global_ip_assignment (object), received (object), timestamp (date-time), transmitted (object)

List all Global IP Health check types

List all Global IP Health check types.

GET /global_ip_health_check_types

global_ip_health_check_types = client.global_ip_health_check_types.list

puts(global_ip_health_check_types)

Returns: health_check_params (object), health_check_type (string), record_type (string)

List all Global IP health checks

List all Global IP health checks.

GET /global_ip_health_checks

page = client.global_ip_health_checks.list

puts(page)

Returns: created_at (string), global_ip_id (uuid), health_check_params (object), health_check_type (string), id (uuid), record_type (string), updated_at (string)

Create a Global IP health check

Create a Global IP health check.

POST /global_ip_health_checks

Optional: created_at (string), global_ip_id (uuid), health_check_params (object), health_check_type (string), id (uuid), record_type (string), updated_at (string)

global_ip_health_check = client.global_ip_health_checks.create

puts(global_ip_health_check)

Returns: created_at (string), global_ip_id (uuid), health_check_params (object), health_check_type (string), id (uuid), record_type (string), updated_at (string)

Retrieve a Global IP health check

Retrieve a Global IP health check.

GET /global_ip_health_checks/{id}

global_ip_health_check = client.global_ip_health_checks.retrieve("6a09cdc3-8948-47f0-aa62-74ac943d6c58")

puts(global_ip_health_check)

Returns: created_at (string), global_ip_id (uuid), health_check_params (object), health_check_type (string), id (uuid), record_type (string), updated_at (string)

Delete a Global IP health check

Delete a Global IP health check.

DELETE /global_ip_health_checks/{id}

global_ip_health_check = client.global_ip_health_checks.delete("6a09cdc3-8948-47f0-aa62-74ac943d6c58")

puts(global_ip_health_check)

Returns: created_at (string), global_ip_id (uuid), health_check_params (object), health_check_type (string), id (uuid), record_type (string), updated_at (string)

Global IP Latency Metrics

GET /global_ip_latency

global_ip_latency = client.global_ip_latency.retrieve

puts(global_ip_latency)

Returns: global_ip (object), mean_latency (object), percentile_latency (object), prober_location (object), timestamp (date-time)

List all Global IP Protocols

GET /global_ip_protocols

global_ip_protocols = client.global_ip_protocols.list

puts(global_ip_protocols)

Returns: code (string), name (string), record_type (string)

Global IP Usage Metrics

GET /global_ip_usage

global_ip_usage = client.global_ip_usage.retrieve

puts(global_ip_usage)

Returns: global_ip (object), received (object), timestamp (date-time), transmitted (object)

List all Global IPs

List all Global IPs.

GET /global_ips

page = client.global_ips.list

puts(page)

Returns: created_at (string), description (string), id (uuid), ip_address (string), name (string), ports (object), record_type (string), updated_at (string)

Create a Global IP

Create a Global IP.

POST /global_ips

Optional: created_at (string), description (string), id (uuid), ip_address (string), name (string), ports (object), record_type (string), updated_at (string)

global_ip = client.global_ips.create

puts(global_ip)

Returns: created_at (string), description (string), id (uuid), ip_address (string), name (string), ports (object), record_type (string), updated_at (string)

Retrieve a Global IP

Retrieve a Global IP.

GET /global_ips/{id}

global_ip = client.global_ips.retrieve("6a09cdc3-8948-47f0-aa62-74ac943d6c58")

puts(global_ip)

Returns: created_at (string), description (string), id (uuid), ip_address (string), name (string), ports (object), record_type (string), updated_at (string)

Delete a Global IP

Delete a Global IP.

DELETE /global_ips/{id}

global_ip = client.global_ips.delete("6a09cdc3-8948-47f0-aa62-74ac943d6c58")

puts(global_ip)

Returns: created_at (string), description (string), id (uuid), ip_address (string), name (string), ports (object), record_type (string), updated_at (string)