Skip to content

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 ​

GET/v1/agents

Returns a paginated list of agents for the authenticated tenant.

Query Parameters ​

ParameterTypeDefaultDescription
limitinteger50Max records to return (max 500)
offsetinteger0Records to skip

Example Request ​

bash
curl "https://api.rymi.live/v1/agents?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
ts
const { agents } = await rymi.agents.list({ limit: 10, offset: 0 });
python
result = rymi.agents.list(limit=10, offset=0)

Response 200 ​

json
{
  "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.

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Priya",
  "language": "hi-IN",
  "published": true,
  "retiring": false,
  "persona": { "name": "Priya", "role": "Front desk" },
  "advanced": { "transferNumber": "+919876543210" }
}
FieldTypeDescription
iduuidAgent id
namestringAgent name
languagestring or nullAgent language
publishedbooleanTrue when published_snapshot_id is set
retiringbooleanPresent on this list. True when a model, voice, or SKU the agent uses is retiring
persona.namestring or nullSpoken name
persona.rolestring or nullRole
advanced.transferNumberstring or nullNumber 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 ​

StatusMeaning
401Missing or invalid API key
403Publishable keys cannot list agents

Model and Voice Catalog ​

GET/v1/agents/llm-options

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 ​

bash
curl https://api.rymi.live/v1/agents/llm-options \
  -H "Authorization: Bearer YOUR_API_KEY"
ts
const { models, voices } = await rymi.agents.llmOptions();
python
result = rymi.agents.llm_options()

Response 200 ​

