Skip to navigation
Developers

Developer overview

Build on Rydhm from your own code. Base URLs, versioning, and your first request.

The Rydhm API gives your code the same experts your team uses in the app. Everything is scoped to one workspace and authenticated with an API key.

What you can build

Chat from your backend

Start a conversation with any expert, private ones included, and stream its replies.

Voice in your own app

Mint a voice-session token on your server and connect from your frontend.

Experts in meetings

Send an expert into a Google Meet, Zoom or Teams call, then read the transcript and summary.

Knowledge in sync

Add, search and remove an expert’s documents from your own content pipeline.

React to events

Get signed webhooks when meetings end, summaries are ready or documents finish processing.

Use experts from AI tools

Connect Claude, Cursor and other MCP clients to your experts.

Embed on your website

Add the chat and voice widget to your site with one tag.

Talk to other agents

Publish an Agent Card and let other agents talk to public experts.

Base URLs

WhatURL
The APIhttps://api.rydhm.ai/v1
The MCP endpoint (not under /v1)https://api.rydhm.ai/mcp/experts/{expert id}
The OpenAPI document (no key needed)https://api.rydhm.ai/v1/openapi.json

Developers → API reference in the app shows the address for your workspace. To call the API through another host, such as your own proxy, set baseUrl (TypeScript) or base_url (Python) on the SDK client.

The API calls experts agents in its paths and fields: /v1/agents/{id} is an expert, and agentId is an expert’s id.

Requests and responses

  • Send JSON bodies with Content-Type: application/json. A body can be up to 12 MB, which matters for file uploads sent as base64.
  • Ids are UUIDs. Times are ISO 8601 strings in UTC.
  • Every response carries an X-Request-Id header. Quote it to support. See Errors.
  • Errors share one JSON shape, and rate-limited routes send X-RateLimit-* headers. See Errors.

Versioning

The version is in the path: every route is under /v1. The OpenAPI document also carries a date version in info.version (currently 2026-11-09).

New fields and new routes can appear within v1. Build your client to ignore fields it doesn’t know.

Your first request

You need to be a workspace admin to create a key.

1

Create a key

In the app, go to Developers → API keys and choose Create API key. Name it, set Experts under Permissions to Read, and choose Create key. Copy the key: it is shown once.

2

Store it

Put the key in an environment variable on your machine:

export RYDHM_API_KEY="rydhm_live_…"
3

List your experts

curl https://api.rydhm.ai/v1/agents \
  -H "Authorization: Bearer $RYDHM_API_KEY"

The response is a list of experts:

[
  {
    "id": "7b08028d-0a4c-47ee-a91e-4b8d65c43cd1",
    "orgId": "594284c3-1ee2-482e-8f1c-209fb6539a4b",
    "name": "Ava",
    "description": "Answers product questions and walks prospects through features.",
    "firstMessage": "Hi, I'm Ava. What can I help you with?",
    "isActive": true,
    "visibility": "unlisted",
    "slug": "ava-k8nzvywsyuhw",
    "createdAt": "2026-10-26T16:25:46.372Z",
    "updatedAt": "2026-11-09T14:32:34.155Z"
  }
]

Each expert also carries its full settings (personaPrompt, voiceConfig, widgetConfig and more). Secrets in its settings are masked. Keep one expert’s id: the next sections use it.

The SDKs aren’t published to npm or PyPI yet. See TypeScript SDK and Python SDK.

Chat with an expert

A chat takes three calls: start a conversation, send a message, then read the reply as a stream. The key needs chat:write.

# 1. Start a conversation
curl -X POST https://api.rydhm.ai/v1/chat/conversations \
  -H "Authorization: Bearer $RYDHM_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"agentId\":\"$EXPERT_ID\"}"
# → {"id":"e153628d-…","agentId":"…","kind":"text","channel":"api",…}
# 2. Send a message
curl -X POST https://api.rydhm.ai/v1/chat/conversations/$CONVERSATION_ID/messages \
  -H "Authorization: Bearer $RYDHM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"What can you help with?"}'
# 3. Stream the reply
curl -N https://api.rydhm.ai/v1/chat/conversations/$CONVERSATION_ID/stream \
  -H "Authorization: Bearer $RYDHM_API_KEY" \
  -H "Accept: text/event-stream"

To continue the conversation, send the next message and stream again. To read it later, call GET /v1/chat/conversations/{id}/messages (needs conversations:read).

To ground a chat in a meeting’s transcript, pass meetingId when you start it.

Stream the reply

The stream is server-sent events. Each event’s data is one JSON frame:

id: 1
data: {"type":"sources","count":6,"items":[{"documentId":"cee182e0-…","filename":"pricing.md","kind":"text","sourceUrl":null,"ord":0}]}
id: 2
data: {"type":"delta","content":"I help teams "}
id: 3
data: {"type":"delta","content":"understand pricing."}
id: 4
data: {"type":"message","id":"65acd98a-…","role":"agent","content":"I help teams understand pricing."}
id: 5
data: {"type":"done"}
FrameWhat it carries
sourcesHow many knowledge passages ground the reply (count), and which documents (items). Comes first.
deltaThe next piece of the reply’s text (content). Append them in order.
tool_callA tool the expert decided to call (id, label, args), sent before it runs.
tool_resultThe tool’s outcome (id, ok, ms, and a preview of up to 400 characters).
messageThe whole reply as stored (id, role, content).
doneThe reply is complete. The stream ends.
errorThe reply failed (message). The stream ends.

Each reply is a model call, metered as chat usage.

Voice in your own frontend

Your server mints a short-lived voice-session token; your frontend uses it to join the call with the LiveKit client SDK. The key never leaves your server. The key needs voice_sessions:write.

curl -X POST https://api.rydhm.ai/v1/voice/sessions \
  -H "Authorization: Bearer $RYDHM_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"agentId\":\"$EXPERT_ID\",\"variables\":{\"name\":\"Priya\"}}"
{
  "serverUrl": "wss://…",
  "roomName": "…",
  "participantToken": "eyJhbGciOi…"
}

Join with serverUrl and participantToken within 15 minutes. The body can also carry conversationId, to continue an earlier conversation by voice, and variables, values for the expert’s {{variables}} (up to 20).

Send an expert to a meeting

POST /v1/meetings sends an expert into a Google Meet, Zoom or Microsoft Teams call, now or at scheduledAt. It needs its own scope, meetings:join, because it costs money and joins calls with people outside your workspace.

curl -X POST https://api.rydhm.ai/v1/meetings \
  -H "Authorization: Bearer $RYDHM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-event-4821" \
  -d "{\"agentId\":\"$EXPERT_ID\",\"joinUrl\":\"https://meet.google.com/abc-defg-hij\",\"mode\":\"speaker\"}"
  • joinUrl is the meeting link. A whole pasted invite works too; the link is taken from it.
  • mode is speaker (the expert talks) or listener (it only listens).
  • brief tells the expert what it should know going in.

Always send an Idempotency-Key. A retry with the same key returns the first result instead of sending a second bot. Keys are kept for 24 hours, per workspace and route; a replayed response carries Idempotent-Replayed: true.

Read the meeting, its transcript and its summary with GET /v1/meetings/{id} (needs meetings:read), or subscribe to the meeting.* webhooks.

Next steps