API Reference

A REST API that speaks production.

Every endpoint Saaya exposes, agents, knowledge bases, sessions, campaigns, phone numbers, widgets. One envelope, one auth header, page-based lists.

Base URL

https://api.saaya.ai

Auth

API key in the X-API-Key header.

Org context

Resolved from the key. No extra header needed.

Request · create an agent
curl https://api.saaya.ai/api/v1/agents/ \
  -H "X-API-Key: $SAAYA_API_KEY" \
  -H "Content-Type: application/json"
response envelope
{
  "success": true,
  "message": "Agents retrieved successfully",
  "data": [ /* … */ ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 50,
    "totalPages": 1
  }
}
Resources

Eight resources. One consistent shape.

/api/v1/agents

Agents

Create agents, edit the draft, publish it, and restore an earlier version.

  • POST /api/v1/agents/
  • GET /api/v1/agents/:id
  • PATCH /api/v1/agents/:id
  • POST /api/v1/agents/:id/publish
  • GET /api/v1/agents/:id/versions
  • POST /api/v1/agents/:id/versions/:versionId/restore
/api/v1/knowledge-bases

Knowledge Bases

Create a corpus, add and remove sources, trigger a re-sync.

  • POST /api/v1/knowledge-bases/
  • GET /api/v1/knowledge-bases/:id
  • POST /api/v1/knowledge-bases/:id/sources
  • POST /api/v1/knowledge-bases/:id/sync
  • DELETE /api/v1/knowledge-bases/:id
/api/v1/sessions

Sessions

Read back conversations, fetch recordings, and pull period stats.

  • GET /api/v1/sessions
  • GET /api/v1/sessions/:id
  • GET /api/v1/sessions/:id/recording
  • GET /api/v1/sessions/stats
/api/v1/campaigns

Campaigns

Upload an audience, publish, and drive the campaign lifecycle.

  • POST /api/v1/campaigns
  • POST /api/v1/campaigns/:id/leads/upload
  • POST /api/v1/campaigns/:id/publish
  • POST /api/v1/campaigns/:id/start
  • POST /api/v1/campaigns/:id/pause
  • POST /api/v1/campaigns/:id/resume
/api/v1/phone-numbers

Phone Numbers

List the numbers available to you and place an outbound call.

  • GET /api/v1/phone-numbers
  • POST /api/v1/phone-numbers/call
/api/v1/organizations

Organization & Roles

Org settings, members, and the permission-to-role matrix.

  • GET /api/v1/roles
  • GET /api/v1/roles/permissions
  • GET /api/v1/roles/matrix
  • POST /api/v1/roles
/api/v1/widgets

Widgets

Wrap a published agent for embedding on your own pages.

  • POST /api/v1/widgets
  • GET /api/v1/widgets
  • PATCH /api/v1/widgets/:id
  • DELETE /api/v1/widgets/:id
/api/v1/api-keys

API Keys

Issue and revoke keys. Requires a signed-in dashboard session.

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

Resilience built into the wire.

One envelope

Every response carries success, message, and data. Failures keep the same shape.

Page-based pagination

Pass page and limit. List responses return meta with the totals.

Rate-limit headers

Rate-limited routes return the standard X-RateLimit-* headers, and a 429 adds Retry-After.

API FAQ

Common questions

  • Settings → API Keys in the dashboard. A key belongs to one organization, and the full value is shown once at creation. Key management itself is not reachable with an API key, it needs a signed-in session, so a leaked key cannot mint a replacement.

Ready to ship

Build against a stable API.

Generate a key from the dashboard, set one header, and the first call returns an agent. The envelope is the same on every endpoint.

Get an API keyRead the Quickstart

No credit card · 15-min setup · Cancel anytime