json
{
  "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.

KindAPI ValueStackBilling
Custom (default)customYou 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
ManagedmanagedA 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-US or hi-IN for language.
  • 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 ​

POST/v1/agents

Request Body ​

FieldTypeRequiredDefaultDescription
namestringYes-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_promptstringNo-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
voicestringNoAoedeTTS voice ID from GET /v1/agents/llm-options
languagestringNoen-USPrimary call language locale (for example, en-US, hi-IN)
supported_languagesstring[]No[language]Locales this agent may run. The API resolves a valid stack for each selected language
agent_kindstringNocustomcustom (you pick the stack) or managed (Rymi Managed SKU). See Agent Kind
managed_sku_idstring | nullNonullRequired when agent_kind is managed: the SKU ID from GET /v1/managed-skus. Must be null for custom agents
llm_providerstringNoStack defaultgemini, openai, anthropic, sarvam, groq, xai (realtime) or ultravox (realtime)
llm_modelstringNoStack defaultLLM model ID (a realtime model bundles STT/TTS)
stt_providerstringNoStack defaultSpeech-to-text provider
stt_modelstringNoStack defaultSTT model ID
tts_providerstringNoStack defaultText-to-speech provider
tts_modelstringNoStack defaultTTS model ID
llm_fallback_providerstring | nullNo-Secondary LLM provider used if the primary fails. null clears it
llm_fallback_modelstring | nullNo-Secondary LLM model. null clears it
stt_fallback_providerstring | nullNo-Secondary STT provider. null clears it
stt_fallback_modelstring | nullNo-Secondary STT model. null clears it
tts_fallback_providerstring | nullNo-Secondary TTS provider. null clears it
tts_fallback_modelstring | nullNo-Secondary TTS model. null clears it
custom_llm_urlstring | nullNo-Self-hosted LLM endpoint (https:// or wss://). Enterprise only; null clears
custom_voice_urlstring | nullNo-Self-hosted TTS endpoint. Enterprise only; null clears
custom_voice_modestringNorymiWire format for custom_voice_url: rymi or openai-compat
custom_transcriber_urlstring | nullNo-Self-hosted STT endpoint. Enterprise only; null clears
personaPersona objectNo-Structured role, tone, audience, and voice config
playbookPlaybook objectNo-Opener, qualification flow, scripts, CTA, and escalation rules
advancedadvanced objectNo-Runtime tuning (endpointing, turn timing)
featuresFeatures objectNo-Feature flags (recording, transcription)
post_callPost-call objectNo-Default post-call intelligence config
toolsobject[]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_configobjectNo-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 ​

FieldTypeDescription
rolestringAgent's role description (e.g., "Insurance sales specialist")
toneOverridestringSpeaking style (e.g., "warm and concise")
audienceDescriptionstringWho the agent talks to
voiceConfigobjectVoice settings: { "voiceId": "Aoede", "language": "en-US", "bargeInEnabled": true }
successCriteriastring[]What a successful call looks like
callerPersonasobject[]Caller type variants: { type, approach }

The full persona shape (company fields, knowledge base) is in the Configuration Reference below.

Playbook Object ​

FieldTypeDescription
openerstringOpening message the agent uses to start the conversation
qualificationFlowobject[]Questions and what to listen for: { question, listensFor }
requiredSlotsobject[]Data to collect: { name, description, required }
objectionHandlersobject[]How to handle pushback: { trigger, response }
scriptsobject[]Canned responses for specific situations: { title, when, content }
closingCTAstringPrimary call-to-action the agent drives toward
fallbackCTAstringFallback if the primary CTA fails
escalationRulestringWhen/how to escalate to a human
endCallMessagestringClosing 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 ​

FieldTypeDefaultDescription
recording_enabledbooleanfalseRecord both sides of each call
transcription_enabledbooleantrueTranscribe and store each call
require_consentbooleantrueAnnounce 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 ​

FieldTypeDefaultDescription
summary.enabledbooleantrueGenerate a summary after each call
summary.promptstring-Custom instructions for the summary LLM (e.g. "highlight objections")
structured_extraction.json_schemaobject-JSON Schema defining the structured data to extract from the transcript
structured_extraction.promptstring-Custom instructions for the extraction LLM (auto-generated from schema if omitted)
evaluation.rubricstring-Numbered list of quality criteria for call scoring
model.providerstring-LLM provider for post-call analysis: gemini or openai. Defaults to platform setting
model.modelstring-Specific model ID (e.g. gemini-2.5-flash, gpt-4o-mini). Defaults to platform setting

Example: Minimal ​

bash
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 ​

bash
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 ​

json
{
  "status": "created",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Errors ​

StatusMeaning
400Validation error (missing name, invalid agent_kind/managed_sku_id, etc.)
401Missing or invalid API key
402Insufficient credits
403sku_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 ​

GET/v1/agents/:id

Returns the full agent configuration including the compiled prompt.

Path Parameters ​

ParameterTypeDescription
iduuidAgent ID

Example Request ​

bash
curl https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"
ts
const agent = await rymi.agents.retrieve("550e8400-e29b-41d4-a716-446655440000");
python
agent = rymi.agents.retrieve("550e8400-e29b-41d4-a716-446655440000")

Response 200 ​

json
{
  "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 ​

FieldTypeDescription
managed_sku_upgradeobject | nullObject 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 ​

StatusMeaning
401Missing or invalid API key
403Publishable keys can only read the agent the key is bound to, or the agent belongs to another workspace
404Agent not found for this tenant

Update Agent ​

PUT/v1/agents/:id
PATCH/v1/agents/:id

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 ​

ParameterTypeDescription
iduuidAgent ID

Request Body ​

Accepts the same fields as Create Agent. All fields are optional.

Example Request ​

bash
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" }
          }
        }
      }
    }
  }'
ts
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" },
        },
      },
    },
  },
});
python
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 ​

json
{
  "status": "updated"
}

Errors ​

StatusMeaning
400Validation error
401Missing or invalid API key
403Client role sent anything other than { "advanced": { "transferNumber": "+919876543210" } }. Body: { "error": "Your role can change only the transfer number", "code": "field_not_permitted" }
404Agent not found for this tenant

Clone Agent ​

POST/v1/agents/:id/clone

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 ​

ParameterTypeDescription
iduuidAgent ID to clone

Example Request ​

bash
curl -X POST https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000/clone \
  -H "Authorization: Bearer YOUR_API_KEY"
ts
const clone = await rymi.agents.clone("550e8400-e29b-41d4-a716-446655440000");
python
clone = rymi.agents.clone("550e8400-e29b-41d4-a716-446655440000")

Response 201 ​

json
{
  "status": "created",
  "id": "7f3e9a12-b4c1-41f2-a890-556677889900"
}

Errors ​

StatusMeaning
401Missing or invalid API key
403Agent belongs to a different tenant
404Agent not found

List Agent Calls ​

GET/v1/agents/:id/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 ​

ParameterTypeDescription
iduuidAgent ID

Query Parameters ​

ParameterTypeDefaultDescription
limitinteger50Max records to return (max 200)
offsetinteger0Records to skip
statusstringAll statusesFilter by call status: queued, ringing, in_progress, completed, or failed

