Complete reference of the Agoralia REST API — every /api/v1 endpoint, its HTTP method, the scope it requires, and what it does, grouped by resource.

API Endpoints

Base URL: https://api.agoralia.app/api/v1. Authenticate every request with the X-API-Key: ag_… header. Each endpoint requires the API key to hold a specific scope — a request missing the scope returns 403.

For error bodies, rate limits, and idempotency, see Errors & Rate Limits.

Conventions

List endpoints use cursor pagination. Pass cursor and limit; responses are { "data": [...], "has_more": bool, "next_cursor": string | null }.
Write endpoints that create or place something accept an Idempotency-Key header.
Phone numbers are E.164 (+15551234567).

Workspace

Method	Path	Scope	Description
`GET`	`/me`	`me:read`	Workspace info, billing plan/limits, and the calling key's scopes.

Agents

Method	Path	Scope	Description
`GET`	`/agents`	`agents:read`	List voice agents (cursor paginated; optional `is_active` filter).
`GET`	`/agents/{agent_id}`	`agents:read`	Get a single agent's full configuration.
`POST`	`/agents`	`agents:write`	Create a voice agent. Supports `Idempotency-Key`. Returns `201`.
`PATCH`	`/agents/{agent_id}`	`agents:write`	Update an agent's fields.
`POST`	`/agents/{agent_id}/publish`	`agents:write`	Sync (publish) the agent to the voice provider so it can place calls. Required before `POST /calls`.
`DELETE`	`/agents/{agent_id}`	`agents:write`	Soft-delete the agent (`is_active = false`). Returns `204`.

Campaigns

Method	Path	Scope	Description
`GET`	`/campaigns`	`campaigns:read`	List campaigns (cursor paginated; optional `status` filter).
`GET`	`/campaigns/{campaign_id}`	`campaigns:read`	Get campaign details, settings, and stats.
`POST`	`/campaigns`	`campaigns:write`	Create a campaign (starts as `draft`). Supports `Idempotency-Key`. Returns `201`.
`PATCH`	`/campaigns/{campaign_id}`	`campaigns:write`	Update a campaign. Allowed only while `draft` or `paused`.
`DELETE`	`/campaigns/{campaign_id}`	`campaigns:write`	Cancel a campaign (soft delete). A `running` campaign must be paused first. Returns `204`.
`POST`	`/campaigns/{campaign_id}/start`	`campaigns:start`	Start a `draft`/`paused` campaign. Runs the launch pre-flight readiness check; returns `422 campaign_not_ready` with the missing requirements if it isn't ready.
`POST`	`/campaigns/{campaign_id}/pause`	`campaigns:start`	Pause a `running` campaign.
`GET`	`/campaigns/{campaign_id}/results`	`results:read`	Call results for the campaign with outcome, summary, analysis, and transcript (cursor paginated).

Leads

Leads live under their campaign.

Method	Path	Scope	Description
`GET`	`/campaigns/{campaign_id}/leads`	`leads:read`	List leads in a campaign (cursor paginated; optional `status` filter).
`POST`	`/campaigns/{campaign_id}/leads`	`leads:write`	Add/upsert leads in batch (1–10000). Supports `Idempotency-Key`. Returns `201` with `{ imported, errors, total }`.
`DELETE`	`/campaigns/{campaign_id}/leads/{lead_id}`	`leads:write`	Delete a lead from the campaign. Returns `204`.

Calls

Method	Path	Scope	Description
`GET`	`/calls`	`calls:read`	List calls (cursor paginated; optional `campaign_id` and `status` filters).
`GET`	`/calls/{call_id}`	`calls:read`	Get full call detail: transcript, summary, analysis, structured data, recording URL.
`POST`	`/calls`	`calls:write`	Place a single outbound call (agent must be published; the destination is DNC-checked). Supports `Idempotency-Key`. Returns `202`.

Phone numbers

Method	Path	Scope	Description
`GET`	`/phone-numbers`	`numbers:read`	List active phone numbers (cursor paginated).
`GET`	`/phone-numbers/{number_id}`	`numbers:read`	Get phone number details.
`POST`	`/phone-numbers/link`	`numbers:write`	Link a BYO (bring-your-own) number from `telnyx`, `twilio`, `vonage`, `sinch`, `bird`, `infobip`, `bandwidth`, or `sip`. Supports `Idempotency-Key`. Returns `201`.
`PUT`	`/phone-numbers/{number_id}/inbound`	`numbers:write`	Enable/disable inbound on a number; set a default inbound agent and/or external assistant-request server URL. Returns the signing secret only when generated.
`DELETE`	`/phone-numbers/{number_id}`	`numbers:write`	Release (soft-delete) a phone number. Returns `204`.

Integrations (BYO carriers)

Method	Path	Scope	Description
`POST`	`/integrations/connect`	`numbers:write`	Connect a BYO carrier's API credentials (`telnyx`, `twilio`, `vonage`, `sinch`, `bird`, `infobip`, `bandwidth`). Verified against the provider, stored encrypted. Pass `external_owner_id` to isolate credentials per end-customer in a shared workspace. Returns `sms_ready` / `sms_missing`. Returns `201`.

Billing

Method	Path	Scope	Description
`GET`	`/billing/usage`	`billing:read`	Workspace usage: plan, included/used/remaining minutes, and limits.

Compliance / DNC

Method	Path	Scope	Description
`GET`	`/dnc`	`compliance:read`	List do-not-call entries (cursor paginated).
`GET`	`/dnc/check`	`compliance:read`	Check whether a `phone_number` (query param) is on the DNC list.
`POST`	`/dnc`	`compliance:write`	Add a phone number to the DNC list. Returns `201`.
`DELETE`	`/dnc/{phone_number}`	`compliance:write`	Remove a phone number from the DNC list. Returns `204`.

SMS

Method	Path	Scope	Description
`POST`	`/sms`	`sms:write`	Send a single outbound SMS from a workspace number. The sending provider (Telnyx, Twilio, Vonage, Sinch, Bird, Infobip, Bandwidth) is resolved from the number. Supports `Idempotency-Key`. Returns `202`.

See Messaging for provider coverage and the MCP tools.

Webhooks

Configure where Agoralia sends event notifications. See Webhooks for the payload and signature details.

Method	Path	Scope	Description
`GET`	`/webhooks`	`webhooks:read`	Read the current event-webhook configuration (the secret is never returned).
`PUT`	`/webhooks`	`webhooks:write`	Set the webhook URL, subscribed events, and/or rotate the signing secret. The secret is returned only when generated.

API Endpoints

On this page