API configuration

The SunoVoice AI API lets you do from your own code almost everything you can do in the dashboard — manage agents, list calls and pull transcripts, place outbound calls, and manage phone numbers. This page is the complete reference for setting it up.

Base URL

All API requests go to:

https://api.sunovoice.com/api/v1

Requests and responses are JSON. Send Content-Type: application/json on requests that have a body (POST, PATCH).

Creating an API key

API keys are managed by an owner or admin of your organization.

1. In the dashboard, open the API keys tab.
2. Click New key and give it a recognizable name (e.g. "Zapier" or "Internal CRM").
3. Copy the key immediately. The full secret is shown only once, at creation. It begins with sk_live_.
4. Store it somewhere secure (see security best practices below).

We store only a one-way hash of your key plus a short visible prefix — so we can show you which key is which, but we can never reveal the full secret again. If you lose it, revoke it and create a new one.

Authentication

Authenticate every request with your key as a Bearer token in the Authorization header:

curl https://api.sunovoice.com/api/v1/agents \
  -H "Authorization: Bearer sk_live_your_key_here"

The key identifies your organization automatically — you don't need to send any other identifier. A request with a missing, invalid, revoked, or expired key is rejected with a 401 error.

Core endpoints

Agents

Calls

Phone numbers

Knowledge base

Use PUT /knowledge/external/{external_id} to keep the agent's knowledge in sync with your own systems. Pick a stable id for each piece of content (e.g. faq-refunds, product-1023) and send it whenever that content changes — re-sending the same id replaces the source in place, so your knowledge base never fills with duplicates. The content is automatically re-chunked and re-embedded for retrieval during calls.

More

Example requests

List your agents

curl https://api.sunovoice.com/api/v1/agents \
  -H "Authorization: Bearer sk_live_your_key_here"

Get a call with its transcript

curl https://api.sunovoice.com/api/v1/calls/CALL_ID \
  -H "Authorization: Bearer sk_live_your_key_here"

Place an outbound call

curl -X POST https://api.sunovoice.com/api/v1/calls/outbound \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "AGENT_ID",
    "to_number": "+14155550142",
    "objective": "Remind the customer about tomorrow at 10am and offer to reschedule."
  }'

Sync a knowledge source

Create or update the source keyed faq-refunds. Run it again whenever the content changes — it updates in place instead of creating a duplicate:

curl -X PUT https://api.sunovoice.com/api/v1/knowledge/external/faq-refunds \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "text",
    "title": "Refund policy",
    "content": "Refunds are available within 30 days of purchase. Contact support@example.com."
  }'

To sync from a web page instead of raw text, send {"kind": "url", "url": "https://example.com/help/refunds"}. To remove it later, DELETE /knowledge/external/faq-refunds.

The fields for creating and updating agents mirror the agent form in the dashboard — see Creating an agent. The most reliable way to learn a resource's exact shape is to GET an existing one and match its fields.

Responses and errors

Successful responses return JSON with standard status codes (200 for reads, 201 for creates, 204 for deletes). Errors return a JSON body with a human-readable message:

{ "detail": "Invalid or revoked API key." }

Common status codes:

Revoking and rotating keys

• Revoke a key any time from the API keys tab. Revocation takes effect immediately — the key stops working on its next request.
• Rotate safely by creating a new key, updating your integration to use it, confirming everything works, and only then revoking the old key. This avoids downtime.

Security best practices

• Treat keys like passwords. Anyone with a key can act on your organization with owner/admin-level access.
• Never commit a key to source control, embed it in a website, mobile app, or any frontend code, or paste it into a shared document. Keys are for server-side use only.
• Store keys in environment variables or a secret manager, not in code.
• Use a separate key per integration so you can revoke one without breaking the others.
• Revoke keys you no longer use, and rotate periodically.
• If a key may be exposed, revoke it immediately and issue a new one.

Rate limits & fair use

The API is intended for normal automation. Build in sensible retries and back off on errors. If you're planning high-volume usage, contact us so we can make sure your account is set up for it.

Frequently asked questions

I lost my key — can you resend it? No. We only store a hash, so the full secret can't be recovered. Revoke the lost key and create a new one.

Do keys expire? A key stays valid until you revoke it (or until an expiry date, if one was set). Revoking is immediate.

Can a key access all my data? Yes — a key acts as your organization, so protect it accordingly and scope your integrations carefully.

Next step

Get real-time event notifications with Webhooks.