Example Request ​

bash
curl "https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000/calls?limit=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"
ts
const { calls } = await rymi.agents.listCalls("550e8400-e29b-41d4-a716-446655440000", {
  limit: 20,
  status: "completed",
});
python
result = rymi.agents.list_calls(
    "550e8400-e29b-41d4-a716-446655440000",
    limit=20,
    status="completed",
)

Response 200 ​

json
{
  "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 ​

StatusMeaning
401Missing or invalid API key
403Publishable keys cannot access call history, or agent does not belong to you
404Agent not found

Place Task Call ​

POST/v1/agents/:id/task-calls

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 ​

ParameterTypeDescription
iduuidAgent ID to place the call through

Request Body ​

FieldTypeRequiredDescription
tostringYesDestination phone number in strict E.164 format (for example +919812345678)
on_behalf_ofstringYesBusiness or person the call is on behalf of (1 to 120 characters)
instructionsstringYesWhat the call must do in plain words (1 to 4000 characters)
return_fieldsarrayYes1 to 20 fields to extract from the call transcript. Names must be unique snake_case
return_fields[].namestringYesField identifier (^[a-z][a-z0-9_]{0,39}$)
return_fields[].descriptionstringYesGuidance for the extractor (1 to 300 characters)
return_fields[].typestringNoData type: string (default), number, or boolean
opening_linestringNoCustom first line spoken by the agent (1 to 300 characters). When omitted, uses the agent's default opener or disclosure line
from_numberstringNoCaller ID registered to the workspace. When omitted, uses the agent's attached number

Example Request ​

bash
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" }
    ]
  }'
ts
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" },
  ],
});
python
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 ​

json
{
  "call_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Errors ​

StatusCodeMeaning
400invalid_requestBody validation failed, or duplicate return_fields names
401Missing authentication
403task_calls_disabledfeatures.task_calls_enabled is not true for this agent
403Publishable keys cannot place task calls
404agent_not_foundAgent does not exist in the caller's workspace
409agent_not_publishedAgent 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:

json
{ "features": { "caller_memory_enabled": true } }

The agent recognises a caller by:

CallCaller is remembered by
Phone callThe caller's number
Share link, signed inThe verified phone on the visitor's Rymi login
Share link, not signed inA 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 ​

GET/v1/agents/:id/memory

Returns up to 200 callers, most recent call first.

bash
curl https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000/memory \
  -H "Authorization: Bearer YOUR_API_KEY"
json
{
  "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"
    }
  ]
}
FieldDescription
caller.kindphone or browser
caller.labelThe number, or Browser and the first 6 characters of the hash
noteWhat the agent will be told on the next call, one fact per line
call_countCompleted calls recorded for this caller

Forget one caller ​

DELETE/v1/agents/:id/memory/:memoryId

Returns { "deleted": 1 }. The caller's next call starts as a first call.

Forget every caller ​

DELETE/v1/agents/:id/memory

Returns { "deleted": <count> }. Turning caller_memory_enabled off stops reading and writing notes but keeps the stored ones; delete them with this route.

Errors ​

StatusMeaning
401Missing or invalid API key
403Called with a publishable key, or your workspace role cannot manage agents
404Agent not found in this workspace, or memoryId not found on this agent

Delete Agent ​

DELETE/v1/agents/:id

WARNING

Deleting an agent cascade-deletes all associated number mappings. Active calls using this agent are not affected.

Path Parameters ​

ParameterTypeDescription
iduuidAgent ID

Example Request ​

bash
curl -X DELETE https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"
ts
const result = await rymi.agents.delete("550e8400-e29b-41d4-a716-446655440000");
python
result = rymi.agents.delete("550e8400-e29b-41d4-a716-446655440000")

Response 200 ​

