# API overview

> Base URL, authentication, versioning and deprecation, idempotency, pagination, errors and limits of the public v1 REST API.

Source: https://docs.nexafone.so/v1/api/

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](/v1/api/console/)**: try every operation in the browser.
- **[OpenAPI 3.1 spec](/v1/api/openapi.json)**: for code generators, Postman or agents.
- Reference by area:

| Area | Operations |
| --- | --- |
| [SDK sessions](/v1/api/sdk/) | 3 |
| [Inbox](/v1/api/inbox/) | 5 |
| [Members](/v1/api/members/) | 1 |
| [Teams](/v1/api/teams/) | 2 |
| [Templates](/v1/api/templates/) | 7 |
| [Recordings](/v1/api/recordings/) | 2 |
| [Webhook endpoints](/v1/api/webhook-endpoints/) | 10 |
| [Commerce](/v1/api/commerce/) | 22 |
| [Store payments](/v1/api/payments/) | 5 |
| [Partner API](/v1/api/partner/) | 18 |

## Base URL and authentication

```text
https://api.nexafone.so/api/v1/…
```

Send a credential as a bearer token:

```bash
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](/v1/server/user-tokens/) | The member’s workspace (or stores), within the signing key’s scopes |
| Partner secret key `psk_…` | The partner’s server | The [Partner API](/v1/partners/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

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

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

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

Errors are [Problem Details](/v1/errors/) with a stable `code`. Requests are [rate limited](/v1/rate-limits/) per IP
address, user and key. Every response carries `X-Request-Id`; quote it when you contact support.