API Reference

Welcome to the Rymi Voice API. Build, deploy, and manage AI-powered voice agents through REST endpoints under /v1.

Base URL

https://api.rymi.live

All endpoints are prefixed with /v1. For example, https://api.rymi.live/v1/agents.

Authentication

Rymi uses Bearer token authentication via the Authorization header.

curl https://api.rymi.live/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Header	Value
Authorization	Bearer <YOUR_API_KEY>
Content-Type	application/json

Key Types

Key Type	Prefix	Use Case
Secret Key	rymi_	Full management API access. Use only on your backend
Publishable Key	sb_publishable_	Frontend-safe, scoped to call creation flows

TIP

Legacy rymi_pk_ publishable keys remain accepted, but new keys use the sb_publishable_ format. Refer to Publishable Keys for scope details.

Rate Limits

The API enforces tenant, API-key, and IP-based rate limits. Limits vary by plan and may be tightened on specific flows such as public demo phone calls created with publishable keys.

Plan	Requests / min	Concurrent Calls	Burst Allowance
Free	60	1	5 requests
Go	300	10	25 requests
Plus	1,000	50	100 requests
Custom	Unlimited	Custom	Custom

When a rate limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

Pagination

List endpoints return paginated responses. Most resources use limit plus offset. Call history also supports cursor-based pagination.

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

Parameter	Type	Default	Description
limit	integer	50	Maximum number of records to return (max 200)
offset	integer	0	Number of records to skip before starting to collect the result set

Calls additionally accept:

Parameter	Type	Default	Description
cursor	string	—	Resume from a previous call ID when traversing call history
status	string	—	Filter calls by status: queued, ringing, in_progress, completed, or failed

Example paginated response:

{
  "agents": [ ... ],
  "total": 142,
  "limit": 10,
  "offset": 20
}

Error Format

All errors return a JSON body with at least an error field:

{
  "error": "Human-readable error message"
}

Write endpoints may include additional context:

{
  "error": "Insufficient credits to start this call",
  "code": "insufficient_credits",
  "detail": "tenant_balance_exhausted"
}

HTTP Status Codes

Code	Meaning
200	Success
201	Resource created
202	Accepted — queued for async processing
400	Bad request or validation error
401	Missing or invalid API key
402	Insufficient credits
403	Authenticated but not allowed for this token scope
404	Resource not found
409	Conflict with current resource state
429	Rate limit exceeded — retry after the Retry-After header value
500	Internal server error
502	Upstream provider error (e.g., telephony or voice provider failure)

API Surface

These are the public APIs available for self-serve users. Admin routes, internal queue dashboards, and carrier number purchase/search APIs are intentionally excluded.

Area	Endpoints	Description
Agents	GET POST PUT DELETE /v1/agents, GET /v1/agents/:id/calls, POST /v1/agents/generate, GET /v1/agents/llm-options	Core configuration for voice personas, provider routing, prompt/playbook structure, and agent roles
Calls	POST /v1/calls, GET /v1/calls, GET /v1/calls/active, GET /v1/calls/:id, POST /v1/calls/:id/participants, POST /v1/calls/:id/end, GET /v1/calls/:id/events, GET /v1/calls/:id/summary, GET /v1/calls/:id/transcript, GET /v1/calls/:id/recording, POST /v1/calls/:id/reprocess, GET /v1/calls/queue/stats	WebRTC and PSTN call lifecycle, post-call inspection, and queue monitoring
Queue & Fanout	POST /v1/calls/batch	High-throughput outbound dialing for up to 500 PSTN recipients per request
Numbers	POST /v1/numbers, GET /v1/numbers, POST /v1/numbers/:number/attach, DELETE /v1/numbers/:number	BYOC phone number registration and agent assignment
Telephony	POST /v1/telephony/connect, POST /v1/telephony/disconnect, GET /v1/telephony/status, GET /v1/telephony/numbers	Carrier abstraction for Plivo, Twilio, and Vonage
Voice Providers	GET POST /v1/voice-providers/elevenlabs/*	BYO premium voice catalog via ElevenLabs integration
Publishable Keys	GET POST DELETE /v1/keys/publishable	Frontend-safe, scoped keys for SDK call creation
Realtime Tokens	POST /v1/realtime/token, POST /v1/webrtc/token	WebRTC session tokens backed by LiveKit
Webhooks	POST GET PATCH DELETE /v1/webhooks	Event delivery for transcripts, post-call intelligence, and automation hooks
Compliance	POST GET DELETE /v1/dnc, POST /v1/dnc/batch, POST /v1/dnc/check	Do-Not-Call registry with bulk import and pre-flight checks
Analytics	GET /v1/analytics/spend	Usage, spend, call-quality, and agent performance reporting
Notifications	GET /v1/notifications, PUT /v1/notifications/read-all, PUT /v1/notifications/:id/read, GET PUT /v1/notifications/preferences	In-app notification feed and delivery preferences
Languages	GET /v1/languages	Supported language catalog for agent configuration
Auth	GET /v1/auth/me, POST /v1/auth/regenerate-key	Account profile and secret key rotation

Client Libraries

Library	Description
Browser SDK	Add AI voice to any website with @rymi/web
React SDK	React provider and hooks with @rymi/react
Node.js SDK	Server-side SDK with @rymi/node
Python SDK	Server-side SDK with rymi