Quickstart

Get started with Sayvy AI in under 5 minutes

1. Retrieve your API Key

Head over to your Sayvy AI Console under Settings > API Keys to generate a secret access token.

All REST requests require the Authorization header:

Authorization: Bearer sayvy_live_your_api_key_here

2. Create a Voice Agent

Use the /api/v1/agents endpoint to define a voice agent with custom system instructions and TTS voice settings:

cURL

curl -X POST https://api.sayvy.ai/api/v1/agents \
  -H "Authorization: Bearer sayvy_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Specialist",
    "system_prompt": "You are a courteous support concierge for Sayvy AI. Keep responses concise and natural.",
    "voice_id": "cartesia/sonic-english",
    "temperature": 0.4
  }'

Python

import requests

url = "https://api.sayvy.ai/api/v1/agents"
headers = {
    "Authorization": "Bearer sayvy_live_your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "name": "Customer Support Specialist",
    "system_prompt": "You are a courteous support concierge for Sayvy AI. Keep responses concise and natural.",
    "voice_id": "cartesia/sonic-english",
    "temperature": 0.4
}

response = requests.post(url, json=payload, headers=headers)
agent = response.json()
print(f"Agent Created: {agent['id']}")

Node.js

const res = await fetch("https://api.sayvy.ai/api/v1/agents", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sayvy_live_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Customer Support Specialist",
    system_prompt: "You are a courteous support concierge for Sayvy AI.",
    voice_id: "cartesia/sonic-english",
    temperature: 0.4,
  }),
});
const agent = await res.json();
console.log(`Agent Created: ${agent.id}`);

3. Dispatch an Outbound Call

Once you have your agent_id, dispatch an outbound voice call to any valid E.164 phone number:

cURL

curl -X POST https://api.sayvy.ai/api/v1/telephony/calls \
  -H "Authorization: Bearer sayvy_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "ag_98f418ab72",
    "to_number": "[phone]",
    "metadata": {
      "customer_name": "Jane Doe",
      "account_tier": "Enterprise"
    }
  }'

You can track live call state transitions (queued, ringing, in-progress, completed) by subscribing to our real-time Webhooks.