API Reference

A REST API that speaks production.

Every endpoint Saaya exposes — agents, knowledge bases, sessions, campaigns, webhooks. Cursor-paginated, idempotent, and shape-stable.

Open the live spec

Base URL

https://api.saaya.ai

Auth

Bearer token in the Authorization header.

Org context

Pass X-Organization-Id to scope the call.

cURL · create an agent
curl https://api.saaya.ai/api/v1/agents \
  -H "Authorization: Bearer $SAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maya — Pipeline Concierge",
    "prompt": "You qualify inbound interest...",
    "voice": { "provider": "elevenlabs", "voiceId": "rachel" },
    "llm":   { "provider": "anthropic", "model": "claude-opus-4-7" }
  }'
response envelope
{
  "success": true,
  "data": {
    "id": "agt_2N3rH...",
    "name": "Maya — Pipeline Concierge",
    "version": "v1"
  },
  "message": null,
  "meta": null
}
Resources

Eight resources. One consistent shape.

/api/v1/agents

Agents

Create, version, publish, and roll back conversational agents.

  • POST /api/v1/agents
  • GET /api/v1/agents/:id
  • PATCH /api/v1/agents/:id
  • POST /api/v1/agents/:id/publish
  • POST /api/v1/agents/:id/rollback
/api/v1/knowledge-bases

Knowledge Bases

Ingest sources, query with citations, manage embeddings.

  • POST /api/v1/knowledge-bases
  • POST /api/v1/knowledge-bases/:id/ingest
  • POST /api/v1/knowledge-bases/:id/query
  • DELETE /api/v1/knowledge-bases/:id
/api/v1/sessions

Sessions

Place test calls, fetch transcripts, replay tool calls.

  • POST /api/v1/sessions
  • GET /api/v1/sessions/:id
  • GET /api/v1/sessions/:id/transcript
  • GET /api/v1/sessions/:id/replay
/api/v1/campaigns

Campaigns

Bulk dispatch, scheduling, fallback channel cascades.

  • POST /api/v1/campaigns
  • POST /api/v1/campaigns/:id/start
  • POST /api/v1/campaigns/:id/pause
  • GET /api/v1/campaigns/:id/stats
/api/v1/leads

Audience / Leads

Manage the contact list each campaign fans out across.

  • POST /api/v1/leads
  • POST /api/v1/leads/bulk
  • GET /api/v1/leads/:id
  • PATCH /api/v1/leads/:id
/api/v1/webhooks

Webhooks

Subscribe to session, campaign, and agent lifecycle events.

  • POST /api/v1/webhooks
  • GET /api/v1/webhooks
  • DELETE /api/v1/webhooks/:id
  • POST /api/v1/webhooks/:id/rotate-secret
/api/v1/workspaces

Workspace & Members

Org settings, RBAC, member invites, billing scope.

  • GET /api/v1/workspaces/me
  • POST /api/v1/workspaces/:id/invite
  • PATCH /api/v1/workspaces/:id/members/:memberId
/api/v1/api-keys

API Keys

Issue, scope, and rotate keys. Tied to RBAC roles.

  • POST /api/v1/api-keys
  • GET /api/v1/api-keys
  • DELETE /api/v1/api-keys/:id
Production-ready by default

Resilience built into the wire.

Idempotency keys

Pass Idempotency-Key on any create to make retries safe. Saaya replays the response byte-for-byte for 24 hours.

Cursor pagination

List endpoints return meta.next_cursor. Stable across writes — you'll never lose or duplicate a row.

Versioning strategy

Major version is locked into the URL path. Additive changes ship inside the version. Breaking changes get 12 months of overlap.

Webhooks

Saaya tells you when things happen.

Events Saaya emits

  • session.started
  • session.ended
  • session.transferred
  • agent.published
  • agent.rolled_back
  • campaign.started
  • campaign.completed
  • lead.responded
  • kb.ingest.completed

Signature & retries

Every payload is signed with HMAC-SHA256 using your webhook secret. Saaya retries non-2xx responses with exponential backoff for up to 24 hours, then dead-letters.

Full event reference
API FAQ

Common questions

Ready to ship

Build against a stable API.

Generate a key, install the SDK, and the first POST returns an agent ID. The contract holds.

Get an API keyRead the Quickstart

No credit card · 15-min setup · Cancel anytime