API Reference

Build, deploy, and manage AI 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 applies a flat, env-configurable rate limit — by default 100 requests per 60-second window, with no burst allowance and no per-plan tiers. The limit is counted independently per API key and per client IP, so whichever runs out first triggers throttling.

Specific flows add their own limits on top of this — notably, PSTN calls created with a publishable key are capped at one call per 10 minutes per key + IP.

When a rate limit is exceeded, the API returns 429 Too Many Requests with a JSON body ({ "error": "Rate limit exceeded (...)" }). No Retry-After header is sent.

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. The default is 50, but the accepted maximum varies per endpoint — see each endpoint's reference (e.g. agents list caps at 500, calls list defaults to 200 and caps at 1000)
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 — the response body carries the error message
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 /v1/agents, PUT PATCH DELETE /v1/agents/:id, GET /v1/agents/:id/calls, POST /v1/agents/generate, GET /v1/agents/llm-options	Core configuration for voice personas, provider routing, and prompt/playbook structure
Knowledge Sources	POST GET /v1/agents/:id/knowledge-sources, DELETE /v1/agents/:id/knowledge-sources/:sourceId, POST /v1/agents/:id/knowledge-sources/upload	Ground agents in your own documents with full-text or embedding retrieval
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
BYO Providers	GET POST /v1/providers, DELETE /v1/providers/:provider, GET /v1/providers/fields, POST /v1/providers/:provider/validate	Bring your own keys for 25+ LLM, speech-to-text, and voice providers
Publishable Keys	GET POST /v1/keys/publishable, DELETE /v1/keys/publishable/:id	Frontend-safe, scoped keys for SDK call creation
Webhooks	POST GET /v1/webhooks, PATCH DELETE /v1/webhooks/:id	Event delivery for transcripts, post-call intelligence, and automation hooks
Compliance	POST GET /v1/dnc, DELETE /v1/dnc/:phone, 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, GET POST /v1/auth/api-keys, DELETE /v1/auth/api-keys/:id	Account profile, secret key rotation, and multi-key management

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