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

http

GET /v1/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 `200`)
`offset`	integer	`0`	Records to skip

Example Request

bash

curl "https://api.rymi.live/v1/agents?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

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_role": "operator",
      "language": "en-US",
      "created_at": "2026-03-01T10:00:00Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 10
}

Errors

Status	Meaning
`401`	Missing or invalid API key

Model and Voice Catalog

http

GET /v1/agents/llm-options

Returns the tenant-visible model catalog and voice list available for agent configuration. Use this to populate dropdowns and pickers before creating or updating agents.

Example Request

bash

curl https://api.rymi.live/v1/agents/llm-options \
  -H "Authorization: Bearer YOUR_API_KEY"

Response `200`

json

{
  "models": [
    { "id": "gemini-2.5-flash", "provider_id": "google" },
    { "id": "gpt-4o-mini", "provider_id": "openai" }
  ],
  "voices": [
    { "id": "Aoede", "provider": "google", "name": "Aoede" },
    { "id": "21m00Tcm4TlvDq8ikWAM", "provider": "elevenlabs", "name": "Rachel" }
  ]
}

Agent Roles

Agents use an agent role to select their default STT, LLM, TTS, routing behavior, and fallback stack. Set it with agent_role on create or update.

The top role is executive across the UI, API, and routing rules.

Role	API Value	Best For	Default Behavior
Operator	`operator`	Simple call handling, FAQs, lead capture, reminders	Cost-efficient standard pipeline with fallback providers
Specialist	`specialist`	Sales, support, qualification, domain-specific workflows	Higher-accuracy STT, complexity-aware LLM routing, Google Gemini Pro TTS; ElevenLabs available as premium override
Executive	`executive`	Complex conversations, realtime behavior, high-value interactions	Realtime-capable routing with premium fallback stack

Rymi derives the provider route from the agent role, selected language, and supported provider capabilities. The derived route is stored internally so calls use the same behavior until the agent configuration changes.

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.
Rymi resolves the role-safe 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 agent role, selected languages, and supported provider capabilities. Public API clients do not need to manage provider routing tables.

Create Agent

http

POST /v1/agents

Request Body

Field	Type	Required	Default	Description
`name`	string	Yes	—	Human-readable agent name (max 100 characters)
`system_prompt`	string	No	—	Raw system prompt. If you omit `persona` and `playbook`, Rymi can extract structure from this prompt
`voice`	string	No	Role default	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 role-safe stack for each selected language
`agent_role`	string	No	`operator`	`operator`, `specialist`, `executive`, or `concierge`
`llm_provider`	string	No	Role default	`gemini`, `openai`, `anthropic`, or `sarvam`
`llm_model`	string	No	Role default	Model ID for the active agent role
`stt_provider`	string	No	Role default	Speech-to-text provider
`stt_model`	string	No	Role default	STT model ID
`tts_provider`	string	No	Role default	Text-to-speech provider
`tts_model`	string	No	Role 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
`provider_config`	object	No	—	Provider routing override. Use only when instructed by Rymi support

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

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

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",
    "agent_role": "specialist",
    "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

Status	Meaning
`400`	Validation error (missing `name`, invalid `agent_role`, etc.)
`401`	Missing or invalid API key
`402`	Insufficient credits

Get Agent

http

GET /v1/agents/:id

Returns the full agent configuration including the compiled prompt.

Path Parameters

Parameter	Type	Description
`id`	uuid	Agent ID

Example Request

bash

curl https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

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_role": "specialist",
  "features": {
    "recording_enabled": true,
    "transcription_enabled": true
  },
  "post_call": {
    "summary": { "enabled": true },
    "evaluation": { "rubric": null }
  },
  "updated_at": "2026-03-01T10:00:00Z"
}

Errors

Status	Meaning
`401`	Missing or invalid API key
`404`	Agent not found for this tenant

Update Agent

http

PUT /v1/agents/:id

Pass only the fields you want to change. Unspecified fields remain unchanged.

Path Parameters

Parameter	Type	Description
`id`	uuid	Agent 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...",
    "agent_role": "specialist",
    "post_call": {
      "summary": { "enabled": true },
      "structured_extraction": {
        "json_schema": {
          "type": "object",
          "properties": {
            "renewal_confirmed": { "type": "boolean" }
          }
        }
      }
    }
  }'

Response `200`

json

{
  "status": "updated"
}

Errors

Status	Meaning
`400`	Validation error
`401`	Missing or invalid API key
`404`	Agent not found for this tenant

Clone Agent

http

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

Parameter	Type	Description
`id`	uuid	Agent 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"

Response `201`

json

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

http

GET /v1/agents/:id/calls

Returns a paginated list of calls made with a specific agent. Useful for per-agent performance monitoring and debugging.

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

