API Documentation

Everything you need to build empathic voice agents with RealSpeak.

Authentication

All API requests require a Bearer token. Generate API keys from the dashboard.

Authorization: Bearer rs_live_...

Create an Agent

POST /api/v1/agents
{
  "name": "Support Agent",
  "systemPrompt": "You are a helpful support agent...",
  "voiceName": "ITO",
  "webhookUrl": "https://yourapp.com/webhook",
  "webhookSecret": "whsec_your_secret",
  "tools": [{
    "name": "lookup_order",
    "description": "Look up order by ID",
    "parameters": {
      "type": "object",
      "properties": {
        "orderId": { "type": "string" }
      },
      "required": ["orderId"]
    }
  }]
}

Webhook Events

RealSpeak sends HMAC-SHA256 signed webhooks to your endpoint. Verify using the X-RealSpeak-Signature header.

call.started

Sent when a new call connects. Return agent config.

tool_call

Sent when the agent invokes a tool. Return the result as a string.

{
  "event": "tool_call",
  "callId": "call_abc123",
  "toolCallId": "tc_xyz",
  "name": "lookup_order",
  "parameters": { "orderId": "ORD-456" }
}

// Your response:
{ "result": "Order ORD-456 shipped yesterday, tracking: 1Z999..." }

prosody.update

Real-time emotion data from Hume EVI (48 dimensions per utterance).

call.ended

Sent when the call ends. Includes transcript, summary, prosody timeline.

Call History

GET /api/v1/calls?limit=50&offset=0

Usage

GET /api/v1/usage