API reference
The meeAgent voice API. You pick a voice, write the agent's instructions, and open a call.
Authentication
| Who | How |
|---|---|
| Your backend | Authorization: Bearer mk_live_… (an API key) |
| Your users' browsers | a client_token, single use, 60 s, in the realtime URL |
The API key never goes to a browser. Your backend asks for a client_token and hands that to the page. A key carries scopes (x-scope on each operation below); a key that lacks the scope an operation needs gets 403 naming it.
Identifiers, dates, money
Identifiers are a prefix plus 20 base32 characters (agt_…, ses_…). Dates are ISO-8601 in UTC. Money is an object with amount and currency; amount can be null, which means the call could not be priced, not that it was free.
Errors
Every failure returns {"error": {"code", "message", "param"?}}. Match on code.
Rate limits
Each operation carries its own under x-rate-limit. On top of those, any call made with an API key is limited to 600 per minute per key. Exceeding a limit returns 429 with Retry-After.
Auth
/v1/auth/signupSignup
{
"email": "ana@acme.com",
"password": "correct-horse-battery",
"company_name": "Acme"
}
{
"status": "pending_verification"
}
curl -X POST "https://test.meeagent.ai/v1/auth/signup" \
-H "Content-Type: application/json" \
-d '{
"email": "ana@acme.com",
"password": "correct-horse-battery",
"company_name": "Acme"
}'
/v1/auth/verify-emailVerify Email
200 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/auth/verify-email"
/v1/auth/loginLogin
{
"email": "ana@acme.com",
"password": "correct-horse-battery"
}
{
"access_token": "eyJhbGciOiJIUzI1NiIs…",
"token_type": "bearer",
"user": {
"id": "usr_…",
"email": "ana@acme.com",
"name": "Ana",
"role": "owner"
}
}
curl -X POST "https://test.meeagent.ai/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{
"email": "ana@acme.com",
"password": "correct-horse-battery"
}'
/v1/auth/otp/requestOtp Request
202 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/auth/otp/request"
/v1/auth/otp/verifyOtp Verify
200 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/auth/otp/verify"
/v1/auth/password/forgotPassword Forgot
202 exista o no el correo: quién tiene cuenta aquí no se averigua preguntando.
202 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/auth/password/forgot"
/v1/auth/password/resetPassword Reset
Sin sesión de vuelta a propósito: quien acaba de poner la contraseña entra con ella.
204 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/auth/password/reset"
/v1/auth/password/changePassword Change
Cierra las demás sesiones y devuelve un token nuevo para no cerrar también esta.
200 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/auth/password/change"
/v1/auth/invitations/acceptAccept Invitation
Entra en el tenant que invitó, con el rol que le pusieron y el correo ya verificado.
200 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/auth/invitations/accept"
/v1/auth/logoutLogout
Revokes this JWT by jti until it expires; later requests with it get 401.
204 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/auth/logout"
/v1/meMe
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/me"
Catalog
/v1/voicesList Voices
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/voices" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/runtimesList Runtimes
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/runtimes" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
Agents
/v1/agentsList Agents
| Name | Type | Required | Description |
|---|---|---|---|
limit (query) | integer | Optional | |
cursor (query) | string | null | Optional |
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/agents" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/agentsCreate Agent
{
"name": "Support Acme",
"instructions": "You are a customer support agent for Acme. Be brief and warm.",
"voice": "eva",
"language": "es-CO",
"tools": [
{
"type": "webhook",
"name": "get_order",
"url": "https://acme.com/hooks/order"
}
]
}
{
"id": "agt_k3m9x2p7q1r5t8v4w6y2",
"name": "Support Acme",
"description": "",
"instructions": "You are a customer support agent for Acme. Be brief and warm.",
"voice": "eva",
"runtime": "mee-voice-standard",
"language": "es-CO",
"tools": [
{
"type": "webhook",
"name": "get_order",
"url": "https://acme.com/hooks/order",
"description": "",
"status": "available"
}
],
"limits": {
"max_duration_s": 900,
"max_instructions_chars": 8000
},
"status": "active",
"created_at": "2026-09-18T10:00:00Z",
"updated_at": "2026-09-18T10:00:00Z"
}
curl -X POST "https://test.meeagent.ai/v1/agents" \
-H "Authorization: Bearer $MEEAGENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Support Acme",
"instructions": "You are a customer support agent for Acme. Be brief and warm.",
"voice": "eva",
"language": "es-CO",
"tools": [
{
"type": "webhook",
"name": "get_order",
"url": "https://acme.com/hooks/order"
}
]
}'
/v1/agents/{agent_id}Get Agent
| Name | Type | Required | Description |
|---|---|---|---|
agent_id (path) | string | Required |
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/agents/{AGENT_ID}" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/agents/{agent_id}Patch Agent
| Name | Type | Required | Description |
|---|---|---|---|
agent_id (path) | string | Required |
200 — Successful Response
curl -X PATCH "https://test.meeagent.ai/v1/agents/{AGENT_ID}" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/agents/{agent_id}Delete Agent
| Name | Type | Required | Description |
|---|---|---|---|
agent_id (path) | string | Required |
204 — Successful Response
curl -X DELETE "https://test.meeagent.ai/v1/agents/{AGENT_ID}" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
Sessions
/v1/sessionsCreate Session
201 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/sessions" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/sessionsList Sessions
| Name | Type | Required | Description |
|---|---|---|---|
limit (query) | integer | Optional | |
cursor (query) | string | null | Optional |
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/sessions" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/sessions/tokenSession Token
Con Idempotency-Key, un reintento devuelve el token de antes en vez de cobrar otra sesión.
{
"agent_id": "agt_k3m9x2p7q1r5t8v4w6y2",
"context": {
"customer_id": "42"
}
}
{
"client_token": "cZhQgeK9DhIYAmAHVLVZq5aplEUMRn-HxmTLm0-zVFc",
"session_id": "ses_2ku2tkwhrjkemlzjl6pj",
"expires_at": "2026-09-18T10:01:00Z",
"realtime_url": "wss://api.meeagent.ai/v1/realtime",
"max_duration_s": 900,
"transport": null
}
curl -X POST "https://test.meeagent.ai/v1/sessions/token" \
-H "Authorization: Bearer $MEEAGENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agt_k3m9x2p7q1r5t8v4w6y2",
"context": {
"customer_id": "42"
}
}'
/v1/demoDemo Status
Estado de la demo pública, para que la web sepa qué ofrecer antes de pedir un token.
Sin autenticación y sin efectos: comparte el cupo del catálogo porque es lo mismo, una página pública preguntando qué hay. Pedir esto nunca gasta el cupo de llamada.
enabled es conservador: dice que creemos que la llamada funcionaría. Si falta la clave del proveedor, o si ninguna llamada reciente llegó a sonar, dice que no y la web ofrece otra cosa —que es mejor que un botón de llamar que contesta 503.
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/demo"
/v1/demo/tokenDemo Token
Public website demo (ADR 0002): no API key, one call per IP per window, small concurrency cap.
{
"voice": "eva"
}
200 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/demo/token" \
-H "Content-Type: application/json" \
-d '{
"voice": "eva"
}'
/v1/sessions/{session_id}Get Session
| Name | Type | Required | Description |
|---|---|---|---|
session_id (path) | string | Required |
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/sessions/{SESSION_ID}" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/sessions/{session_id}/updateUpdate Session
| Name | Type | Required | Description |
|---|---|---|---|
session_id (path) | string | Required |
200 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/sessions/{SESSION_ID}/update" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/sessions/{session_id}/cancelCancel
| Name | Type | Required | Description |
|---|---|---|---|
session_id (path) | string | Required |
204 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/sessions/{SESSION_ID}/cancel" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/sessions/{session_id}/endEnd
| Name | Type | Required | Description |
|---|---|---|---|
session_id (path) | string | Required |
204 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/sessions/{SESSION_ID}/end" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/sessions/{session_id}/transcriptTranscript
| Name | Type | Required | Description |
|---|---|---|---|
session_id (path) | string | Required |
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/sessions/{SESSION_ID}/transcript" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/sessions/{session_id}/eventsEvents
| Name | Type | Required | Description |
|---|---|---|---|
session_id (path) | string | Required |
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/sessions/{SESSION_ID}/events" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
Account
/v1/usageUsage
| Name | Type | Required | Description |
|---|---|---|---|
from (query) | string | null | Optional | |
to (query) | string | null | Optional | |
group_by (query) | string | Optional |
{
"minutes": 12.5,
"sessions": 7,
"api_requests": 143,
"spend": {
"amount": 0.625,
"currency": "USD"
},
"unpriced_sessions": 0,
"series": [
{
"key": "2026-09-18",
"minutes": 12.5,
"sessions": 7,
"spend": 0.625,
"api_requests": 143
}
]
}
curl -X GET "https://test.meeagent.ai/v1/usage" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/usage/exportUsage Export
El detalle, una fila por sesión, para llevárselo a una hoja de cálculo o a un cierre de mes.
Se manda a trozos según se lee: un trimestre de una cuenta con tráfico son decenas de miles de filas, y armarlas enteras en memoria sería dejar que un cliente grande tumbe el proceso pidiendo su propio consumo.
| Name | Type | Required | Description |
|---|---|---|---|
from (query) | string | null | Optional | |
to (query) | string | null | Optional | |
format (query) | string | Optional |
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/usage/export" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/tenantUpdate Tenant
Cuánto se guarda el historial de las llamadas. Lo decide el cliente, no nosotros.
200 — Successful Response
curl -X PATCH "https://test.meeagent.ai/v1/tenant" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/tenant/delete/requestRequest Tenant Deletion
202 siempre. Borrar una cuenta no puede depender de un clic ni de una sesión robada.
202 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/tenant/delete/request" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/tenant/delete/confirmConfirm Tenant Deletion
Apaga la cuenta en el acto y programa la purga.
200 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/tenant/delete/confirm" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/billingBilling
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/billing" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/api-keysList Keys
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/api-keys" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/api-keysCreate Key
{
"name": "production backend",
"permissions": [
"sessions:write",
"agents:read"
]
}
{
"id": "key_7h2k9m4p1q6r3t8v5w1y",
"name": "production backend",
"prefix": "mk_live_a1b2",
"permissions": [
"sessions:write",
"agents:read"
],
"status": "active",
"created_at": "2026-09-18T10:00:00Z",
"last_used_at": null,
"key": "mk_live_a1b2… shown once, never again"
}
curl -X POST "https://test.meeagent.ai/v1/api-keys" \
-H "Authorization: Bearer $MEEAGENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "production backend",
"permissions": [
"sessions:write",
"agents:read"
]
}'
/v1/api-keys/{key_id}Revoke Key
| Name | Type | Required | Description |
|---|---|---|---|
key_id (path) | string | Required |
204 — Successful Response
curl -X DELETE "https://test.meeagent.ai/v1/api-keys/{KEY_ID}" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
Members
/v1/membersList Members
Quién está dentro, y quién está invitado y todavía no ha entrado.
En {data: [...]} como el resto de listados: una lista a secas no deja sitio para añadir un cursor el día que un tenant tenga cien personas, y obligaría a la web a tratar esta ruta distinto de todas las demás.
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/members" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/members/invitationsInvite
202 se pueda o no: quién tiene cuenta aquí no se averigua invitando.
202 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/members/invitations" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/members/invitations/{invitation_id}Revoke Invitation
| Name | Type | Required | Description |
|---|---|---|---|
invitation_id (path) | string | Required |
204 — Successful Response
curl -X DELETE "https://test.meeagent.ai/v1/members/invitations/{INVITATION_ID}" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/members/{member_id}Set Role
| Name | Type | Required | Description |
|---|---|---|---|
member_id (path) | string | Required |
200 — Successful Response
curl -X PATCH "https://test.meeagent.ai/v1/members/{MEMBER_ID}" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/members/{member_id}Remove
| Name | Type | Required | Description |
|---|---|---|---|
member_id (path) | string | Required |
204 — Successful Response
curl -X DELETE "https://test.meeagent.ai/v1/members/{MEMBER_ID}" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
Webhooks
/v1/webhooksList Webhooks
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/webhooks" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/webhooksCreate Webhook
El secreto se enseña aquí y no vuelve a salir nunca, igual que una API key.
201 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/webhooks" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/webhooks/{webhook_id}Delete Webhook
| Name | Type | Required | Description |
|---|---|---|---|
webhook_id (path) | string | Required |
204 — Successful Response
curl -X DELETE "https://test.meeagent.ai/v1/webhooks/{WEBHOOK_ID}" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/webhooks/{webhook_id}/deliveriesDeliveries
Qué se intentó, cuándo y cómo acabó: la respuesta a «no me llegó».
| Name | Type | Required | Description |
|---|---|---|---|
webhook_id (path) | string | Required | |
limit (query) | integer | Optional | |
cursor (query) | string | null | Optional |
200 — Successful Response
curl -X GET "https://test.meeagent.ai/v1/webhooks/{WEBHOOK_ID}/deliveries" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/retryRetry Delivery
Vuelve a intentar una entrega que se rindió, con un ciclo nuevo de intentos.
Solo sobre failed: reintentar algo que ya se entregó sería mandarlo dos veces a propósito, y una que sigue pendiente ya tiene su hora puesta. El event_id no cambia, porque sigue siendo el mismo hecho y el cliente tiene que poder reconocerlo como repetido.
| Name | Type | Required | Description |
|---|---|---|---|
webhook_id (path) | string | Required | |
delivery_id (path) | string | Required |
202 — Successful Response
curl -X POST "https://test.meeagent.ai/v1/webhooks/{WEBHOOK_ID}/deliveries/{DELIVERY_ID}/retry" \
-H "Authorization: Bearer $MEEAGENT_API_KEY"
Realtime
The call itself runs over a WebSocket, which OpenAPI cannot describe, so it is documented here.
Open wss://…/v1/realtime?token=<client_token> with the token from POST /v1/sessions/token. The token is single use and lasts 60 seconds: if the socket drops and you reconnect, ask for a new one. Reusing a spent token is refused before the handshake.
What you send
| Message | Payload |
|---|---|
session.update | {instructions?, context?, business_state?, tools?}; answered with the new version |
response.cancel | none — stops the agent talking |
client.metrics | {eot_to_audio_ms, connect_ms?, first_audio_ms?} — one per agent turn |
ping | none — answered with pong |
What you receive
| Message | Payload |
|---|---|
session.state | {status, version}; the first one also carries session_id |
error | {code, message}; the REST codes, plus max_duration, which only exists here |
turn.user, turn.agent and latency are reserved and not emitted yet: while the audio does not pass through meeAgent there are no turns to report, which is also why GET /v1/sessions/{id}/transcript comes back empty.
Latency, measured by you
Send client.metrics after each agent turn. eot_to_audio_ms is the one that matters: from the moment the person stops speaking to the first audio of the reply. connect_ms and first_audio_ms are worth sending once, on the first turn. Anything out of range or any extra field is answered with error {code: "invalid_request"} without closing the socket: telemetry must never cost a call. The aggregate appears in latency on the session, with source: "client".
Close codes
| Code | Meaning |
|---|---|
4401 | the token is invalid, expired or already used — refused before the handshake |
4403 | the tenant, agent or runtime was stopped; an error {code: "forbidden"} is sent first |
1008 | you broke one of the channel rules below while connected |
Anything else is an ordinary WebSocket close. Reaching max_duration_s sends error {code: "max_duration"} first.
Channel rules
Four limits, and none of them is a surprise if you send what the protocol says.
- Origin. If the connection carries an Origin header — that is, it comes from a browser — the origin has to be one we know, or the connection is refused *before the handshake* (HTTP 403, the same as a bad token). With no Origin header, which is the case for an SDK or curl, the token is the only thing that matters. A WebSocket is not covered by the policy a browser applies to fetch, so this check lives here. - 40 messages every 2 seconds, per session. Going over ends the call with ended_reason: "flooded". - 10 invalid messages in a row end it with ended_reason: "protocol_error". One on its own does not: you get an error and the call goes on, and any valid message resets the count. - 32 KiB per message. The server cuts an oversized frame at its own layer, before reading it whole into memory.
Binary audio, server to server
WS /v1/realtime with Authorization: Bearer mk_… and binary PCM16 audio is planned and not available in v1.0. Today the socket takes ?token= and text messages only. That is why the control channel above is all there is for now, and why transport exists at all.
transport
POST /v1/sessions/token may return a transport block describing a direct audio channel. For a paying account it is always `null`, and you should treat it as such: it exists only for the public demo on meeagent.ai, and it will disappear once the audio runs through meeAgent. Build against the realtime socket above, never against transport.