Routes

Every route the Ostra API and the MCP server serve, in one fixed form: the credential it takes, the scopes or role it needs, its Idempotency-Key, what it answers and its notable refusals. This list is read from the server’s own route table when these pages are built, so a route cannot be missing from it or listed here without existing.

Paths are under the base URL. Refusals link to the error codes; any route can also answer 400 invalid_request, 401 unauthenticated, 403 forbidden or insufficient_scope, 429 rate_limited and 500 internal_error, and a line or item you may not see is always 404 not_found. An answer written {a, b} is an object with those fields; a name, such as Line, is that object itself, as GET /v1/lines/{line_id} gives it.

Lines

Your lines and the sandbox line: status, addresses, proxy endpoints and credentials, a new carrier IP, the connection record and usage.

• GET /v1/lines
• GET /v1/lines/{line_id}
• GET /v1/lines/{line_id}/ip
• POST /v1/lines/{line_id}/new-carrier-ip
• GET /v1/lines/{line_id}/new-carrier-ip/{job_id}
• GET /v1/lines/{line_id}/proxy
• POST /v1/lines/{line_id}/proxy-credentials
• DELETE /v1/lines/{line_id}/proxy-credentials/{credential_id}
• GET /v1/lines/{line_id}/sources
• PUT /v1/lines/{line_id}/sources
• GET /v1/lines/{line_id}/attestations
• POST /v1/lines/{line_id}/attestations
• GET /v1/lines/{line_id}/connections
• GET /v1/lines/{line_id}/connections/export
• GET /v1/lines/{line_id}/report
• GET /v1/usage

Orders

Order lines for your organization. Available lines are assigned at once; the rest wait in a first-come queue, and nothing is charged until a line is assigned. A signed-in session also needs the admin role to order.

• GET /v1/orders
• GET /v1/orders/renewal-terms
• POST /v1/orders/renewal-terms
• POST /v1/orders
• GET /v1/orders/{order_id}
• POST /v1/orders/{order_id}/cancel
• POST /v1/orders/{order_id}/resume

Texts and calls

What reaches a line's number. A list never carries a body unless you ask for content, and every body or code returned is written to Ostra's audit log.

• GET /v1/lines/{line_id}/messages
• GET /v1/lines/{line_id}/messages/wait
• GET /v1/lines/{line_id}/messages/{message_id}
• POST /v1/lines/{line_id}/simulate/message
• GET /v1/lines/{line_id}/calls
• GET /v1/lines/{line_id}/calls/{call_id}
• GET /v1/labels
• PUT /v1/labels/{number}
• DELETE /v1/labels/{number}

Webhooks

Endpoints that receive signed events for every line your organization holds.

• GET /v1/webhooks
• POST /v1/webhooks
• GET /v1/webhooks/{endpoint_id}
• PATCH /v1/webhooks/{endpoint_id}
• DELETE /v1/webhooks/{endpoint_id}
• POST /v1/webhooks/{endpoint_id}/secret
• POST /v1/webhooks/{endpoint_id}/test
• GET /v1/webhooks/{endpoint_id}/deliveries
• POST /v1/webhooks/{endpoint_id}/deliveries/{delivery_id}/retry

App devices

The Ostra apps register each device here and read its tunnel settings. Your own code rarely needs these.

• POST /v1/devices
• GET /v1/devices
• GET /v1/devices/{device_id}
• DELETE /v1/devices/{device_id}
• GET /v1/devices/{device_id}/tunnel-config
• PUT /v1/devices/{device_id}/push
• GET /v1/devices/{device_id}/push
• DELETE /v1/devices/{device_id}/push
• POST /v1/voice/token
• DELETE /v1/voice/registration

Organization and members

Managed from the dashboard with a signed-in session. API keys and OAuth tokens cannot call these, except GET /v1/org.

• GET /v1/orgs
• POST /v1/orgs
• GET /v1/org
• PATCH /v1/org
• GET /v1/org/members
• POST /v1/org/members
• PATCH /v1/org/members/{user_id}
• DELETE /v1/org/members/{user_id}
• GET /v1/invitations
• POST /v1/invitations/{org_id}/accept
• POST /v1/invitations/{org_id}/decline

Verification and policy

Signing up: the details, the mobile number proved by a texted code, and the automatic check (the sanctions screen, and where the request comes from); acceptance of the acceptable use policy.

• GET /v1/signup/turnstile
• GET /v1/aup
• GET /v1/org/verification
• PUT /v1/org/verification
• POST /v1/org/verification/submit
• GET /v1/org/verification/phone
• POST /v1/org/verification/phone
• POST /v1/org/verification/phone/check
• POST /v1/org/aup

API keys

Made and revoked by an admin from a signed-in session. A key can never create or see another key.

• GET /v1/keys
• POST /v1/keys
• DELETE /v1/keys/{key_id}

Billing

A signed-in session only. Checkout and the card portal are Stripe's own pages.

• GET /v1/billing
• POST /v1/lines/{line_id}/cancel
• POST /v1/billing/checkout
• POST /v1/billing/portal

Sign-in

Passwordless sign-in for the dashboard: a 6-digit code by email (with a link that asks before it signs in), then a session cookie.

• GET /v1/auth/access
• POST /v1/auth/access
• POST /v1/auth/sign-in
• POST /v1/auth/sign-in/code
• POST /v1/auth/sign-in/check
• POST /v1/auth/sign-in/verify
• GET /v1/auth/session
• POST /v1/auth/sign-out
• POST /v1/auth/two-step
• POST /v1/auth/two-step/enroll
• POST /v1/auth/two-step/enroll/confirm
• GET /v1/auth/two-step
• POST /v1/auth/two-step/setup
• POST /v1/auth/two-step/setup/confirm
• POST /v1/auth/two-step/backup-codes
• POST /v1/auth/two-step/disable

OAuth

Authorization code with PKCE for the apps, the extension and MCP clients. Clients are registered by Ostra.

• GET /.well-known/oauth-authorization-server
• GET /.well-known/oauth-protected-resource
• GET /oauth/authorize
• GET /v1/oauth/authorize
• POST /v1/oauth/authorize
• POST /oauth/token
• POST /oauth/revoke
• POST /oauth/introspect
• GET /v1/oauth/grants
• DELETE /v1/oauth/grants/{grant_id}

MCP server

Its own host and listener. One JSON-RPC message per POST.

• POST /mcp
• GET /mcp
• DELETE /mcp
• GET /.well-known/oauth-protected-resource
• GET /.well-known/oauth-protected-resource/mcp