Agents
Agents are the reusable voice personas that power calls. Each agent stores its prompt, persona/playbook structure, provider routing, post-call defaults, and feature flags.
List Agents
Returns a paginated list of agents for the authenticated tenant.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Max records to return (max 500) |
offset | integer | 0 | Records to skip |
Example Request
curl "https://api.rymi.live/v1/agents?limit=10&offset=0" \
-H "Authorization: Bearer YOUR_API_KEY"const { agents } = await rymi.agents.list({ limit: 10, offset: 0 });result = rymi.agents.list(limit=10, offset=0)Response 200
{
"agents": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Priya - Sales Specialist",
"voice": "Aoede",
"llm_provider": "gemini",
"llm_model": "gemini-2.5-flash",
"agent_kind": "custom",
"language": "en-US",
"created_at": "2026-03-01T10:00:00Z"
}
],
"total": 1,
"offset": 0,
"limit": 10
}Client role
A signed-in user whose role in this workspace is client gets a reduced agent in agents. Prompt, voice, models, tools, and the rest of the row are left out. Secret keys are treated as the owner and still get the full row.
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Priya",
"language": "hi-IN",
"published": true,
"retiring": false,
"persona": { "name": "Priya", "role": "Front desk" },
"advanced": { "transferNumber": "+919876543210" }
}| Field | Type | Description |
|---|---|---|
id | uuid | Agent id |
name | string | Agent name |
language | string or null | Agent language |
published | boolean | True when published_snapshot_id is set |
retiring | boolean | Present on this list. True when a model, voice, or SKU the agent uses is retiring |
persona.name | string or null | Spoken name |
persona.role | string or null | Role |
advanced.transferNumber | string or null | Number the agent transfers a caller to |
GET /v1/agents/:id for the same role returns that object without retiring. The list wrapper (agents, total, offset, limit) is unchanged.
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Publishable keys cannot list agents |
Model and Voice Catalog
Returns the model catalog and voice list available for agent configuration. Populate dropdowns and pickers from this before you create or update an agent.
Example Request
curl https://api.rymi.live/v1/agents/llm-options \
-H "Authorization: Bearer YOUR_API_KEY"const { models, voices } = await rymi.agents.llmOptions();result = rymi.agents.llm_options()Response 200
{
"models": [
{
"provider": "google",
"provider_name": "Google",
"model_id": "gemini-2.5-flash",
"label": "Gemini 2.5 Flash",
"type": ["llm"],
"plan_locked": false,
"required_plan": null,
"byok_required": false,
"byok_provider_id": null,
"modality": "standard",
"latency_ms": null,
"cost_per_min": null,
"reasoning_supported": false
}
],
"voices": [
{
"id": "voice_aoede",
"provider": "google",
"name": "Aoede",
"label": "Aoede",
"gender": "Female",
"supported_model_ids": ["gemini-2.5-flash"],
"is_active": true,
"byok_required": false,
"byok_provider_id": null
}
]
}Each model uses model_id as its identifier and provider as the provider key. The type array records which roles the entry can fill (llm, stt, tts). Voice entries carry the human-readable label, gender, and supported_model_ids (the models a voice is compatible with). byok_required is true when the provider requires your own key.
Agent Kind
Every agent is one of two kinds, set with agent_kind on create or update. The kind also determines how the agent is billed. See Pricing model.
| Kind | API Value | Stack | Billing |
|---|---|---|---|
| Custom (default) | custom | You choose the STT, LLM, and TTS models (and optional fallbacks). | Component cost (sum of each model's per-minute rate) plus the Rymi runtime fee |
| Managed | managed | A ready-made, locked stack chosen for you. Set managed_sku_id to the chosen SKU. | The SKU's fixed published price_per_min |
List the available managed SKUs (with prices and their locked stacks) via GET /v1/managed-skus. Some SKUs are limited to specific countries: the managed Hindi SKUs are available in India only. For custom agents, call GET /v1/agents/llm-options for valid model and voice IDs.
Language Routing
The language field is the primary language the agent starts with. The supported_languages field lists every language this agent may run.
- Use an explicit locale such as
en-USorhi-INforlanguage. - Include one or more locales in
supported_languages. - For custom agents, Rymi resolves a valid STT, LLM, and TTS stack for each selected language before the agent is saved.
- Automatic language detection and mid-call dynamic rerouting are not default MVP behavior.
- Routing is derived from the selected languages and supported provider capabilities. Public API clients do not need to manage provider routing tables.
Create Agent
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | - | Studio label: the name in your sidebar and agent list (100 characters or fewer recommended). The name the agent speaks is persona.name, which defaults to this label |
system_prompt | string | No | - | Raw system prompt. With advanced.prompt_mode: "raw" the agent uses it word for word. In builder mode (the default), Rymi extracts persona and playbook from it when you send neither; when you send them too, it appends the prompt as an "Additional instructions" section |
voice | string | No | Aoede | TTS voice ID from GET /v1/agents/llm-options |
language | string | No | en-US | Primary call language locale (for example, en-US, hi-IN) |
supported_languages | string[] | No | [language] | Locales this agent may run. The API resolves a valid stack for each selected language |
agent_kind | string | No | custom | custom (you pick the stack) or managed (Rymi Managed SKU). See Agent Kind |
managed_sku_id | string | null | No | null | Required when agent_kind is managed: the SKU ID from GET /v1/managed-skus. Must be null for custom agents |
llm_provider | string | No | Stack default | gemini, openai, anthropic, sarvam, groq, xai (realtime) or ultravox (realtime) |
llm_model | string | No | Stack default | LLM model ID (a realtime model bundles STT/TTS) |
stt_provider | string | No | Stack default | Speech-to-text provider |
stt_model | string | No | Stack default | STT model ID |
tts_provider | string | No | Stack default | Text-to-speech provider |
tts_model | string | No | Stack default | TTS model ID |
llm_fallback_provider | string | null | No | - | Secondary LLM provider used if the primary fails. null clears it |
llm_fallback_model | string | null | No | - | Secondary LLM model. null clears it |
stt_fallback_provider | string | null | No | - | Secondary STT provider. null clears it |
stt_fallback_model | string | null | No | - | Secondary STT model. null clears it |
tts_fallback_provider | string | null | No | - | Secondary TTS provider. null clears it |
tts_fallback_model | string | null | No | - | Secondary TTS model. null clears it |
custom_llm_url | string | null | No | - | Self-hosted LLM endpoint (https:// or wss://). Enterprise only; null clears |
custom_voice_url | string | null | No | - | Self-hosted TTS endpoint. Enterprise only; null clears |
custom_voice_mode | string | No | rymi | Wire format for custom_voice_url: rymi or openai-compat |
custom_transcriber_url | string | null | No | - | Self-hosted STT endpoint. Enterprise only; null clears |
persona | Persona object | No | - | Structured role, tone, audience, and voice config |
playbook | Playbook object | No | - | Opener, qualification flow, scripts, CTA, and escalation rules |
advanced | advanced object | No | - | Runtime tuning (endpointing, turn timing) |
features | Features object | No | - | Feature flags (recording, transcription) |
post_call | Post-call object | No | - | Default post-call intelligence config |
tools | object[] | No | - | Tool bindings: API tools (call_webhook), handoff and others. A connector tool (calendar, lookup_customer, lookup_ticket, create_ticket, send_whatsapp_message, send_telegram_message, send_asset) is on for this agent only when its binding has enabled: true; a connected app alone switches nothing on. An update replaces the whole array, so read the agent first. send_whatsapp_message needs template entries in provider_settings.templates, and an invalid entry returns 400; see WhatsApp templates. See API Tools |
provider_config | object | No | - | Read-only. Server-derived from the resolved stack + supported languages on every write; ignored if sent as input and cannot be set via the API |
Persona Object
| Field | Type | Description |
|---|---|---|
role | string | Agent's role description (e.g., "Insurance sales specialist") |
toneOverride | string | Speaking style (e.g., "warm and concise") |
audienceDescription | string | Who the agent talks to |
voiceConfig | object | Voice settings: { "voiceId": "Aoede", "language": "en-US", "bargeInEnabled": true } |
successCriteria | string[] | What a successful call looks like |
callerPersonas | object[] | Caller type variants: { type, approach } |
The full persona shape (company fields, knowledge base) is in the Configuration Reference below.
Playbook Object
| Field | Type | Description |
|---|---|---|
opener | string | Opening message the agent uses to start the conversation |
qualificationFlow | object[] | Questions and what to listen for: { question, listensFor } |
requiredSlots | object[] | Data to collect: { name, description, required } |
objectionHandlers | object[] | How to handle pushback: { trigger, response } |
scripts | object[] | Canned responses for specific situations: { title, when, content } |
closingCTA | string | Primary call-to-action the agent drives toward |
fallbackCTA | string | Fallback if the primary CTA fails |
escalationRule | string | When/how to escalate to a human |
endCallMessage | string | Closing message or sign-off script |
advanced object
Runtime tuning: turn timing, speech detection, and safety limits. See the Configuration Reference for the full field list (maxCallDuration, silencePromptDelay, smartEndpointing, STT options, …).
Features Object
| Field | Type | Default | Description |
|---|---|---|---|
recording_enabled | boolean | false | Record both sides of each call |
transcription_enabled | boolean | true | Transcribe and store each call |
require_consent | boolean | true | Announce recording at call start. On create, when you omit this field, a saved workspace notice of on writes require_consent: true; off writes false. Before any settings are saved, the default (true) stands. A value you send wins. Existing agents stay as they are. See Compliance settings |
Post-call Object
| Field | Type | Default | Description |
|---|---|---|---|
summary.enabled | boolean | true | Generate a summary after each call |
summary.prompt | string | - | Custom instructions for the summary LLM (e.g. "highlight objections") |
structured_extraction.json_schema | object | - | JSON Schema defining the structured data to extract from the transcript |
structured_extraction.prompt | string | - | Custom instructions for the extraction LLM (auto-generated from schema if omitted) |
evaluation.rubric | string | - | Numbered list of quality criteria for call scoring |
model.provider | string | - | LLM provider for post-call analysis: gemini or openai. Defaults to platform setting |
model.model | string | - | Specific model ID (e.g. gemini-2.5-flash, gpt-4o-mini). Defaults to platform setting |
Example: Minimal
curl -X POST https://api.rymi.live/v1/agents \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Support Agent"
}'Example: Full Configuration
curl -X POST https://api.rymi.live/v1/agents \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Priya - Sales Specialist",
"system_prompt": "You are Priya, a friendly insurance sales agent who speaks Hindi with a Delhi accent.",
"voice": "Aoede",
"language": "hi-IN",
"llm_provider": "gemini",
"llm_model": "gemini-2.5-flash",
"persona": {
"role": "Insurance sales specialist",
"toneOverride": "warm, patient, and persuasive",
"audienceDescription": "Hindi-speaking consumers in North India",
"voiceConfig": { "voiceId": "Aoede", "language": "hi-IN", "bargeInEnabled": true },
"successCriteria": ["Lead qualified", "Follow-up call booked"]
},
"playbook": {
"opener": "Namaste! Main Priya hoon, Acme Insurance se. Kaise madad kar sakti hoon?",
"qualificationFlow": [
{ "question": "What type of coverage are you looking for?", "listensFor": "Interest in health insurance" },
{ "question": "How many family members need coverage?", "listensFor": "Family size and decision-maker status" }
],
"objectionHandlers": [
{ "trigger": "Premium feels too expensive", "response": "Acknowledge, then compare against out-of-pocket hospital costs." }
],
"closingCTA": "Book a follow-up call with our advisor",
"escalationRule": "Transfer to a human when the customer requests a supervisor",
"endCallMessage": "Thank you for your time! We will send the policy details to your email."
},
"advanced": {
"maxCallDuration": 600,
"silencePromptDelay": 8,
"smartEndpointing": true
},
"features": {
"recording_enabled": true,
"transcription_enabled": true,
"require_consent": true
},
"post_call": {
"summary": { "enabled": true },
"structured_extraction": {
"json_schema": {
"type": "object",
"properties": {
"interested_plan": { "type": "string" },
"family_size": { "type": "integer" },
"booked_followup": { "type": "boolean" }
}
}
},
"evaluation": {
"rubric": "1. Did the agent qualify the lead?\n2. Did the agent book a follow-up?"
}
}
}'Response 201
{
"status": "created",
"id": "550e8400-e29b-41d4-a716-446655440000"
}Errors
| Status | Meaning |
|---|---|
400 | Validation error (missing name, invalid agent_kind/managed_sku_id, etc.) |
401 | Missing or invalid API key |
402 | Insufficient credits |
403 | sku_not_available_in_country: the managed SKU is not available in your workspace's country, or the workspace has no country set. See Country availability |
Get Agent
Returns the full agent configuration including the compiled prompt.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | uuid | Agent ID |
Example Request
curl https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer YOUR_API_KEY"const agent = await rymi.agents.retrieve("550e8400-e29b-41d4-a716-446655440000");agent = rymi.agents.retrieve("550e8400-e29b-41d4-a716-446655440000")Response 200
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Priya - Sales Specialist",
"voice": "Aoede",
"language": "hi-IN",
"persona": {
"role": "Insurance sales specialist",
"toneOverride": "warm and persuasive",
"audienceDescription": "Hindi-speaking consumers in North India",
"voiceConfig": { "voiceId": "Aoede", "language": "hi-IN" }
},
"playbook": {
"opener": "Namaste! Main Priya hoon, Acme Insurance se.",
"closingCTA": "Book a follow-up call with our advisor"
},
"compiled_prompt": "You are Priya...",
"llm_provider": "gemini",
"llm_model": "gemini-2.5-flash",
"agent_kind": "custom",
"managed_sku_id": null,
"managed_sku_upgrade": null,
"features": {
"recording_enabled": true,
"transcription_enabled": true
},
"post_call": {
"summary": { "enabled": true },
"evaluation": { "rubric": null }
},
"updated_at": "2026-03-01T10:00:00Z"
}Response Fields
| Field | Type | Description |
|---|---|---|
managed_sku_upgrade | object | null | Object or null. Present on managed agents whose SKU has a replacement_sku_id. Contains { to: string, deprecation_date: string | null }. |
The client role gets the reduced object from List Agents, without retiring.
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Publishable keys can only read the agent the key is bound to, or the agent belongs to another workspace |
404 | Agent not found for this tenant |
Update Agent
Pass only the fields you want to change. Unspecified fields remain unchanged. PUT and PATCH behave identically: both apply a partial update to the agent.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | uuid | Agent ID |
Request Body
Accepts the same fields as Create Agent. All fields are optional.
Example Request
curl -X PUT https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"system_prompt": "Updated instructions for handling renewals...",
"post_call": {
"summary": { "enabled": true },
"structured_extraction": {
"json_schema": {
"type": "object",
"properties": {
"renewal_confirmed": { "type": "boolean" }
}
}
}
}
}'const result = await rymi.agents.update("550e8400-e29b-41d4-a716-446655440000", {
system_prompt: "Updated instructions for handling renewals...",
post_call: {
summary: { enabled: true },
structured_extraction: {
json_schema: {
type: "object",
properties: {
renewal_confirmed: { type: "boolean" },
},
},
},
},
});result = rymi.agents.update(
"550e8400-e29b-41d4-a716-446655440000",
system_prompt="Updated instructions for handling renewals...",
post_call={
"summary": {"enabled": True},
"structured_extraction": {
"json_schema": {
"type": "object",
"properties": {
"renewal_confirmed": {"type": "boolean"},
},
}
},
},
)Response 200
{
"status": "updated"
}Errors
| Status | Meaning |
|---|---|
400 | Validation error |
401 | Missing or invalid API key |
403 | Client role sent anything other than { "advanced": { "transferNumber": "+919876543210" } }. Body: { "error": "Your role can change only the transfer number", "code": "field_not_permitted" } |
404 | Agent not found for this tenant |
Clone Agent
Creates a duplicate of an existing agent. The clone gets " (Copy)" appended to its name and is otherwise identical: same persona, playbook, advanced config, post-call settings, and provider stack. The original is unchanged.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | uuid | Agent ID to clone |
Example Request
curl -X POST https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000/clone \
-H "Authorization: Bearer YOUR_API_KEY"const clone = await rymi.agents.clone("550e8400-e29b-41d4-a716-446655440000");clone = rymi.agents.clone("550e8400-e29b-41d4-a716-446655440000")Response 201
{
"status": "created",
"id": "7f3e9a12-b4c1-41f2-a890-556677889900"
}Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Agent belongs to a different tenant |
404 | Agent not found |
List Agent Calls
Returns a paginated list of calls made with a specific agent. Use it to monitor per-agent performance and debug call flows.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | uuid | Agent ID |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Max records to return (max 200) |
offset | integer | 0 | Records to skip |
status | string | All statuses | Filter by call status: queued, ringing, in_progress, completed, or failed |
Example Request
curl "https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000/calls?limit=20&status=completed" \
-H "Authorization: Bearer YOUR_API_KEY"const { calls } = await rymi.agents.listCalls("550e8400-e29b-41d4-a716-446655440000", {
limit: 20,
status: "completed",
});result = rymi.agents.list_calls(
"550e8400-e29b-41d4-a716-446655440000",
limit=20,
status="completed",
)Response 200
{
"calls": [
{
"id": "call_abc123",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"started_at": "2026-03-01T10:00:00Z",
"ended_at": "2026-03-01T10:05:00Z",
"bill_duration": 300,
"total_cost": 0.30
}
],
"total": 1,
"offset": 0,
"limit": 20,
"agent_id": "550e8400-e29b-41d4-a716-446655440000"
}Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Publishable keys cannot access call history, or agent does not belong to you |
404 | Agent not found |
Place Task Call
Places a one-shot task call through an opted-in agent with structured data extraction. The agent must have features.task_calls_enabled: true and a published snapshot.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | uuid | Agent ID to place the call through |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Destination phone number in strict E.164 format (for example +919812345678) |
on_behalf_of | string | Yes | Business or person the call is on behalf of (1 to 120 characters) |
instructions | string | Yes | What the call must do in plain words (1 to 4000 characters) |
return_fields | array | Yes | 1 to 20 fields to extract from the call transcript. Names must be unique snake_case |
return_fields[].name | string | Yes | Field identifier (^[a-z][a-z0-9_]{0,39}$) |
return_fields[].description | string | Yes | Guidance for the extractor (1 to 300 characters) |
return_fields[].type | string | No | Data type: string (default), number, or boolean |
opening_line | string | No | Custom first line spoken by the agent (1 to 300 characters). When omitted, uses the agent's default opener or disclosure line |
from_number | string | No | Caller ID registered to the workspace. When omitted, uses the agent's attached number |
Example Request
curl -X POST https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000/task-calls \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+919812345678",
"on_behalf_of": "Sharma Clinic",
"instructions": "Confirm tomorrow 10am appointment and ask how many people are coming.",
"return_fields": [
{ "name": "booked", "description": "Did they confirm the appointment?", "type": "boolean" },
{ "name": "party_size", "description": "Number of people coming", "type": "number" }
]
}'const res = await rymi.agents.placeTaskCall("550e8400-e29b-41d4-a716-446655440000", {
to: "+919812345678",
on_behalf_of: "Sharma Clinic",
instructions: "Confirm tomorrow 10am appointment and ask how many people are coming.",
return_fields: [
{ name: "booked", description: "Did they confirm the appointment?", type: "boolean" },
{ name: "party_size", description: "Number of people coming", type: "number" },
],
});res = rymi.agents.place_task_call(
"550e8400-e29b-41d4-a716-446655440000",
to="+919812345678",
on_behalf_of="Sharma Clinic",
instructions="Confirm tomorrow 10am appointment and ask how many people are coming.",
return_fields=[
{"name": "booked", "description": "Did they confirm the appointment?", "type": "boolean"},
{"name": "party_size", "description": "Number of people coming", "type": "number"},
],
)Response 200
{
"call_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued"
}Errors
| Status | Code | Meaning |
|---|---|---|
400 | invalid_request | Body validation failed, or duplicate return_fields names |
401 | Missing authentication | |
403 | task_calls_disabled | features.task_calls_enabled is not true for this agent |
403 | Publishable keys cannot place task calls | |
404 | agent_not_found | Agent does not exist in the caller's workspace |
409 | agent_not_published | Agent has no published snapshot |
Caller Memory
An agent with features.caller_memory_enabled: true keeps one short note per caller. After each completed call, post-call analysis rewrites the note (at most 800 characters) from what the caller said, and the gateway gives it to that agent on the caller's next call. Memory belongs to one agent: a second agent in the same workspace does not see it. Turn it on with Update Agent:
{ "features": { "caller_memory_enabled": true } }The agent recognises a caller by:
| Call | Caller is remembered by |
|---|---|
| Phone call | The caller's number |
| Share link, signed in | The verified phone on the visitor's Rymi login |
| Share link, not signed in | A random id the share page keeps in that browser. Rymi stores only a hash of it. Another browser, a private window or cleared site data starts fresh |
A caller who says "forget me" during a call has the note deleted. Studio test-panel calls are not remembered.
List remembered callers
Returns up to 200 callers, most recent call first.
curl https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000/memory \
-H "Authorization: Bearer YOUR_API_KEY"{
"memories": [
{
"id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
"caller": { "kind": "phone", "label": "+919812345678" },
"note": "Name: Ravi\nWorks night shifts at a call centre\nLikes old Kishore Kumar songs",
"call_count": 3,
"last_call_at": "2026-11-10T16:50:51.575Z",
"created_at": "2026-11-08T14:02:10.110Z"
}
]
}| Field | Description |
|---|---|
caller.kind | phone or browser |
caller.label | The number, or Browser and the first 6 characters of the hash |
note | What the agent will be told on the next call, one fact per line |
call_count | Completed calls recorded for this caller |
Forget one caller
Returns { "deleted": 1 }. The caller's next call starts as a first call.
Forget every caller
Returns { "deleted": <count> }. Turning caller_memory_enabled off stops reading and writing notes but keeps the stored ones; delete them with this route.
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Called with a publishable key, or your workspace role cannot manage agents |
404 | Agent not found in this workspace, or memoryId not found on this agent |
Delete Agent
WARNING
Deleting an agent cascade-deletes all associated number mappings. Active calls using this agent are not affected.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | uuid | Agent ID |
Example Request
curl -X DELETE https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer YOUR_API_KEY"const result = await rymi.agents.delete("550e8400-e29b-41d4-a716-446655440000");result = rymi.agents.delete("550e8400-e29b-41d4-a716-446655440000")Response 200
{
"status": "deleted",
"id": "550e8400-e29b-41d4-a716-446655440000"
}Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
404 | Agent not found for this tenant |
Generate Agent Draft
Describe the agent you want in plain English. Rymi returns a draft persona/playbook bundle plus a compiled prompt preview. You can also send the current draft and opt into clarifying questions before generation.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
prompt | string | Yes | - | Natural-language description of the agent you want |
mode | string | No | create | create for a new agent or edit to refine an existing config |
allow_clarifying_questions | boolean | No | false | When true, Rymi may return questions instead of generating a weak draft |
options.voice | string | No | - | Preferred voice ID or name |
options.llm_provider | string | No | - | Preferred LLM provider hint |
options.llm_model | string | No | - | Preferred model hint |
current_config | object | No | - | Current agent config snapshot for edit mode |
Example: Create Mode
curl -X POST https://api.rymi.live/v1/agents/generate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A friendly female sales agent who speaks Hindi with a Delhi accent and can sell insurance plans",
"options": {
"llm_provider": "gemini",
"voice": "Aoede"
},
"mode": "create",
"allow_clarifying_questions": false
}'Response 200: Generated
{
"generated": true,
"draft": {
"name": "Delhi Insurance Sales Agent",
"voice": "Aoede",
"llm_provider": "gemini",
"persona": {
"role": "Insurance sales specialist",
"tone": "friendly",
"audience": "Hindi-speaking consumers in North India"
},
"playbook": {
"opener": "Namaste! Main aapki insurance needs mein madad kar sakti hoon.",
"cta": "Book a follow-up with our advisor"
}
},
"compiled_prompt_preview": "You are a friendly female sales agent..."
}Response 200: Clarifying Questions
If allow_clarifying_questions is true and the brief is too thin:
{
"generated": false,
"clarifying_questions": [
"What primary action should the agent drive toward?",
"How should we know the call was successful?"
],
"quality_gates": {
"blockers": ["Primary CTA is missing."],
"warnings": ["Audience context is thin."]
}
}Example: Edit Mode
curl -X POST https://api.rymi.live/v1/agents/generate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Make the tone more formal and add an escalation rule for angry customers",
"mode": "edit",
"current_config": {
"name": "Support Agent",
"persona": { "role": "Customer support", "tone": "friendly" },
"playbook": { "opener": "Hi! How can I help?" }
}
}'Errors
| Status | Meaning |
|---|---|
400 | Missing prompt or invalid mode |
401 | Missing or invalid API key |
500 | Generation failed |
503 | Generation provider is not configured |
Configuration Reference
The canonical agent payload shape. Every field is optional on PUT /v1/agents/:id (partial updates). On POST /v1/agents only name is required.
Top-level Fields
| Field | Type | Default | Description |
|---|---|---|---|
name | string | required | Display name for the agent |
voice | string | "Aoede" | Voice ID (use GET /v1/agents/llm-options for available voices) |
language | string | "en-US" | BCP-47 language code |
agent_kind | string | "custom" | custom or managed. See Agent Kind |
managed_sku_id | string | null | null | SKU ID for managed agents (GET /v1/managed-skus); null for custom |
llm_provider | string | "gemini" | Conversation LLM: gemini, openai, anthropic, sarvam, groq, xai (realtime), ultravox (realtime) |
llm_model | string | "gemini-2.5-flash" | Model ID for the conversation LLM |
stt_provider | string | - | Speech-to-text provider override |
stt_model | string | - | STT model override |
tts_provider | string | - | Text-to-speech provider override |
tts_model | string | - | TTS model override |
supported_languages | string[] | [language] | All BCP-47 locales this agent may run |
llm_fallback_provider / llm_fallback_model | string | null | - | Secondary LLM provider/model; null clears |
stt_fallback_provider / stt_fallback_model | string | null | - | Secondary STT provider/model; null clears |
tts_fallback_provider / tts_fallback_model | string | null | - | Secondary TTS provider/model; null clears |
custom_llm_url / custom_voice_url / custom_transcriber_url | string | null | - | Self-hosted endpoints (https:///wss://), Enterprise; null clears |
custom_voice_mode | string | rymi | Wire format for custom_voice_url: rymi or openai-compat |
provider_config is server-derived (recomputed from the resolved stack + supported languages on every write) and is not accepted as an input field.
persona Object
Who the agent is, how it sounds, and what it knows.
| Field | Type | Description |
|---|---|---|
name | string | The name the agent speaks and introduces itself with, also shown on share and tester pages. Defaults to the agent's name (its Studio label) |
role | string | Job title (e.g. "Sales Specialist") |
audienceDescription | string | Who the agent talks to |
toneOverride | string | Speaking style (e.g. "warm and concise") |
companyName | string | Company name injected into the system prompt |
companyWebsite | string | Company website URL |
companyDescription | string | What the company does |
knowledgeBase | string[] | URLs or text passages the agent references |
successCriteria | string[] | What a successful call looks like |
voiceConfig.bargeInEnabled | boolean | Whether the caller can interrupt mid-sentence |
callerPersonas | object[] | Caller type variants: { type, approach } |
playbook Object
Conversation flow, objections, scripts, and call-to-action.
| Field | Type | Description |
|---|---|---|
opener | string | First thing the agent says |
qualificationFlow | object[] | Questions and what to listen for: { question, listensFor } |
requiredSlots | object[] | Data to collect: { name, description, required } |
objectionHandlers | object[] | How to handle pushback: { trigger, response } |
scripts | object[] | Canned responses for specific situations: { title, when, content } |
closingCTA | string | Primary call-to-action at end of call |
fallbackCTA | string | Fallback if primary CTA fails |
escalationRule | string | When/how to escalate to a human |
advanced Object
Runtime, speech, and safety configuration.
| Field | Type | Default | Description |
|---|---|---|---|
maxCallDuration | number | 600 | Max call length in seconds. Range 30 to 7200, enforced on POST /v1/agents/apply-changes but not on POST/PATCH /v1/agents |
maxTurnLength | number | 60 | Max agent speaking time per turn (seconds) |
silencePromptDelay | number | 8 | Seconds of silence before nudging the caller |
postSilenceHangup | number | 15 | Seconds of silence before hanging up |
replyDelay | number | 0 | Milliseconds to pause before responding |
startSpeakingPhrasing | string | "agent_greets" | agent_greets or wait_for_user |
startSpeakingThreshold | number | - | VAD sensitivity for when agent starts speaking |
stopSpeakingThreshold | number | - | VAD sensitivity for when caller stops speaking |
resumeAfterInterruption | boolean | true | Resume interrupted sentence after caller stops |
smartEndpointing | boolean | true | AI-powered end-of-turn detection |
waitAfterSentence | number | - | ms to wait after a sentence ends |
waitAfterNoPunctuation | number | - | ms to wait when no sentence-ending punctuation |
waitAfterNumbers | number | - | ms to wait after numbers (they often continue) |
stt_confidence_threshold | number | - | Minimum confidence to accept a transcription |
stt_numeral_formatting | boolean | true | Format numbers as numerals in transcript |
stt_profanity_filter | boolean | false | Filter profanity from transcript |
stt_keywords | string | - | Comma-separated keywords to boost STT accuracy |
offLimitsTopics | string | - | Topics the agent must never discuss |
prohibitedClaims | string | - | Claims the agent must never make |
prompt_mode | string | "builder" | builder compiles the prompt from persona and playbook; raw uses system_prompt word for word (the playbook.opener still opens the call) |
pronunciations | object[] | - | Up to 100 { word, say_as, ipa? } entries. See Pronunciations |
background_sound | string | "off" | "off", "office", or "custom". Mixes a continuous loop under the agent's voice. The loop ducks by 8 dB while the agent speaks |
background_sound_volume | number | 0.15 | Base gain for the loop, from 0.00 to 0.40 |
background_sound_url | string | "" | Public https:// URL of a .wav or .mp3, 3 to 120 seconds, up to 15 MB, at most 512 characters. Used when background_sound is "custom" |
voice_focus | string | "off" | "off" or "standard". Inbound RNNoise noise suppression before speech recognition. It reduces steady noise. It does not remove other people talking |
features Object
| Field | Type | Default | Description |
|---|---|---|---|
recording_enabled | boolean | false | Record both sides of each call |
transcription_enabled | boolean | true | Transcribe and store each call |
require_consent | boolean | true | Announce recording at call start. On create, when you omit this field, a saved workspace notice of on writes require_consent: true; off writes false. Before any settings are saved, the default (true) stands. A value you send wins. Existing agents stay as they are |
post_call Object
| Field | Type | Default | Description |
|---|---|---|---|
summary.enabled | boolean | true | Generate a call summary |
summary.prompt | string | - | Custom summary instructions |
structured_extraction.json_schema | object | - | JSON Schema for data extraction |
structured_extraction.prompt | string | - | Custom extraction instructions (auto-generated if omitted) |
evaluation.rubric | string | - | Numbered scoring criteria |
model.provider | string | - | gemini or openai for post-call LLM |
model.model | string | - | Model ID for post-call LLM |
Validate Publish
POST /v1/agents/validate-publishCheck whether an agent is ready to go live. Returns a validation report without persisting any changes.
Body
| Field | Type | Description |
|---|---|---|
agent_id | uuid | Optional. Merge validation with a persisted agent's config |
name | string | Agent name to validate |
voice | string | Voice ID to validate |
persona | object | Persona config |
playbook | object | Playbook config |
Example
curl -X POST https://api.rymi.live/v1/agents/validate-publish \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"agent_id": "550e8400-e29b-41d4-a716-446655440000"}'Pending Publish
On a phone line from Rymi, Rymi reviews an agent edit before it goes live. This route returns the latest held edit. MCP: get_pending_publish.
curl https://api.rymi.live/v1/agents/AGENT_ID/pending-publish \
-H "Authorization: Bearer YOUR_API_KEY"const { pending_publish } = await rymi.agents.pendingPublish('AGENT_ID');result = rymi.agents.pending_publish("AGENT_ID")Response 200
{
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"pending_publish": {
"id": "6f1e2d3c-4b5a-4968-8776-655443322110",
"status": "pending",
"summary": { "changed": ["system_prompt"] },
"review_note": null,
"reviewed_at": null,
"created_at": "2026-11-13T09:30:00Z"
}
}pending_publish is null when nothing was ever held. status is pending, approved, rejected (see review_note) or stale (a newer edit replaced it).
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Publishable key, or the agent is not yours |
404 | Agent not found |
Apply Changes
POST /v1/agents/apply-changesValidates and resolves a flat key/value change-set against the AgentConfig field registry. Enforces field types, edit-mode blocklist, and implies rules. Does not persist. Follow up with PUT /v1/agents/:id.
Body
| Field | Type | Description |
|---|---|---|
currentConfig | object | The agent's current flat config |
changes | array | [{key, value}] field changes to apply |
mode | string | "create" or "edit" |
lenient | boolean | Skip unknown-field hard-fail (not recommended) |
Example
curl -X POST https://api.rymi.live/v1/agents/apply-changes \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"currentConfig": {"name": "Support", "voice": "Aoede"},
"changes": [{"key": "voice", "value": "Charon"}],
"mode": "edit"
}'Response
{
"valid": true,
"config": { "name": "Support", "voice": "Charon" },
"applied": [{ "key": "voice", "value": "Charon" }]
}Preview Model Stack
POST /v1/agents/stack-previewResolves the model stack (STT/LLM/TTS) for a set of supported languages, along with any blockers and warnings, without saving. Call this before create or update to confirm a multi-language setup resolves to a valid stack.
Body
| Field | Type | Required | Description |
|---|---|---|---|
supported_languages | string[] | Yes | Non-empty list of BCP-47 locales to resolve a stack for |
language | string | null | No | Primary locale (defaults to the first supported language) |
current_provider_config | object | null | No | Existing provider config to diff against |
Example
curl -X POST https://api.rymi.live/v1/agents/stack-preview \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"supported_languages": ["hi-IN", "en-US"]
}'Response 200
{
"language": "hi-IN",
"supported_languages": ["hi-IN", "en-US"],
"provider_config": { "mode": "pipeline", "stt": { }, "llm": { }, "tts": { } },
"blockers": [],
"warnings": []
}provider_config is the resolved flat stack. If a language can't be served, it appears in blockers. Non-fatal notes (e.g. a fallback substitution) appear in warnings.
Enrich Company
POST /v1/agents/enrich-companyGenerates a company description from a website URL, grounded in Google Search results. Drop the result into an agent's persona.
Body
| Field | Type | Description |
|---|---|---|
companyName | string | Company name |
websiteUrl | string | Company website URL |
Example
curl -X POST https://api.rymi.live/v1/agents/enrich-company \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"companyName": "Acme Corp", "websiteUrl": "https://acme.example.com"}'Response
This endpoint always returns 200. Use the enriched boolean to discriminate success from failure rather than the HTTP status. On success:
{
"enriched": true,
"companyDescription": "Acme Corp is a leading provider of...",
"knowledgeBase": []
}When the lookup cannot be completed, enriched is false and an error string explains why (the call still returns 200):
{
"enriched": false,
"error": "Could not look up company details. You can describe your business manually."
}Check a Background Sound URL
POST /v1/agents/background-sound/validateChecks a public link before you save it as an agent's custom background sound (advanced.background_sound_url). It fetches the first 256 KB of the file and reads its length. The voice gateway applies the same limits when a call starts, so a link that passes here can still be refused on a call (for example, if the host changes the file).
Body
| Field | Type | Description |
|---|---|---|
url | string | https:// link to a .wav or .mp3 file, up to 512 characters |
Example
curl -X POST https://api.rymi.live/v1/agents/background-sound/validate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://cdn.example.com/office-loop.wav"}'Response 200
{
"ok": true,
"duration_s": 32.4,
"sample_rate": 24000,
"channels": 1,
"duration_estimated": false
}duration_estimated is true for MP3 files, where the length is worked out from bitrate and file size and can differ for variable-bitrate files.
Response 400
{ "ok": false, "error": "That file is larger than 15 MB." }The error string says what to fix: not a public https:// link to a .wav or .mp3, a private or unknown host, a redirect, a non-audio file, more than 15 MB, or a length outside 3 to 120 seconds.
Response 429
Each workspace can run 10 checks a minute.
{ "ok": false, "error": "Too many checks. Try again in a minute." }Additional Endpoints
These endpoints back the Studio agent builder and SDK/MCP flows. All are prefixed with /v1 and authenticated like the rest of the API.
Catalog & capabilities
| Method | Path | Description |
|---|---|---|
GET | /v1/managed-skus | List managed SKUs with their published price_per_min and locked stacks |
GET | /v1/agents/voices | Voice catalog for agent configuration |
GET | /v1/agents/:id/tool-capabilities | The tool capabilities resolved for a specific agent |
Lifecycle
| Method | Path | Description |
|---|---|---|
POST | /v1/agents/:id/publish | Validate the persisted draft and freeze it. Body { environment?: "production" | "staging", label?: string }. With agent versioning on, this appends an immutable version and points that environment at it. A draft save does not move production. snapshot_id stays the harness content hash. version_id is the UUID live calls record. |
GET | /v1/agents/:id/versions | List immutable versions and which of production or staging currently points at each. 404 when versioning is off. |
POST | /v1/agents/:id/environments/:environment | Point production or staging at an existing { version_id }. Does not copy the version. Production also refreshes published_snapshot. |
POST | /v1/agents/:id/opt-out-to-custom | Convert a managed agent to a custom agent, unlocking the stack for manual configuration |
POST | /v1/agents/:id/apply-managed-sku | Swap an agent onto a managed SKU stack in place. Body { managed_sku_id, language } |
AI-assisted drafting
| Method | Path | Description |
|---|---|---|
POST | /v1/agents/draft | Create an agent from the full create body (name required; structured config or system_prompt), skipping publish gates. Not prompt-driven, for prompt-driven creation use /v1/agents/generate |
POST | /v1/agents/draft-field | Generate or refine a single agent field |
POST | /v1/agents/compile-prompt | Compile a preview of the agent's system prompt from its structured config |
POST | /v1/agents/chat/answer | Answer a builder-assistant question about agent configuration |

