Calls
Create WebRTC or PSTN call sessions, add participants, and retrieve post-call data from a single API surface.
Create a Call
Every call request includes one or more participants. Use transport: "webrtc" for browser users and transport: "pstn" for phone numbers.
Rymi returns 201 for WebRTC-only calls and 202 when at least one PSTN participant is queued.
For high-volume PSTN fanout, see POST /v1/calls/batch which accepts up to 500 outbound recipients.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
agent_id | uuid | Yes | - | Agent to run for this call |
participants | Participant[] | Yes | - | One or more call participants |
metadata | object | No | {} | Custom key-value data stored on the call record. A test call is stored with source mcp_test |
test | boolean | No | false | Secret keys and signed-in users, not publishable keys. Marks the call as a test. With no from_number, also dials from the shared test number. The destination must be confirmed on WhatsApp for the caller |
use_test_pool | boolean | No | false | Dial from the shared test number. Studio test calls and calls with test: true may set this. A batch request ignores it |
variables | object | No | {} | Variables passed into queued PSTN jobs (accessible in agent prompt templates) |
post_call | Post-call object | No | Agent default | Per-call override for post-call intelligence. Merged with the agent's default post_call config |
Participant Object
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
transport | string | Yes | - | webrtc for browser participants, pstn for phone numbers |
identity | string | Yes | - | Browser identity string for WebRTC, or an E.164 phone number (e.g., +15551234567) for PSTN |
from_number | string | No | Tenant default | Caller ID for PSTN legs. Optional when a default number can be resolved from the tenant |
metadata | object | No | {} | Participant-scoped metadata |
Example: WebRTC Call
curl -X POST https://api.rymi.live/v1/calls \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"participants": [
{ "transport": "webrtc", "identity": "browser-tab-1" }
],
"metadata": { "source": "sdk", "session_id": "sess_123" }
}'const call = await rymi.calls.create({
agent_id: "550e8400-e29b-41d4-a716-446655440000",
participants: [{ transport: "webrtc", identity: "browser-tab-1" }],
metadata: { source: "sdk", session_id: "sess_123" },
});call = rymi.calls.create(
agent_id="550e8400-e29b-41d4-a716-446655440000",
participants=[{"transport": "webrtc", "identity": "browser-tab-1"}],
metadata={"source": "sdk", "session_id": "sess_123"},
)Response 201
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"room_name": "call_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "connecting",
"participants": [
{
"id": "participant_1",
"transport": "webrtc",
"identity": "browser-tab-1",
"status": "joining",
"access": {
"url": "wss://livekit.rymi.live",
"token": "eyJ..."
}
}
],
"agent": { "id": "550e8400-...", "name": "Aria" }
}Example: PSTN Call
curl -X POST https://api.rymi.live/v1/calls \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"participants": [
{
"transport": "pstn",
"identity": "+15551234567",
"from_number": "+15559876543"
}
],
"metadata": { "customer_name": "Alice" },
"variables": { "customer_segment": "renewal" }
}'const call = await rymi.calls.create({
agent_id: "550e8400-e29b-41d4-a716-446655440000",
participants: [
{
transport: "pstn",
identity: "+15551234567",
from_number: "+15559876543",
},
],
metadata: { customer_name: "Alice" },
variables: { customer_segment: "renewal" },
});call = rymi.calls.create(
agent_id="550e8400-e29b-41d4-a716-446655440000",
participants=[
{
"transport": "pstn",
"identity": "+15551234567",
"from_number": "+15559876543",
}
],
metadata={"customer_name": "Alice"},
variables={"customer_segment": "renewal"},
)Response 202
{
"id": "call_abc123",
"room_name": "call_call_abc123",
"status": "queued",
"participants": [
{
"id": "participant_1",
"transport": "pstn",
"identity": "+15551234567",
"status": "queued",
"telephony_leg_id": "leg_123",
"job_id": "job_xyz"
}
]
}Example: Post-call Override
Override the agent's default post-call intelligence for a specific call:
curl -X POST https://api.rymi.live/v1/calls \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"participants": [
{ "transport": "webrtc", "identity": "browser-user" }
],
"post_call": {
"summary": { "enabled": true },
"structured_extraction": {
"json_schema": {
"type": "object",
"properties": {
"booked_appointment": { "type": "boolean" },
"preferred_date": { "type": "string" }
}
}
},
"evaluation": {
"rubric": "1. Did the agent successfully book an appointment?"
}
}
}'const call = await rymi.calls.create({
agent_id: "550e8400-e29b-41d4-a716-446655440000",
participants: [{ transport: "webrtc", identity: "browser-user" }],
post_call: {
summary: { enabled: true },
structured_extraction: {
json_schema: {
type: "object",
properties: {
booked_appointment: { type: "boolean" },
preferred_date: { type: "string" },
},
},
},
evaluation: {
rubric: "1. Did the agent successfully book an appointment?",
},
},
});call = rymi.calls.create(
agent_id="550e8400-e29b-41d4-a716-446655440000",
participants=[{"transport": "webrtc", "identity": "browser-user"}],
post_call={
"summary": {"enabled": True},
"structured_extraction": {
"json_schema": {
"type": "object",
"properties": {
"booked_appointment": {"type": "boolean"},
"preferred_date": {"type": "string"},
},
}
},
"evaluation": {
"rubric": "1. Did the agent successfully book an appointment?",
},
},
)Agent defaults are merged with post_call. The resolved config is snapped onto the call record at creation time.
Errors
| Status | Meaning |
|---|---|
400 | Validation error (missing agent_id, invalid participants, etc.) |
400 | DNC conflict: one or more PSTN participants are on the Do-Not-Call list |
400 | unsupported_country or invalid_phone_number: a phone number is outside Rymi's supported countries or doesn't parse |
401 | Missing or invalid API key |
402 | Insufficient credits |
403 | Publishable key scope violation (e.g., phone channel not allowed) |
404 | Agent not found for this tenant |
409 | Agent is not publish-ready (code: agent_not_publish_ready): resolve publish validation blockers before starting live calls |
409 | phone_not_confirmed: a shared-test-line call (test: true or use_test_pool: true) to a number this account has not confirmed on WhatsApp. Confirm it, then retry. See Confirm a test destination |
422 | Provider key unavailable (code: provider_key_unavailable): the agent's LLM/STT/TTS provider key is not configured |
422 | Workspace compliance, body { "error": "<message>", "code": "<code>" }. destination_not_allowed: the PSTN number's country is not in the workspace's destination list. outside_calling_hours and no_voice_consent: the callee is outside calling hours, or has no granted voice consent. Those two apply on this route when the body includes batch_id, and on a single call when the workspace's apply_to_single_calls is on. See Compliance settings |
423 | Agent is paused by an administrator (code: agent_admin_paused) |
503 | Platform calls are disabled (code: platform_calls_disabled) |
Personal assistant calls
An agent with features.personal_calls_enabled: true places regular phone calls one at a time, each approved by the agent's owner. The owner must be signed in, so API keys, including the SDKs and a local @rymi/mcp, cannot place these calls. Hosted MCP over OAuth can. Browser calls and shared-test-line calls do not use these rules.
Add personal_call to POST /v1/calls:
| Field | Type | Required | Description |
|---|---|---|---|
recipient_number | string | Yes | The same number as the PSTN participant |
recipient_name | string | Yes | Who the owner approved |
purpose | string | Yes | Why the owner approved the call |
non_commercial | boolean | Yes | Must be true. Use a business agent for sales or business outreach |
timezone | string | No | Recipient's IANA zone, for example Asia/Kolkata. Without it, Rymi uses the contact's zone, then the country when it has one zone |
recipient_agreed_to_this_time | boolean | No | Allows this one call outside 9:00-21:00 recipient time, when the recipient agreed to the time |
The participant needs a from_number registered to this exact workspace, or a shared line Rymi has enabled for this agent. If the agent records, its recording notice (features.require_consent) must be on. Rymi plays that notice before the opener, and recording starts when the call connects. Rymi dials once and does not retry a failed dial. If the person asks not to be called again, Rymi adds the number to the workspace's do-not-call list after the call.
These checks are product safeguards. They do not replace the consent or telecom rules that apply to your calls.
| Status | Code | Meaning |
|---|---|---|
403 | personal_call_owner_only | The request is not from the owner's signed-in session |
422 | personal_call_approval_required | personal_call is missing, or its number does not match |
422 | personal_call_commercial_refused | non_commercial is not true |
422 | personal_call_single_only | A batch, campaign, scheduled call, added participant or more than one recipient |
422 | personal_call_number_required | No from_number this agent may use |
422 | personal_call_recording_notice_off | The agent records without the spoken notice |
422 | personal_call_timezone_unknown | Rymi cannot tell the recipient's time zone. Ask for it |
422 | personal_call_outside_hours | Outside 9:00-21:00 recipient time |
Confirm a test destination
Rymi's shared test lines dial on Rymi's carrier for any signed-up account, so they only call a number that account confirmed. You have two methods: the phone sends Rymi one WhatsApp message, or Rymi sends the phone a code and a person types it in Studio.
Confirming a test destination is not login verification. It never changes a login number, password, recovery detail, session or account owner, and it never links accounts. It lets the shared test lines ring that number. It is not consent to future calls, and it does not place a call. To add a number you can log in with, use Studio: Settings, or the screen that asks for your own number after you sign in. On that screen, the message and the code both set your login number if you have none.
Rymi stores a confirmed destination on the user behind the credential, the same user POST /v1/calls checks, and never on the workspace. The older whatsapp_confirmed_phones list and a verified login number also count. A code or message only proves the number for the account that asked.
Start confirmation
A secret key needs calls:write. A signed-in account holder can call it too. Publishable keys and impersonation receive 403.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
phone | string | Yes | The destination, in a supported country. Rymi stores it as E.164 |
Response 200 (not yet confirmed)
{
"confirmed": false,
"phone": "+919876543210",
"wa_url": "https://wa.me/919311623592?text=Confirm%20this%20number%20for%20Rymi%20test%20calls%20only",
"message_text": "Confirm this number for Rymi test calls only",
"expires_in": 600,
"otp_template": false
}Open wa_url on that phone and send message_text unchanged. The request lasts expires_in seconds (10 minutes). One user holds the pending request for a number. Each user can start 20 confirmations a day.
When the number is already confirmed, the response is { "confirmed": true, "phone": "+919876543210" } and no link.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | The number does not parse, or it is outside the supported countries | |
403 | Publishable key, impersonation, or no signed-in user | |
409 | in_progress | Someone is already confirming this number. Try again in 10 minutes |
429 | daily_limit | This user has started 20 confirmations today |
503 | WhatsApp confirmation is not configured on this server |
Request a code
For a secret key with calls:write, or a hosted MCP OAuth token. Rymi sends a 6-digit code to the number on WhatsApp and returns delivery details. The code never appears in the response. Sending does not confirm the number.
| Field | Type | Required | Description |
|---|---|---|---|
phone | string | Yes | The destination, in a country where Rymi sends codes |
curl -X POST https://api.rymi.live/v1/phone-confirmation/request-code \
-H "Authorization: Bearer $RYMI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"phone": "+919876543210"}'const sent = await rymi.phoneConfirmation.requestCode({ phone: '+919876543210' });
console.log(sent.entry_url, sent.expires_in, sent.resend_after);sent = rymi.phone_confirmation.request_code("+919876543210")
print(sent["entry_url"], sent["expires_in"], sent["resend_after"])Response 200
{
"sent": true,
"confirmed": false,
"phone": "+919876543210",
"phone_masked": "+9198…10",
"channel": "whatsapp",
"expires_in": 600,
"resend_after": 60,
"max_attempts": 5,
"entry_url": "https://studio.rymi.live/verify-test-number#%2B919876543210"
}A person opens entry_url in a browser signed in to the same Rymi account and types the code there. Secret keys and MCP tokens cannot submit a code. POST /v1/phone-confirmation/confirm-code accepts only a signed-in browser session, which keeps the code out of assistant transcripts and tool logs.
Do not ask anyone to paste a code into a chat, a ticket or a tool argument.
When the number is already confirmed, the response is { "sent": false, "confirmed": true, "phone": "+919876543210" } and Rymi sends nothing.
A code lasts 10 minutes, works once and allows 5 attempts. Rymi sends one code per number per minute, 3 per number per hour, 5 per number per day and 5 per user per day. Browsers pass a Turnstile check before a send. Keys and MCP tokens skip that check and share a separate limit of 50 sends a day across Rymi.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | The number does not parse, or it is outside the supported countries | |
403 | Publishable key, impersonation, or a browser session. Studio sends codes through its own step | |
403 | country_not_allowed | Rymi does not send codes to this country yet. Use the WhatsApp message |
429 | rate_limited | Too many codes. retry_after gives the seconds to wait |
502 | send_failed | WhatsApp refused the send. Use the WhatsApp message |
503 | unavailable, daily_cap | Code sending is off or at today's limit. Use the WhatsApp message |
Confirmation status
A secret key needs calls:read. The response is { "confirmed": true } or { "confirmed": false } for the caller only. While a code is waiting, the response also has code, with status (awaiting_entry), channel, expires_in, attempts_left, resend_after and entry_url. It never contains the code. This route does not confirm the number. The number becomes confirmed when Rymi receives message_text from that phone while a request for it is open.
Errors
| Status | Meaning |
|---|---|
400 | The number does not parse |
403 | Publishable key, impersonation, or no signed-in user |
List Calls
Returns a paginated list of call records for the authenticated tenant.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 200 | Max records to return (max 1000) |
offset | integer | 0 | Records to skip |
cursor | string | - | Resume from a previous call ID when traversing call history |
status | string | - | Filter by call status: queued, ringing, in_progress, completed, failed, no_answer, busy, or canceled |
agent_id | uuid | - | Filter to calls for a single agent |
Example Request
curl "https://api.rymi.live/v1/calls?limit=50&status=completed" \
-H "Authorization: Bearer YOUR_API_KEY"const { calls } = await rymi.calls.list({ limit: 50, status: "completed" });result = rymi.calls.list(limit=50, status="completed")Response 200
{
"calls": [
{
"id": "call_abc123",
"room_name": "call_call_abc123",
"agent_id": "550e8400-...",
"status": "completed",
"started_at": "2026-03-01T10:00:00Z",
"ended_at": "2026-03-01T10:05:00Z",
"bill_duration": 300,
"billable_seconds": 300,
"total_cost": 0.30,
"provider_cost": 0.18,
"provider_cost_breakdown": { "llm": 0.05, "stt": 0.04, "tts": 0.09 },
"provider_cost_calculated_at": "2026-03-01T10:05:10Z",
"end_reason": "participant_disconnected",
"metadata": { "batch_id": "batch_1710" },
"intelligence_status": "completed",
"sentiment": "positive",
"participant_count": 1,
"primary_participant": {
"identity": "+15551234567",
"transport": "pstn"
},
"participants": [
{ "id": "cp_1", "role": "caller", "transport": "pstn", "identity": "+15551234567", "status": "completed" }
]
}
],
"total": 1,
"limit": 50,
"offset": 0,
"next_cursor": null
}sentiment is the post-call sentiment, null until post-call analysis finishes. The summary is on Call Detail.
end_reason (also on the Call Detail response) is an open string, not a closed enum. There is no database constraint on it, and PSTN calls report carrier-specific values. Treat unknown values gracefully rather than exhaustively matching.
Common values:
| Group | Values |
|---|---|
| Clean ends | participant_disconnected, client_disconnected, normal_hangup, natural_end, end_call_tool, agent_ended_call, completed |
| Limits and silence | time_limit_exceeded, max_call_duration, silence_timeout, silence_dead_air, demo_idle_timeout |
| Voicemail | voicemail_detected, voicemail_left |
| Failures | insufficient_funds, no_provider_connected, room_setup_failed, room_connection_failed, session_init_failed, session_start_failed, worker_error, session_error, llm_unavailable, server_shutdown |
| Reaper backstop | reaper_in_progress_timeout, reaper_post_dial_timeout, reaper_queued_timeout |
| Carrier (PSTN) | <carrier>_<status>, e.g. twilio_completed, plivo_no-answer, vonage_rejected, telnyx_hangup |
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Publishable keys cannot list call history |
List Active Calls
Returns the same payload shape as GET /v1/calls, filtered to calls with in_progress status.
Example Request
curl https://api.rymi.live/v1/calls/active \
-H "Authorization: Bearer YOUR_API_KEY"const { calls } = await rymi.calls.active();result = rymi.calls.active()Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
Add Participants
Bring a browser participant into an existing PSTN call, or queue another PSTN leg on an active session.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | uuid | Call ID |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
participants | Participant[] | Yes | One or more participants to add |
Example Request
curl -X POST https://api.rymi.live/v1/calls/call_abc123/participants \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"participants": [
{ "transport": "webrtc", "identity": "browser-tab-2" }
]
}'const result = await rymi.calls.addParticipants("call_abc123", {
participants: [{ transport: "webrtc", identity: "browser-tab-2" }],
});result = rymi.calls.add_participants(
"call_abc123",
participants=[{"transport": "webrtc", "identity": "browser-tab-2"}],
)Errors
| Status | Meaning |
|---|---|
400 | Invalid participant data |
401 | Missing or invalid API key |
403 | Publishable keys cannot add call participants, or the call does not belong to this tenant |
404 | Call not found |
409 | Agent is not publish-ready (code: agent_not_publish_ready) |
422 | Same workspace compliance codes as Create a Call: destination_not_allowed on any PSTN leg; outside_calling_hours and no_voice_consent when the workspace's apply_to_single_calls is on. Add participant is a single call |
Call Detail
Returns the expanded view of a call including participants, transcript, recording metadata, intelligence results, and event log.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | uuid | Call ID |
Example Request
curl https://api.rymi.live/v1/calls/call_abc123 \
-H "Authorization: Bearer YOUR_API_KEY"const call = await rymi.calls.retrieve("call_abc123");call = rymi.calls.retrieve("call_abc123")Response 200
{
"id": "call_abc123",
"status": "completed",
"intelligence_status": "completed",
"bill_duration": 145,
"total_cost": 0.21,
"transcript": {
"text": "Caller: Hello\nAgent: Hi there, how can I help?",
"segments": [
{
"speaker": "user",
"text": "Hello",
"sequence": 0,
"started_at_ms": 0,
"ended_at_ms": 900,
"is_final": true,
"source": "runtime"
},
{
"speaker": "agent",
"text": "Hi there, how can I help?",
"sequence": 1,
"started_at_ms": 1000,
"ended_at_ms": 2500,
"is_final": true,
"source": "runtime"
}
],
"raw": [
{
"id": "t_1",
"type": "user_input",
"response": "Hello"
}
]
},
"recording": {
"id": "rec_1",
"status": "completed",
"format": "wav",
"provider_recording_id": "prov_123",
"metadata": {
"stereo_mix": {
"signed_url": "https://storage.rymi.live/recordings/..."
}
}
},
"intelligence": {
"status": "completed",
"summary": "Caller asked for support and the agent resolved the issue.",
"sentiment": "neutral",
"structured_data": {
"customer_intent": "support"
},
"evaluation": {
"passed": true,
"score": 1,
"reasoning": "The issue was resolved successfully."
},
"errors": []
},
"events": [
{
"id": "evt_1",
"level": "info",
"source": "post_call",
"message": "Post-call analysis completed."
}
]
}Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Publishable keys cannot fetch call details |
404 | Call not found |
Call Summary
Returns the persisted post-call summary and sentiment. It serves previously computed results and runs no LLM analysis at request time.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | uuid | Call ID |
Example Request
curl https://api.rymi.live/v1/calls/call_abc123/summary \
-H "Authorization: Bearer YOUR_API_KEY"const summary = await rymi.calls.summary("call_abc123");summary = rymi.calls.summary("call_abc123")Response 200
{
"status": "completed",
"sentiment": "positive",
"summary": "The caller confirmed the appointment and no follow-up was needed."
}Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
404 | Call not found or summary not yet available |
Call Transcript
Returns the raw and normalized transcript for a completed call.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | uuid | Call ID |
Example Request
curl https://api.rymi.live/v1/calls/call_abc123/transcript \
-H "Authorization: Bearer YOUR_API_KEY"const transcript = await rymi.calls.transcript("call_abc123");transcript = rymi.calls.transcript("call_abc123")Response 200
{
"transcript": [
{
"id": "t_1",
"type": "user_input",
"response": "Hello?",
"speaker": "user",
"sequence": 0,
"started_at_ms": 0,
"ended_at_ms": 850,
"is_final": true,
"source": "runtime"
}
],
"text": "Caller: Hello?",
"segments": [
{
"speaker": "user",
"text": "Hello?",
"sequence": 0,
"started_at_ms": 0,
"ended_at_ms": 850,
"is_final": true,
"source": "runtime"
}
]
}Transcript Segment Fields
| Field | Type | Description |
|---|---|---|
speaker | string | user or agent |
text | string | Transcribed text |
sequence | integer | Zero-based segment order |
started_at_ms | integer | Segment start time in milliseconds from call start |
ended_at_ms | integer | Segment end time in milliseconds from call start |
is_final | boolean | Whether this is a final (non-interim) transcript segment |
source | string | Transcript source (e.g., runtime) |
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
404 | Call not found or transcript not yet available |
Call Recording
Returns the latest recording metadata plus time-limited signed URLs for audio download.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | uuid | Call ID |
Example Request
curl https://api.rymi.live/v1/calls/call_abc123/recording \
-H "Authorization: Bearer YOUR_API_KEY"const recording = await rymi.calls.recording("call_abc123");recording = rymi.calls.recording("call_abc123")Response 200
{
"call_id": "call_abc123",
"recording": {
"id": "rec_1",
"status": "completed",
"format": "wav",
"provider_recording_id": "prov_123",
"metadata": {
"stereo_mix": {
"signed_url": "https://storage.rymi.live/recordings/..."
}
}
}
}Recording Status Values
| Status | Description |
|---|---|
processing | Recording is being captured or finalized (initial state) |
completed | Recording is available for download |
failed | Recording processing failed |
When recording is not enabled for a call, no recording record exists and the endpoint returns 404.
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Publishable keys cannot access recordings |
404 | Call not found or recording not available |
End a Call
Force-ends an active call by closing the LiveKit room. The call transitions to completed and post-call processing is triggered.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | uuid | Call ID |
Example Request
curl -X POST https://api.rymi.live/v1/calls/call_abc123/end \
-H "Authorization: Bearer YOUR_API_KEY"const result = await rymi.calls.end("call_abc123");result = rymi.calls.end("call_abc123")Response 200
{
"status": "ended",
"id": "call_abc123",
"message": "Call has been terminated."
}Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Publishable keys cannot end calls |
404 | Call not found |
409 | Call is already completed or failed |
Call Events
Returns the event log for a specific call, including lifecycle transitions and post-call processing events. Use it to build real-time dashboards and debug call flows.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | uuid | Call ID |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Max records to return (max 200) |
offset | integer | 0 | Records to skip |
Example Request
curl "https://api.rymi.live/v1/calls/call_abc123/events?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"Response 200
{
"events": [
{
"id": "evt_1",
"call_id": "call_abc123",
"level": "info",
"source": "lifecycle",
"message": "Call created",
"created_at": "2026-03-01T10:00:00Z"
},
{
"id": "evt_2",
"call_id": "call_abc123",
"level": "info",
"source": "lifecycle",
"message": "PSTN leg connected",
"created_at": "2026-03-01T10:00:05Z"
},
{
"id": "evt_3",
"call_id": "call_abc123",
"level": "info",
"source": "post_call",
"message": "Post-call analysis completed.",
"created_at": "2026-03-01T10:05:30Z"
}
],
"total": 3,
"offset": 0,
"limit": 20
}Event Fields
| Field | Type | Description |
|---|---|---|
id | string | Event ID |
call_id | string | Associated call ID |
level | string | info, warning, or error |
source | string | Event source: lifecycle, post_call, telephony, livekit |
message | string | Human-readable event description |
created_at | string | ISO 8601 timestamp |
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Publishable keys cannot access call events |
404 | Call not found |
Reprocess Post-call Intelligence
Queues post-call intelligence again for a call. Run it after you change the agent's extraction schema or evaluation criteria and want fresh analysis.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | uuid | Call ID |
Example Request
curl -X POST https://api.rymi.live/v1/calls/call_abc123/reprocess \
-H "Authorization: Bearer YOUR_API_KEY"const result = await rymi.calls.reprocess("call_abc123");result = rymi.calls.reprocess("call_abc123")Response 202
{
"status": "queued",
"job_id": "job_123",
"message": "Post-call intelligence reprocessing has been queued."
}Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Publishable keys cannot trigger reprocessing |
404 | Call not found |
409 | Post-call intelligence is already being processed for this call |
Queue Stats
Returns the outbound dialing queue counts for PSTN calls.
Example Request
curl https://api.rymi.live/v1/calls/queue/stats \
-H "Authorization: Bearer YOUR_API_KEY"const stats = await rymi.calls.queueStats();stats = rymi.calls.queue_stats()Response 200
{
"waiting": 12,
"active": 2,
"completed": 340,
"failed": 4
}List Scheduled Callbacks
Returns the callbacks your agents scheduled for themselves with the Scheduled callbacks tool, latest due time first. The platform places each one at its due time. There is no SDK or MCP wrapper for this endpoint yet.
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
agent_id | string | No | - | Only callbacks scheduled by this agent |
status | string | No | - | One of pending, dispatching, placed, no_answer_retry, done, cancelled, failed |
limit | integer | No | 50 | 1 to 200 |
offset | integer | No | 0 | Rows to skip |
Example Request
curl "https://api.rymi.live/v1/scheduled-callbacks?status=pending&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"Response 200
{
"callbacks": [
{
"id": "6c1f5e0a-2b7d-4c0e-9a61-3d2f8b4e7a10",
"agent_id": "16e0724d-bc5e-4a82-9792-f3ac83c561f0",
"agent_name": "Isha",
"to_number": "+919876543210",
"due_at": "2026-10-06T12:30:00+00:00",
"status": "pending",
"reason": "driving, wants callback",
"notes": "Rohit, budget 50 lakh, Skyline Greens",
"attempts": 0,
"result_call_id": null,
"last_error": null,
"created_at": "2026-10-05T10:00:00+00:00"
}
],
"total": 1,
"offset": 0,
"limit": 50
}| Field | Description |
|---|---|
due_at | When the call is due, in UTC. 2026-10-06T12:30:00+00:00 is 6:00 pm IST |
status | See the statuses in the guide |
attempts | Calls placed so far (0, 1 or 2) |
result_call_id | The call that was placed, once there is one. Fetch it with Call Detail |
last_error | Why it did not go out: no_caller_id, dnc, dnc_lookup_failed, no_answer, busy, or cancelled by user |
Errors
| Status | Meaning |
|---|---|
400 | status is not one of the listed values |
401 | Missing or invalid API key |
403 | Publishable keys cannot read scheduled callbacks |
Cancel a Scheduled Callback
Stops a callback that has not been placed yet. It works while the status is pending or no_answer_retry.
Example Request
curl -X POST https://api.rymi.live/v1/scheduled-callbacks/6c1f5e0a-2b7d-4c0e-9a61-3d2f8b4e7a10/cancel \
-H "Authorization: Bearer YOUR_API_KEY"Response 200
{ "status": "cancelled", "id": "6c1f5e0a-2b7d-4c0e-9a61-3d2f8b4e7a10" }Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Publishable keys cannot cancel scheduled callbacks |
404 | No callback with that id in your workspace |
409 | The callback is already being placed or has finished, so it cannot be cancelled |
Publishable Key Rules
When using a publishable key (sb_publishable_...) to create calls:
- WebRTC: Allowed when the key permits the
webchannel. - PSTN: Allowed only when the key permits the
phonechannel. - Phone limit: Publishable phone calls must target exactly one PSTN participant and cannot override
agent_idorfrom_number. - Read restrictions: Publishable keys cannot list call history, fetch recordings, access transcripts, or trigger reprocessing.

