API overview
The public API is the stable v1 surface: every operation tagged public in api/openapi.public.yaml, generated
from the backend’s own operation definitions, so this reference always matches what the server runs.
- API console: try every operation in the browser.
- OpenAPI 3.1 spec: for code generators, Postman or agents.
- Reference by area:
| Area | Operations |
|---|---|
| SDK sessions | 3 |
| Inbox | 5 |
| Members | 1 |
| Teams | 2 |
| Templates | 7 |
| Recordings | 2 |
| Webhook endpoints | 10 |
| Commerce | 22 |
| Store payments | 5 |
| Partner API | 18 |
Base URL and authentication
Section titled “Base URL and authentication”https://api.nexafone.so/api/v1/…Send a credential as a bearer token:
curl "https://api.nexafone.so/api/v1/workspaces/$WORKSPACE_ID/teams" \ -H "Authorization: Bearer $NEXAFON_SECRET_KEY"| Credential | From | Reaches |
|---|---|---|
Secret key sk_live_…/sk_test_… |
Your server | Its own workspace, with its scopes |
SDK session sdk_… |
The SDK, after a user token | The member’s workspace (or stores), within the signing key’s scopes |
Partner secret key psk_… |
The partner’s server | The Partner API and the partner’s own stores |
The {workspaceId} in a path only selects among what the credential may reach; anything else answers 404, as does
an id from another workspace. Requests and responses are JSON (application/json); errors are
application/problem+json.
Versioning and deprecation
Section titled “Versioning and deprecation”Public responses carry API-Version: v1. Within v1, changes are additive: new operations, new optional fields, new
enum values and new event types. Write clients that ignore fields they do not know.
An operation that will go away is first deprecated: it keeps working for at least 180 days, is marked in the
reference, and its responses carry Deprecation (RFC 9745) and Sunset (RFC 8594) headers with the dates. Breaking
changes come only in a new version, documented here side by side.
Idempotency
Section titled “Idempotency”Operations that create things accept an Idempotency-Key header (1 to 255 visible ASCII characters, such as a UUID).
Retrying the same request with the same key within 24 hours returns the stored response with
Idempotent-Replayed: true instead of doing the work twice. The same key with a different body answers
idempotency_key_reused; a retry while the first is still running answers idempotency_in_flight. A 5xx releases
the key so the retry runs again. Responses that show a secret once (a new webhook secret, an SDK session) never
replay it.
Pagination
Section titled “Pagination”List operations take limit and return a next cursor when there are more; pass it as cursor to get the next page.
Errors and limits
Section titled “Errors and limits”Errors are Problem Details with a stable code. Requests are rate limited per IP
address, user and key. Every response carries X-Request-Id; quote it when you contact support.