API basics

The rules every route follows: where the API is, how to send a credential, the scopes, the one error shape, the limits, cursors and idempotency. Each route is on the Routes page.

Base URL and format

• The base URL is https://api.ostranetwork.com, and every route is under /v1.
• JSON in and out, with content-type: application/json. The OAuth token, revocation and introspection routes take form bodies, as OAuth does.
• Times are ISO 8601 in UTC with a Z. Ids are strings.
• The API can use your lines and order more (Orders); Ostra assigns each line, and no route texts or calls out from a line.

Credentials

• A key or token names its organization itself. Do not send Ostra-Organization with it, or send the same organization (403 forbidden otherwise).
• When an Authorization header is present the cookie is ignored. A malformed one is a failed credential, not a missing one.
• Keys, members, the verification record and billing take a session only: a key or token there is 403 forbidden. A key can never create or see another key.
• Every secret (a key, a proxy credential’s secret, a webhook signing secret) is shown once, in the answer that makes it, and never again.

Scopes

One list for keys, OAuth tokens and sessions. A key with only :read scopes cannot ask for a new carrier IP, issue a proxy credential or change a webhook; it can still send the sandbox line a simulated text. A call that lacks a scope is 403 insufficient_scope, and required_scopes names the scopes the route needs, or, when only the content scope is missing for include_content=true, that one scope.

Roles

Every member of an organization has a role. A session carries every scope above; an OAuth token carries the scopes allowed at consent, cut at every request to what the person’s role and the client allow, so a person removed from the organization takes the access they granted with them.

Errors

Every refusal has one shape, with a code to branch on and a message for people. Some codes carry more fields, named below.

{ "error": { "code": "insufficient_scope", "message": "this credential lacks lines:new_carrier_ip", "required_scopes": ["lines:new_carrier_ip"] } }

404 not_found is also the answer for a line, text or anything else that exists but is not yours, the same as for one that does not exist. A body too large or of the wrong content type answers 413 or 415 with the code invalid_request.

Rate limits and other limits

Past a rate limit the answer is 429, with retry_after_seconds in the body and a Retry-After header. Wait that long; nothing you sent was queued.

Cursors

Lists of texts and calls page with an opaque cursor. Every answer carries next_cursor; pass it back to continue, and keep it to resume later. Cursors follow the order Ostra stored the items, not the phone’s clock, so nothing that arrived late is skipped. Text cursors start s. on the sandbox line and m. on a real line, and call cursors c.; treat them as opaque all the same. A cursor is sealed, so it carries no count of anything, and one you make up or change is refused with 400 invalid_request.

Idempotency

Send Idempotency-Key (1 to 128 of A-Z a-z 0-9 . _ : -) to make a retry safe.

• Required on POST /v1/lines/{line_id}/new-carrier-ip; accepted on issuing a proxy credential, creating a webhook endpoint and registering a device. Other routes ignore it.
• Keys are kept 24 hours per organization and route. The same key with the same request returns the first answer again, with Ostra-Idempotent-Replay: true; with a different request it is 409 idempotency_conflict. While the first is still running, a second is 409 conflict.
• An answer that carried a secret comes back without it: "secret": null and "secret_withheld": true.
• The MCP server’s new_carrier_ip tool uses the same keys, so a key replays at either door.

OAuth

For an app that acts for a person. Authorization code with PKCE (S256 only), as a client Ostra registered; there is no dynamic client registration. The issuer is the API’s base URL, with metadata at /.well-known/oauth-authorization-server.

1. Send the person’s browser to /oauth/authorize with response_type=code, client_id, redirect_uri, scope (space-separated), state, code_challenge, code_challenge_method=S256 and, for the MCP server, resource=https://mcp.ostranetwork.com/mcp (the API is the default resource).
2. They sign in to the dashboard, pick the organization and allow it. The redirect carries code, state and iss; check all three.
3. Trade the code at POST /oauth/token (form-encoded) with your code_verifier. The access token lasts 60 minutes; the refresh token works once and comes back with a new one, and using an old one again revokes the whole grant.

• A redirect URI matches a registered one exactly, except a loopback one (http://127.0.0.1/..., http://localhost/... or http://[::1]/...), which matches on any port. Native apps use a reverse-domain scheme with one slash, such as com.example.app:/oauth/callback.
• A code lasts 5 minutes and works once; a second use revokes everything issued from the first.
• A token works only at its resource: one issued for the API is refused by the MCP server, and the reverse.
• The person can revoke an app in the dashboard (DELETE /v1/oauth/grants/{grant_id}); its next call is 401.