REST API overview

Everything the Comcent web app does goes through a JSON REST API, which you can also call from your own systems. This page summarises the API as it exists in the open source server (server/lib/comcent_web/router.ex).

Base URL

The API is served from the same hostname as the web app:

https://<COMCENT_DOMAIN>/api/v2

Most resources belong to an organisation and include the organisation’s subdomain in the path:

https://<COMCENT_DOMAIN>/api/v2/<subdomain>/<resource>

For example, GET https://voice.example.com/api/v2/acme/queues lists the queues of the acme organisation.

Conventions

Requests and responses are JSON. Send Content-Type: application/json with request bodies.
Parameter names may be sent in camelCase or snake_case; the server accepts both.
Errors return an HTTP error status with a JSON body such as {"error": "Unauthorized"}.
GET /health returns the server’s health and needs no authentication.

Authentication

API requests are authenticated with a session token, sent as a bearer token:

curl https://voice.example.com/api/v2/acme/queues \
  -H "Authorization: Bearer <session_token>"

Get a session token by signing in with email and password:

curl -X POST https://voice.example.com/api/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "…"}'

The response contains token and user. Session tokens are valid for 30 days, and are invalidated early if the user resets their password. See Authentication for more, including API keys.

Access levels

Level	Who can call it
Public	Anyone (sign-in, registration, password reset)
Signed-in user	Any valid session token
Organisation member	A member of the organisation in the path
Organisation admin	A member with the `ADMIN` role in that organisation

A request for an organisation you do not belong to returns 404 with not_org_member; a request that needs a higher role returns 403 with insufficient_role.

Resource groups

Authentication and account — `/api/v2/auth`, `/api/v2/user`

Endpoints	Access	Purpose
`auth/login`, `auth/register`, `auth/verify-email`, `auth/resend-verification`, `auth/forgot-password`, `auth/reset-password`	Public	Password sign-in and account recovery
`auth/config`, `auth/oauth/:provider/start`, `auth/oauth/:provider/callback`	Public	Sign-in options and single sign-on
`auth/claim-setup`	Public	Claim a new instance with the setup token
`user/session`, `user/orgs`, `user/invitations/:id`, `user/accept-terms`	Signed-in user	Current session, list or create organisations, accept invitations

Organisation member — `/api/v2/<subdomain>/…`

Endpoints	Purpose
`me/access`, `me/context`	The current member’s permissions and app context
`me/api-keys`	Create and delete the member’s own API keys
`members`, `members/presence`, `members/default-number`	List members, read and set presence, choose a default outbound number
`dashboard/aggregate-presence`, `calls/live`	Presence counts and calls in progress
`promises`, `promises/close`, `promises/:id/assign`	Promises detected in calls: list, close and assign

Organisation admin — `/api/v2/<subdomain>/…`

Endpoints	Purpose
`sip-trunks`	Create, list, update and delete SIP trunks
`numbers`, `numbers/:id/set-default`	Manage phone numbers and their inbound flows; set the default number
`queues`, `queues/:id/state`, `queues/:id/members`	Manage queues, read live queue state, add and remove queue members
`voice-bots`	Create, read, update and delete voice bots
`call-stories`, `call-story/:id`, `…/transcript`, `…/summary`, `…/sentiment`	Call history and each call’s transcript, summary and sentiment
`call-story/:id/record/:file_name`, `playback/:file_name`	Download recordings and uploaded audio
`uploads/get-signed-url`, `uploads`	Upload and delete audio files
`daily-summaries`, `daily-summaries/sentiment-counts`	Daily summaries and sentiment totals
`settings/ai-analysis`	Read and update the organisation’s AI analysis settings
`settings/api-keys`	Organisation API keys
`settings/webhooks`	Webhooks (see Webhooks)
`admin/members`, `admin/members/:id/role`, `admin/members/:id/regenerate-password`, `members/invite`	Manage members, roles and invitations

Real-time updates

The web app receives live updates over a Phoenix WebSocket at wss://<COMCENT_DOMAIN>/ws, connecting with the token (a session token) and subdomain parameters. It exposes the channels presence:<subdomain>, live_calls:<subdomain>, queue_dashboard:<subdomain>:<queue_id> and compliance:<subdomain>.