bash

curl "https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000/calls?limit=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

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

Delete Agent

http

DELETE /v1/agents/:id

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

bash

curl -X DELETE https://api.rymi.live/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response `200`

json

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

http

POST /v1/agents/generate

Describe your ideal agent in plain English and Rymi generates a draft persona/playbook bundle plus a compiled prompt preview. Studio clients 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

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

Status	Meaning
`400`	Missing `prompt` or invalid `mode`
`401`	Missing or invalid API key
`500`	Generation failed

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_role`	string	`"operator"`	One of `operator`, `specialist`, `executive`, `concierge`
`llm_provider`	string	`"gemini"`	Conversation LLM: `gemini`, `openai`, `anthropic`, `sarvam`
`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 role + 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
`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)
`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

`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

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

Check 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

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"}'

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

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

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 per-language model stack (STT/LLM/TTS), blockers, warnings, model-change diffs, and any required role upgrades for a set of supported languages — without saving. Call this before create/update to confirm a multi-language setup is valid.

INFO

This endpoint covers the standard operator, specialist, and executive roles. The concierge (realtime) role is not supported here.

Body

Field	Type	Required	Description
`supported_languages`	string[]	Yes	Non-empty list of BCP-47 locales to resolve a stack for
`agent_role` (or `role`)	string	No	`operator` (default), `specialist`, or `executive`
`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

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"],
    "agent_role": "operator"
  }'

Response 200

json

{
  "language": "hi-IN",
  "supported_languages": ["hi-IN", "en-US"],
  "provider_config": { "active_role": "operator", "tiers": { } },
  "stacks": { "operator:hi-IN": { }, "operator:en-US": { } },
  "diffs": [],
  "blockers": [],
  "warnings": [],
  "role_upgrades": []
}

If a language requires a higher role, it appears in role_upgrades; unsupported language stacks appear in blockers.

Enrich Company

POST /v1/agents/enrich-company

Uses AI with Google Search grounding to generate a company description from a website URL, suitable for an agent's persona.

Body

Field	Type	Description
`companyName`	string	Company name
`websiteUrl`	string	Company 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

json

{
  "enriched": true,
  "companyDescription": "Acme Corp is a leading provider of...",
  "knowledgeBase": []
}

Agents ​

List Agents ​

Query Parameters ​

Example Request ​

Response 200 ​

Errors ​

Model and Voice Catalog ​

Example Request ​

Response 200 ​

Agent Roles ​

Language Routing ​

Create Agent ​

Request Body ​

Persona Object ​

Playbook Object ​

advanced object ​

Features Object ​

Post-call Object ​

Example — Minimal ​

Example — Full Configuration ​

Response 201 ​

Errors ​

Get Agent ​

Path Parameters ​

Example Request ​

Response 200 ​

Errors ​

Update Agent ​

Path Parameters ​

Request Body ​

Example Request ​

Response 200 ​

Errors ​

Clone Agent ​

Path Parameters ​

Example Request ​

Response 201 ​

Errors ​

List Agent Calls ​

Path Parameters ​

Query Parameters ​

Example Request ​

Response 200 ​

Errors ​

Delete Agent ​

Path Parameters ​

Example Request ​

Response 200 ​

Errors ​

Generate Agent Draft ​

Request Body ​

Example — Create Mode ​

Response 200 — Generated ​

Response 200 — Clarifying Questions ​

Example — Edit Mode ​

Errors ​

Configuration Reference ​

Top-level Fields ​

persona Object ​

playbook Object ​

advanced Object ​

features Object ​

post_call Object ​

Validate Publish ​

Apply Changes ​

Preview Model Stack ​

Enrich Company ​

Agents

List Agents

Query Parameters

Example Request

Response `200`

Errors

Model and Voice Catalog

Example Request

Response `200`

Agent Roles

Language Routing

Create Agent

Request Body

Persona Object

Playbook Object

`advanced` object

Features Object

Post-call Object

Example — Minimal

Example — Full Configuration

Response `201`

Errors

Get Agent

Path Parameters

Example Request

Response `200`

Errors

Update Agent

Path Parameters

Request Body

Example Request

Response `200`

Errors

Clone Agent

Path Parameters

Example Request

Response `201`

Errors

List Agent Calls

Path Parameters

Query Parameters

Example Request

Response `200`

Errors

Delete Agent

Path Parameters

Example Request

Response `200`

Errors

Generate Agent Draft

Request Body

Example — Create Mode

Response `200` — Generated

Response `200` — Clarifying Questions

Example — Edit Mode

Errors

Configuration Reference

Top-level Fields

`persona` Object

`playbook` Object

`advanced` Object

`features` Object

`post_call` Object

Validate Publish

Apply Changes

Preview Model Stack

Enrich Company