Reference

API Overview

The generated API Reference has the exact request and response shapes.

This page answers a different question: which endpoints matter for which workflow?

Typical first workflow

  1. create account or get key
  2. create line
  3. receive an inbound call or SMS
  4. inspect calls or conversations
  5. add consent for outbound calling
  6. place outbound call

Resource map

Auth

  • POST /api/v1/auth/keys
  • GET /api/v1/auth/keys

Lines

  • POST /api/v1/lines
  • GET /api/v1/lines
  • GET /api/v1/lines/{id}
  • PATCH /api/v1/lines/{id}
  • DELETE /api/v1/lines/{id}

Calls

  • POST /api/v1/calls
  • GET /api/v1/calls
  • GET /api/v1/calls/{id}
  • POST /api/v1/calls/{id}/hangup
  • POST /api/v1/calls/conversation

SMS and conversations

  • POST /api/v1/messages
  • GET /api/v1/conversations
  • GET /api/v1/conversations/{lineId}/{phoneNumber}

Compliance

  • POST /api/v1/consent
  • GET /api/v1/consent
  • DELETE /api/v1/consent
  • GET /api/v1/compliance/audit
  • GET /api/v1/compliance/events
  • POST /api/v1/disclosures
  • GET /api/v1/disclosures

Webhooks and delivery inspection

  • GET /api/v1/webhooks/deliveries
  • GET /api/v1/webhooks/stats
  • POST /api/v1/webhooks/test

Billing and settings

  • GET /api/v1/billing/balance
  • GET /api/v1/billing/transactions
POST /api/v1/billing/add-funds was removed in v0.5.2.0. Saperly is now postpaid — when your balance runs low, the saved card on file is auto-charged. Add or update a payment method at app.saperly.com/billing.
  • GET /api/v1/settings
  • PATCH /api/v1/settings
  • GET /api/v1/usage/daily
  • GET /api/v1/usage/monthly
  • GET /api/v1/voices

If you only read three endpoints

Read these first:

  • POST /api/v1/lines
  • POST /api/v1/calls
  • POST /api/v1/messages

That gives you the product shape fast.

Key request fields — POST /api/v1/lines

FieldTypeRequiredDescription
namestringYesDisplay name for the line
modestringYeshosted, webhook (alias: text), or audio
system_promptstringHosted onlyAI behavior instructions
begin_messagestringNoGreeting spoken at call start
voicestringNoElevenLabs voice ID
context_limitintegerNoMax conversation turns to keep
webhook_urlstringWebhook modeURL for webhook events
audio_handler_urlstringAudio modeWebSocket URL for audio relay
status_callback_urlstringNoURL for lifecycle events
recording_enabledbooleanNoEnable call recording
compliance_enabledbooleanNoEnable disclosure and consent checks

Pagination

Saperly uses two pagination styles depending on the endpoint:

Cursor-based pagination

Used by: transactions, conversations list, conversation messages.

Pass cursor from the previous response to fetch the next page. Response includes next_cursor and has_more.

$GET /api/v1/billing/transactions?limit=20
$GET /api/v1/billing/transactions?limit=20&cursor=2026-04-10T12:00:00Z

Offset-based pagination

Used by: calls list, webhook deliveries, compliance audit.

Pass limit and offset as query params. Response includes total.

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

Default page size varies per endpoint (typically 20 for cursor, 50 for offset). Max is usually 100.

Streaming responses

Webhook mode supports NDJSON streaming for lower latency. Instead of returning one JSON object, return newline-delimited JSON chunks. Each chunk is spoken as it arrives. See the Webhook Mode guide for details.

Raw spec and local development

  • OpenAPI spec source: fern/openapi.yaml
  • App-served spec: GET /api/openapi.yaml
  • Local docs preview: fern docs dev