# API conventions and reference

All control-plane paths are under `/v1`. The API origin is configured by
the operator (local default `http://localhost:4000`); production domains
are announced by your operator.

- Requests and responses are JSON; use `Content-Type: application/json`.
- Objects are returned directly. Lists use `{data: [...], next_cursor: null|"evt_…"}`.
- Typed IDs: `org_`, `proj_`, `agent_`, `grant_`, `line_`, `num_`, `nres_`,
  `port_`, `call_`, `xfer_`, `msg_`, `rec_`, `trn_`, `apr_`, `evt_`, `led_`.
  Pass the returned public ID, not a raw UUID or phone number where an ID
  is expected.
- E.164 numbers include `+`; URL-encode them in query parameters (`%2B`).
- Timestamps are ISO 8601. Budget inputs are integer cents; cost outputs
  are decimal strings of integer micros. `$1 = 1000000` micros,
  `1 cent = 10000`.
- A resource can be operationally terminal while its cost is still
  `pending` — carrier evidence, not the HTTP response, closes accounting.
- [Idempotency and errors](errors.md) apply to every side-effecting
  request.

## Discover the complete contract

`GET /v1/openapi.json` includes operation paths, auth schemes, request
bodies, response objects, enums, query parameters, billing units and error
recovery guidance.

| Surface | Main operations |
|---|---|
| Human/account | `/auth/signup`, `/auth/verify-email`, `/auth/login`, `/auth/me`, `/orgs`, projects/keys/members |
| Pairing | `/oauth/device/authorize`, `/oauth/token`, human approve/deny |
| Authority | `/agents`, agent grants, grant Lines/credentials, revoke/withdraw |
| Policies | `/policies`, immutable versions, `/policies/check` |
| Numbers | `/available-numbers`, `/numbers/reserve`, `/numbers`, `/lines` |
| Voice | `/calls`, answer/hangup/transfer/DTMF, recording start/stop, transcripts/outcomes |
| Messaging | `/messages`; `/orgs/{org}/messaging` quote/brand/campaign/OTP |
| Ports | `/ports`, details, documents, requirements, confirm/cancel |
| Audit | `/usage`, `/usage/ledger`, `/usage/adjustments`, `/events`, `/audit` |
| Delivery | `/webhook-endpoints`, delivery replay; signed provider ingress |

Account, grant, port and registration endpoints require the appropriate
human or key authority; a broad phone capability does not unlock them. See
[authentication](authentication.md).