API reference

Base URL

Environment	URL
Production	`https://api.powsoo.com`
Staging	`https://api-staging.powsoo.com`

Authentication

Powsoo uses two complementary mechanisms — no bearer tokens in the embed snippet itself.

Origin allowlist — on POST /v1/voice-tokens and GET /v1/embed/:widgetId/config, the API validates the Origin request header against the widget’s allowed origins list. A mismatch returns 404 before any credentials are accessed. This is the primary access gate.

Session token — after minting a token, the API returns a sessionToken (sst_*). This authenticates the per-call SSE stream and result POST. Pass it via:

Header: x-powsoo-session-token: sst_...
Query param: ?token=sst_... (useful for EventSource which doesn’t support custom headers)

Common request headers

Header	Description
`Content-Type: application/json`	Required for POST requests with a body.
`x-powsoo-session-token`	Session token for per-call endpoints.
`x-request-id`	Optional client-supplied request ID for tracing. Echoed in the response.

Error format

All errors return JSON:

{
  "code": "widget_unavailable",
  "message": "Widget not found, origin not allowed, or voice platform not configured."
}

Error codes

Code	HTTP	Description
`widget_unavailable`	404	Catch-all — check API logs for the specific sub-reason.
`origin_not_allowed`	404	`Origin` header not in the widget’s allowed origins list.
`widget_not_found`	404	`widget-id` does not exist.
`voice_platform_not_connected`	404	No voice platform account connected to this widget.
`retell_agent_not_configured`	404	Widget has no Retell agent selected.
`decryption_failed`	404	API key decryption failed (key/secret mismatch).
`retell_auth_failed`	502	Retell rejected the decrypted API key.
`plan_limit_exceeded`	402	Monthly call cap reached.
`invalid_session_token`	401	Missing or invalid `x-powsoo-session-token`.
`session_not_found`	404	`callId` has no active session.

Endpoints

The full endpoint reference — including request/response schemas, code snippets, and error details — is auto-generated from the OpenAPI spec. Browse it in the Endpoints sidebar group below this page, or open the interactive Swagger UI:

Swagger UI: https://api.powsoo.com/docs
Raw spec: https://api.powsoo.com/openapi.json