Python SDK
The rymi Python package wraps the Rymi REST API for server-side use. Use it from backend services, workers, and data pipelines that manage agents, calls, numbers, and webhook verification.
INFO
rymi is published on PyPI and is the supported server-side SDK for Python teams. For in-browser / WebRTC voice, use the Browser SDK or the React SDK, or build against the REST API with publishable keys.
Installation
pip install rymiLatest release: rymi on PyPI.
Initialization
from rymi import Rymi
rymi = Rymi(api_key="rymi_your_secret_key")
# Or use the RYMI_API_KEY environment variable:
rymi = Rymi()Accounts
rymi.accounts lists accounts, renames one, and manages members and this month's workspace usage. Roles are owner, admin, and billing. See Accounts.
accounts = rymi.accounts.list()["accounts"]
account = rymi.accounts.get(accounts[0]["id"])["account"]
rymi.accounts.update(account["id"], "Rymi")
added = rymi.accounts.add_member(account["id"], "arvind@example.com", "billing")
rymi.accounts.list_members(account["id"])
rymi.accounts.update_member(account["id"], added["member"]["user_id"], "admin")
rymi.accounts.remove_member(account["id"], added["member"]["user_id"])
rymi.accounts.workspaces(account["id"])Workspaces
Pass workspace, or set RYMI_WORKSPACE, and every request sends Rymi-Workspace. with_workspace returns a client aimed at one workspace you can reach. An account key may name any workspace in its account. A workspace key that names another workspace receives workspace_forbidden.
rymi = Rymi(api_key="rymi_your_secret_key", workspace="7c9e6679-7425-40de-944b-e07fc1f90ae7")
client = rymi.with_workspace("7c9e6679-7425-40de-944b-e07fc1f90ae7")
client.compliance.get_settings()rymi.workspaces covers the workspaces API:
listed = rymi.workspaces.list()
# In the current account. operating_country saves that country's compliance preset.
created = rymi.workspaces.create("Sarang Stay Homes", operating_country="IN")
rymi.workspaces.update(created["workspace"]["id"], name="Sarang", spend_cap_cents_monthly=5000)
usage = rymi.workspaces.usage(created["workspace"]["id"], month="2026-10") # calls, minutes, credits
rymi.workspaces.add_member(created["workspace"]["id"], email="client@example.com", role="client")
rymi.workspaces.list_members(created["workspace"]["id"])
rymi.workspaces.remove_member(created["workspace"]["id"], user_id="<user id>")
# Empty workspace, account Owner. The primary workspace returns cannot_delete_primary.
rymi.workspaces.delete(created["workspace"]["id"])create lands in the current account. parent must name a workspace in that account. role on a listed workspace is admin, editor, client, viewer, or null, with account_id, account_name, and account_role. add_member takes admin, editor, client, or viewer (default client). usage takes month as YYYY-MM (UTC). Omit it for the current month. Credits are omitted for the client and viewer roles. delete raises on cannot_delete_primary (400) and on workspace_not_empty (409), whose body lists the blockers. An account Owner can delete an empty workspace. See Workspaces and Delete a workspace.
Agents
agent = rymi.agents.create(
name="Customer Support",
system_prompt="You are a helpful customer support assistant for Acme Corp.",
voice="Aoede",
language="en-US",
)
agent_id = agent["id"]
agents = rymi.agents.list(limit=20)
options = rymi.agents.llm_options()create and update accept **kwargs that pass straight through to the REST body, so any documented agent field works, including multi-language and model-stack configuration:
bilingual = rymi.agents.create(
name="Ganga Sahayak",
language="hi-IN",
supported_languages=["hi-IN", "en-US"],
llm_provider="gemini",
llm_model="gemini-2.5-flash",
tts_provider="sarvam",
llm_fallback_provider="openai",
llm_fallback_model="gpt-4o-mini",
)Preview the model stack
preview = rymi.agents.preview_stack(
supported_languages=["hi-IN", "en-US"],
)
print(preview["blockers"], preview["warnings"]) # empty == good to saveKnowledge sources, history & evals
# Knowledge (RAG): add from text or a URL
rymi.agents.add_knowledge_source(agent_id, kind="text", title="Refund policy",
text="Refunds are processed within 5 business days...")
sources = rymi.agents.list_knowledge_sources(agent_id)
rymi.agents.delete_knowledge_source(agent_id, sources["sources"][0]["id"])
# Configuration history: auditable, reversible
changes = rymi.agents.list_changes(agent_id)
rymi.agents.undo_change(agent_id, changes["changes"][0]["change_id"])
# Evaluations
run = rymi.agents.run_evals(agent_id, mode="synthetic")
runs = rymi.agents.list_eval_runs(agent_id)
detail = rymi.agents.get_eval_run(agent_id, run["id"])# Clone an agent
clone = rymi.agents.clone(agent_id)
# List calls for an agent
calls = rymi.agents.list_calls(agent_id, limit=20)
# Validate before publishing
report = rymi.agents.validate_publish(agent_id=agent_id)
# Apply a change-set (does not persist; follow up with update())
result = rymi.agents.apply_changes(
current_config={"name": "Support", "voice": "Aoede"},
changes=[{"key": "voice", "value": "Charon"}],
mode="edit"
)
rymi.agents.update(agent_id, **result["config"])
# Enrich company from website
info = rymi.agents.enrich_company("Acme Corp", "https://acme.example.com")
if info["enriched"]:
print(info["companyDescription"])Calls
call = rymi.calls.create(
agent_id=agent_id,
participants=[
{
"transport": "pstn",
"identity": "+15551234567",
"from_number": "+15559876543"
}
],
metadata={"customer_name": "Alice"},
variables={"customer_segment": "renewal"}
)
details = rymi.calls.retrieve(call["id"])
transcript = rymi.calls.transcript(call["id"])Confirm a test destination
Shared test lines only call a number this user confirmed on WhatsApp. start opens the request and returns the link. It does not confirm the number. The phone confirms it by sending message_text. A secret key needs calls:write to start and calls:read to check. See Confirm a test destination.
pending = rymi.phone_confirmation.start("+919876543210")
if not pending["confirmed"]:
print(pending["wa_url"], pending["message_text"], pending["expires_in"])
status = rymi.phone_confirmation.status("+919876543210")To confirm by code, call request_code. A person then types the code at entry_url while signed in to Studio. No secret key can submit a code, and a confirmed number is never a login number. See Request a code.
sent = rymi.phone_confirmation.request_code("+919876543210")
print(sent["entry_url"], sent["expires_in"], sent["resend_after"])409 in_progress means someone is already confirming that number (try again in 10 minutes). 429 daily_limit means this user has started 20 confirmations today. 503 means WhatsApp confirmation is not configured.
Control a live call
# Add a participant to a live call
rymi.calls.add_participants(call["id"], [
{"transport": "pstn", "identity": "+15557654321", "from_number": "+15559876543"}
])
# End the call
rymi.calls.end(call["id"])Batch Calls
batch = rymi.calls.batch(
agent_id=agent_id,
to=["+15551234567", "+15557654321"],
from_number="+15559876543",
variables={"batch_label": "renewal-q2"}
)
print(batch["batch_id"], batch["queued"])Do-Not-Call (DNC)
Numbers are normalized to E.164 server-side, so any input format is accepted. Outbound calls to blocked numbers are refused.
rymi.dnc.add(phone_number="+15551234567", reason="customer opt-out")
# Add up to 1000 at once; invalid numbers are skipped and returned
result = rymi.dnc.add_batch(phone_numbers=["+15551234567", "+15557654321"])
print(result["count"], result["invalid_count"], result["invalid"])
# Check up to 500 numbers without adding them (read-only)
check = rymi.dnc.check(phone_numbers=["+15551234567"])
print(check["blocked_count"])
entries = rymi.dnc.list(limit=50)
rymi.dnc.remove("+15551234567") # re-enables outbound to itSee the Compliance API for the underlying REST endpoints.
Compliance settings
Calling hours, the do-not-call check, voice consent, the recording notice for new agents, and destination countries. Choosing operating_country fills every setting you have not edited. See the guide.
settings = rymi.compliance.get_settings()
preview = rymi.compliance.preview_settings("IN")
rymi.compliance.update_settings(operating_country="IN", rules={"apply_to_single_calls": True})update_settings(operating_country=None) clears the country and leaves the rules in place. Leave the argument out to keep the country.
Numbers
rymi.numbers.register("+15559876543")
numbers = rymi.numbers.list()
rymi.numbers.attach(numbers["numbers"][0]["number"], agent_id)
# Detach + remove a number from the account
rymi.numbers.remove(numbers["numbers"][0]["number"])Telephony
status = rymi.telephony.status() # {"connected": ..., "provider": ...}
carrier_numbers = rymi.telephony.numbers()
# Connect / disconnect a carrier (requires carrier credentials)
rymi.telephony.connect(provider="twilio", auth_id="AC...", auth_token="...")
rymi.telephony.disconnect()Phone line from Rymi
See Phone Line from Rymi for fields and errors.
result = rymi.telephony.line()
studio_url = rymi.telephony.request_line("IN", handoff="both")["studio_url"]
rymi.telephony.accept_line_terms()
rymi.telephony.submit_line_kyc(fields={"name": "Sharma Realty Pvt Ltd", "city": "Pune"}, submit=True)
held = rymi.agents.pending_publish(agent_id)
rymi.contacts.record_consent("+919876543210", source="web_form", consent_text="I agree to receive calls.")Secret keys
keys.create mints an account or workspace key. The response field is key, shown once. keys.self reads the key authenticating this client. See API keys and scopes.
created = rymi.keys.create(
kind="workspace",
scopes=["calls:write", "agents:read"],
label="Website calls",
)
print(created["key"])
self = rymi.keys.self()
# kind, account_id, workspace_id, scopes, legacyPublishable keys
list_publishable returns prefixes only. create_publishable returns the full key once, so store it then. These use your secret key, so call them server-side only.
keys = rymi.keys.list_publishable() # prefixes only, never full secrets
created = rymi.keys.create_publishable(
agent_id=agent["id"],
label="Marketing site widget",
allowed_channels=["web"],
)
print(created["key"]) # sb_publishable_...: store now
rymi.keys.revoke_publishable(created["id"])Usage
Voice balance is reported in minutes (the customer-facing unit), not dollars.
usage = rymi.billing.usage_summary()
print(usage["voice_runtime"]["remaining_minutes"], usage["voice_runtime"]["status"])Cost estimate & spend controls
Spend-management settings are denominated in USD.
est = rymi.billing.estimate(
stt_model="nova-2",
llm_model="gemini-2.5-flash",
tts_model="gemini-2.5-flash-tts",
duration_seconds=300,
)
rymi.billing.set_auto_recharge(enabled=True, pack_usd=50, threshold_usd=10)
rymi.billing.set_alerts(thresholds_usd=[25, 50], low_balance_pct=15, email_enabled=True)
# Billing country. Locked after the first paid invoice (409 billing_country_locked).
rymi.billing.set_country("IN")Campaigns and live leads
Create a campaign, launch it, then keep adding people while it runs. See Campaigns and the Campaigns API.
campaign = rymi.campaigns.create(
agent_id="agent_123",
type="outbound",
name="Subscriber updates",
schedule_policy={"start": "09:00", "end": "20:00", "timezone": "Asia/Kolkata"},
)["campaign"]
rymi.campaigns.launch(campaign["id"])
# Push a lead from your backend; it's dialed on the next sweep inside the window.
rymi.campaigns.members.import_(campaign["id"], contacts=[{"phone": "+919876543210", "name": "Ramesh", "consent": {"voice": True}}])
# Or give a form tool a URL it can post to without an API key (shown once).
url = rymi.campaigns.intake.set(campaign["id"], assume_voice_consent=True, default_country="IN")["url"]Sharing and API-tool secrets
link = rymi.agents.set_share_link("agent_123", enabled=True, minutes_limit=120)["link"]
rymi.tool_secrets.set("RESERVATIONS_API_KEY", value="sk_live_...", host="api.example.com")Templates
templates = rymi.templates.list()["templates"]
starter = next((t for t in templates if t["label"] == "Healthcare Receptionist"), None)
if starter:
rymi.agents.create(name="Front Desk", **starter["defaults"])Webhooks
Register and maintain the endpoints Rymi delivers events to. Each endpoint has its own signing secret; keep it to verify deliveries (below).
created = rymi.webhooks.create(
url="https://api.example.com/rymi-webhook",
events=["call.completed", "call.intelligence.ready"],
secret="whsec_your_webhook_secret",
alert_email="oncall@example.com",
)
hooks = rymi.webhooks.list()
rymi.webhooks.update(hooks["webhooks"][0]["id"], events=["call.intelligence.ready"])
rymi.webhooks.delete(hooks["webhooks"][0]["id"])Verifying deliveries
verify_signature is a stateless helper; it needs no API key.
import json
from flask import Flask, request, jsonify
from rymi import Rymi
app = Flask(__name__)
rymi = Rymi()
@app.route("/webhook", methods=["POST"])
def handle_webhook():
signature = request.headers.get("x-rymi-signature")
timestamp = request.headers.get("x-rymi-timestamp")
payload_raw = request.get_data(as_text=True)
rymi.webhooks.verify_signature(
payload_raw,
signature,
timestamp,
"whsec_your_webhook_secret"
)
event = json.loads(payload_raw)
if event["type"] == "call.intelligence.ready":
print("Summary:", event["data"]["summary"])
return jsonify(status="OK"), 200