json
{
  "status": "deleted",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Errors ​

StatusMeaning
401Missing or invalid API key
404Agent not found for this tenant

Generate Agent Draft ​

POST/v1/agents/generate

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 ​

FieldTypeRequiredDefaultDescription
promptstringYes-Natural-language description of the agent you want
modestringNocreatecreate for a new agent or edit to refine an existing config
allow_clarifying_questionsbooleanNofalseWhen true, Rymi may return questions instead of generating a weak draft
options.voicestringNo-Preferred voice ID or name
options.llm_providerstringNo-Preferred LLM provider hint
options.llm_modelstringNo-Preferred model hint
current_configobjectNo-Current agent config snapshot for edit mode

Example: Create Mode ​

bash
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 ​

json
{
  "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:

json
{
  "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 ​

bash
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 ​

StatusMeaning
400Missing prompt or invalid mode
401Missing or invalid API key
500Generation failed
503Generation 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 ​

FieldTypeDefaultDescription
namestringrequiredDisplay name for the agent
voicestring"Aoede"Voice ID (use GET /v1/agents/llm-options for available voices)
languagestring"en-US"BCP-47 language code
agent_kindstring"custom"custom or managed. See Agent Kind
managed_sku_idstring | nullnullSKU ID for managed agents (GET /v1/managed-skus); null for custom
llm_providerstring"gemini"Conversation LLM: gemini, openai, anthropic, sarvam, groq, xai (realtime), ultravox (realtime)
llm_modelstring"gemini-2.5-flash"Model ID for the conversation LLM
stt_providerstring-Speech-to-text provider override
stt_modelstring-STT model override
tts_providerstring-Text-to-speech provider override
tts_modelstring-TTS model override
supported_languagesstring[][language]All BCP-47 locales this agent may run
llm_fallback_provider / llm_fallback_modelstring | null-Secondary LLM provider/model; null clears
stt_fallback_provider / stt_fallback_modelstring | null-Secondary STT provider/model; null clears
tts_fallback_provider / tts_fallback_modelstring | null-Secondary TTS provider/model; null clears
custom_llm_url / custom_voice_url / custom_transcriber_urlstring | null-Self-hosted endpoints (https:///wss://), Enterprise; null clears
custom_voice_modestringrymiWire 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.

FieldTypeDescription
namestringThe name the agent speaks and introduces itself with, also shown on share and tester pages. Defaults to the agent's name (its Studio label)
rolestringJob title (e.g. "Sales Specialist")
audienceDescriptionstringWho the agent talks to
toneOverridestringSpeaking style (e.g. "warm and concise")
companyNamestringCompany name injected into the system prompt
companyWebsitestringCompany website URL
companyDescriptionstringWhat the company does
knowledgeBasestring[]URLs or text passages the agent references
successCriteriastring[]What a successful call looks like
voiceConfig.bargeInEnabledbooleanWhether the caller can interrupt mid-sentence
callerPersonasobject[]Caller type variants: { type, approach }

playbook Object ​

Conversation flow, objections, scripts, and call-to-action.

FieldTypeDescription
openerstringFirst thing the agent says
qualificationFlowobject[]Questions and what to listen for: { question, listensFor }
requiredSlotsobject[]Data to collect: { name, description, required }
objectionHandlersobject[]How to handle pushback: { trigger, response }
scriptsobject[]Canned responses for specific situations: { title, when, content }
closingCTAstringPrimary call-to-action at end of call
fallbackCTAstringFallback if primary CTA fails
escalationRulestringWhen/how to escalate to a human

advanced Object ​

Runtime, speech, and safety configuration.

FieldTypeDefaultDescription
maxCallDurationnumber600Max call length in seconds. Range 30 to 7200, enforced on POST /v1/agents/apply-changes but not on POST/PATCH /v1/agents
maxTurnLengthnumber60Max agent speaking time per turn (seconds)
silencePromptDelaynumber8Seconds of silence before nudging the caller
postSilenceHangupnumber15Seconds of silence before hanging up
replyDelaynumber0Milliseconds to pause before responding
startSpeakingPhrasingstring"agent_greets"agent_greets or wait_for_user
startSpeakingThresholdnumber-VAD sensitivity for when agent starts speaking
stopSpeakingThresholdnumber-VAD sensitivity for when caller stops speaking
resumeAfterInterruptionbooleantrueResume interrupted sentence after caller stops
smartEndpointingbooleantrueAI-powered end-of-turn detection
waitAfterSentencenumber-ms to wait after a sentence ends
waitAfterNoPunctuationnumber-ms to wait when no sentence-ending punctuation
waitAfterNumbersnumber-ms to wait after numbers (they often continue)
stt_confidence_thresholdnumber-Minimum confidence to accept a transcription
stt_numeral_formattingbooleantrueFormat numbers as numerals in transcript
stt_profanity_filterbooleanfalseFilter profanity from transcript
stt_keywordsstring-Comma-separated keywords to boost STT accuracy
offLimitsTopicsstring-Topics the agent must never discuss
prohibitedClaimsstring-Claims the agent must never make
prompt_modestring"builder"builder compiles the prompt from persona and playbook; raw uses system_prompt word for word (the playbook.opener still opens the call)
pronunciationsobject[]-Up to 100 { word, say_as, ipa? } entries. See Pronunciations
background_soundstring"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_volumenumber0.15Base gain for the loop, from 0.00 to 0.40
background_sound_urlstring""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_focusstring"off""off" or "standard". Inbound RNNoise noise suppression before speech recognition. It reduces steady noise. It does not remove other people talking

features Object ​

FieldTypeDefaultDescription
recording_enabledbooleanfalseRecord both sides of each call
transcription_enabledbooleantrueTranscribe and store each call
require_consentbooleantrueAnnounce 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 ​

FieldTypeDefaultDescription
summary.enabledbooleantrueGenerate a call summary
summary.promptstring-Custom summary instructions
structured_extraction.json_schemaobject-JSON Schema for data extraction
structured_extraction.promptstring-Custom extraction instructions (auto-generated if omitted)
evaluation.rubricstring-Numbered scoring criteria
model.providerstring-gemini or openai for post-call LLM
model.modelstring-Model ID for post-call LLM

Validate Publish ​

POST /v1/agents/validate-publish

Check whether an agent is ready to go live. Returns a validation report without persisting any changes.

Body

FieldTypeDescription
agent_iduuidOptional. Merge validation with a persisted agent's config
namestringAgent name to validate
voicestringVoice ID to validate
personaobjectPersona config
playbookobjectPlaybook config

Example

bash
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 ​

GET/v1/agents/:id/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.

bash
curl https://api.rymi.live/v1/agents/AGENT_ID/pending-publish \
  -H "Authorization: Bearer YOUR_API_KEY"
ts
const { pending_publish } = await rymi.agents.pendingPublish('AGENT_ID');
python
result = rymi.agents.pending_publish("AGENT_ID")

Response 200 ​

json
{
  "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 ​

StatusMeaning
401Missing or invalid API key
403Publishable key, or the agent is not yours
404Agent not found

Apply Changes ​

POST /v1/agents/apply-changes

Validates 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

FieldTypeDescription
currentConfigobjectThe agent's current flat config
changesarray[{key, value}] field changes to apply
modestring"create" or "edit"
lenientbooleanSkip unknown-field hard-fail (not recommended)

Example

bash
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

json
{
  "valid": true,
  "config": { "name": "Support", "voice": "Charon" },
  "applied": [{ "key": "voice", "value": "Charon" }]
}

Preview Model Stack ​

POST /v1/agents/stack-preview

Resolves 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

FieldTypeRequiredDescription
supported_languagesstring[]YesNon-empty list of BCP-47 locales to resolve a stack for
languagestring | nullNoPrimary locale (defaults to the first supported language)
current_provider_configobject | nullNoExisting provider config to diff against

Example

bash
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

json
{
  "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-company

Generates a company description from a website URL, grounded in Google Search results. Drop the result into an agent's persona.

Body

FieldTypeDescription
companyNamestringCompany name
websiteUrlstringCompany website URL

Example

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

json
{
  "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):

json
{
  "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/validate

Checks 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

FieldTypeDescription
urlstringhttps:// link to a .wav or .mp3 file, up to 512 characters

Example

bash
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

json
{
  "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

json
{ "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.

json
{ "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 ​

MethodPathDescription
GET/v1/managed-skusList managed SKUs with their published price_per_min and locked stacks
GET/v1/agents/voicesVoice catalog for agent configuration
GET/v1/agents/:id/tool-capabilitiesThe tool capabilities resolved for a specific agent

Lifecycle ​

MethodPathDescription
POST/v1/agents/:id/publishValidate 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/versionsList immutable versions and which of production or staging currently points at each. 404 when versioning is off.
POST/v1/agents/:id/environments/:environmentPoint 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-customConvert a managed agent to a custom agent, unlocking the stack for manual configuration
POST/v1/agents/:id/apply-managed-skuSwap an agent onto a managed SKU stack in place. Body { managed_sku_id, language }

AI-assisted drafting ​

MethodPathDescription
POST/v1/agents/draftCreate 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-fieldGenerate or refine a single agent field
POST/v1/agents/compile-promptCompile a preview of the agent's system prompt from its structured config
POST/v1/agents/chat/answerAnswer a builder-assistant question about agent configuration