REST API

A conventional JSON REST API for building integrations and automations. Available on all plans.

• Base URL: https://api.agoralia.app/api/v1
• Auth: X-API-Key: ag_… (create in Dashboard → API Keys)
• Content type: application/json

See Authentication for the full credential model and the scopes table.

Authentication

Send your ag_ key in the X-API-Key header on every request:

curl https://api.agoralia.app/api/v1/me \
  -H "X-API-Key: ag_your_key_here"

Each endpoint requires a specific scope. A key missing it returns 403 Missing scope: <scope>.

Idempotency

Mutating requests accept an Idempotency-Key header. Replaying the same key returns the stored response without repeating the action. Reusing a key with a different body returns 409.

curl -X POST https://api.agoralia.app/api/v1/campaigns \
  -H "X-API-Key: ag_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: june-outreach-001" \
  -d '{"name":"June outreach"}'

Pagination

List endpoints use cursor pagination. Pass limit (default 20, max 100; the DNC and lead lists default to 50 and allow up to 500) and an optional cursor. The response carries has_more and next_cursor:

{
  "data": [ { "id": "…", "name": "…" } ],
  "has_more": true,
  "next_cursor": "01HZ…"
}

Pass next_cursor back as cursor to fetch the next page:

curl "https://api.agoralia.app/api/v1/campaigns?limit=50&cursor=01HZ..." \
  -H "X-API-Key: ag_your_key_here"

Errors

Errors return a standard HTTP status with a JSON detail:

Rate limits

Per-workspace, scaling with your plan. Over-limit requests return HTTP 429 with a message indicating the per-minute or per-day cap. See the rate limits table.

HTTP 429
{ "detail": "API rate limit exceeded (per minute). Slow down and retry shortly." }

Examples

List agents:

curl "https://api.agoralia.app/api/v1/agents?limit=20" \
  -H "X-API-Key: ag_your_key_here"

Create a campaign (draft — only a name is required):

curl -X POST https://api.agoralia.app/api/v1/campaigns \
  -H "X-API-Key: ag_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"June outreach"}'

Add a lead to a campaign:

curl -X POST https://api.agoralia.app/api/v1/campaigns/<CAMPAIGN_ID>/leads \
  -H "X-API-Key: ag_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"leads":[{"phone_number":"+15551234567","name":"Jane Doe"}]}'

Publish an agent so it can place calls:

curl -X POST https://api.agoralia.app/api/v1/agents/<AGENT_ID>/publish \
  -H "X-API-Key: ag_your_key_here"

Next

• Authentication
• MCP
• CLI