Skip to main content

API Endpoints Reference

Complete reference for all Public API v1 endpoints. All endpoints require authentication via API key in the X-API-Key header.

Base URL: https://api.agoralia.app/api/v1

Authentication​

All endpoints require an API key in the X-API-Key header:

curl -X GET "https://api.agoralia.app/api/v1/me" \
  -H "X-API-Key: your-api-key-here"

See Authentication for details on creating and managing API keys.

Tenant Information​

GET /me​

Get information about your tenant and the scopes of your API key.

Required Scope: me:read

Response:

{
  "tenant_id": 1234,
  "workspace_name": "My Workspace",
  "plan": "pro",
  "rate_limits": {
    "rpm": 120,
    "rpd": 20000
  },
  "api_key_scopes": ["me:read", "agents:read", "agents:write"]
}

Example:

curl -X GET "https://api.agoralia.app/api/v1/me" \
  -H "X-API-Key: your-api-key-here"

Agents​

GET /agents​

List all agents in your workspace.

Required Scope: agents:read

Query Parameters:

  • limit (optional, default: 20, max: 100): Number of agents to return
  • cursor (optional): Pagination cursor (agent ID)

Response:

{
  "items": [
    {
      "id": 1,
      "name": "Sales Agent",
      "lang": "it-IT",
      "voice_engine": "vapi"
    }
  ],
  "next_cursor": 10
}

Example:

curl -X GET "https://api.agoralia.app/api/v1/agents?limit=50" \
  -H "X-API-Key: your-api-key-here"

POST /agents​

Create a new agent.

Required Scope: agents:write

Request Body:

{
  "name": "Customer Support Agent",
  "lang": "en-US",
  "voice_engine": "vapi",
  "voice_id": "voice-id-here",
  "model": "gpt-4o-mini",
  "general_tools": [],
  "post_call_analysis_data": []
}

Request Fields:

  • name (required): Agent name
  • lang (optional): Language code (e.g., "en-US", "it-IT")
  • voice_engine (optional, default: "vapi"): Voice engine ("vapi" or "retell")
  • voice_id (optional): Voice ID for the agent
  • model (optional, default: "gpt-4o-mini"): LLM model to use
  • general_tools (optional): Array of tool objects for the LLM
  • post_call_analysis_data (optional): Array of post-call analysis configurations

Response:

{
  "id": 15,
  "name": "Customer Support Agent",
  "lang": "en-US",
  "voice_engine": "vapi"
}

Example:

curl -X POST "https://api.agoralia.app/api/v1/agents" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{
    "name": "Customer Support Agent",
    "lang": "en-US",
    "voice_engine": "vapi"
  }'

Note:

  • This endpoint supports idempotency. Include an Idempotency-Key header to safely retry requests.
  • Advanced Configuration: This endpoint currently supports basic agent creation. For advanced settings (voice temperature, interruption sensitivity, webhooks, knowledge bases, etc.), use the web interface or check for future API updates.

Campaigns​

GET /campaigns​

List all campaigns in your workspace.

Required Scope: campaigns:read

Query Parameters:

  • limit (optional, default: 20, max: 100): Number of campaigns to return
  • cursor (optional): Pagination cursor (campaign ID)

Response:

{
  "items": [
    {
      "id": 1,
      "name": "Q1 Sales Campaign",
      "status": "active"
    }
  ],
  "next_cursor": 10
}

Example:

curl -X GET "https://api.agoralia.app/api/v1/campaigns" \
  -H "X-API-Key: your-api-key-here"

POST /campaigns​

Create a new campaign.

Required Scope: campaigns:write

Request Body:

{
  "name": "Q1 Sales Campaign",
  "purpose": "quote_request",
  "agent_ref_id": 1,
  "from_number_id": 123,
  "call_language_mode": "auto",
  "output_language": "same_as_call",
  "extraction_schema": {
    "type": "object",
    "properties": {
      "quote_amount": {
        "type": "number",
        "required": true
      },
      "availability": {
        "type": "string",
        "enum": ["yes", "no", "unknown"]
      }
    }
  },
  "display_columns": ["name", "phone", "quote_amount"],
  "schedule": {
    "timezone": "Europe/Rome",
    "start_date": "2025-01-20T00:00:00Z",
    "end_date": "2025-01-31T23:59:59Z"
  }
}

Request Fields:

  • name (required): Campaign name
  • purpose (required): Campaign purpose - "quote_request", "cold_calling", "appointment", "qualification", or "inbound"
  • agent_ref_id (required): ID of the agent to use (from GET /agents)
  • from_number_id (optional): Phone number ID to use for outbound calls
  • call_language_mode (optional, default: "auto"): "auto" (auto-detect) or "fixed" (use agent language)
  • output_language (optional, default: "same_as_call"): "same_as_call" or BCP-47 code like "en-US", "it-IT"
  • extraction_schema (required): JSON Schema defining what to extract from calls
  • display_columns (required): Array of column keys to display in results
  • schedule (optional): Object with timezone, start_date, end_date (ISO 8601 format)

Response:

{
  "id": 5,
  "name": "Q1 Sales Campaign",
  "status": "draft"
}

Example:

curl -X POST "https://api.agoralia.app/api/v1/campaigns" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-456" \
  -d '{
    "name": "Q1 Sales Campaign",
    "purpose": "quote_request",
    "agent_ref_id": 1,
    "extraction_schema": {
      "type": "object",
      "properties": {
        "quote_amount": {"type": "number"}
      }
    },
    "display_columns": ["quote_amount"]
  }'

Note:

  • This endpoint supports idempotency.
  • Advanced Configuration: This endpoint currently supports basic campaign creation. For advanced settings (quiet hours, call limits, budget limits, knowledge base assignment, etc.), use the web interface or check for future API updates.

POST /campaigns/{campaign_id}/start​

Start a campaign. Returns a proposal ID that requires confirmation (double opt-in pattern).

Required Scope: campaigns:start

Path Parameters:

  • campaign_id (required): Campaign ID to start

Response:

{
  "proposal_id": "pc_abc12345",
  "requires_confirmation": true
}

Example:

curl -X POST "https://api.agoralia.app/api/v1/campaigns/5/start" \
  -H "X-API-Key: your-api-key-here"

GET /campaigns/{campaign_id}/results​

Get results from a campaign.

Required Scope: results:read

Path Parameters:

  • campaign_id (required): Campaign ID

Response:

{
  "display_columns": [
    {"name": "name", "label": "Name"},
    {"name": "phone", "label": "Phone"},
    {"name": "quote_amount", "label": "Quote Amount"}
  ],
  "rows": [
    {
      "name": "John Doe",
      "phone": "+393401234567",
      "quote_amount": 1500
    }
  ]
}

Example:

curl -X GET "https://api.agoralia.app/api/v1/campaigns/5/results" \
  -H "X-API-Key: your-api-key-here"

Leads​

POST /leads:upsert​

Create or update leads for a campaign. Uses external_id to determine if a lead already exists.

Required Scope: leads:write

Request Body:

{
  "campaign_id": 5,
  "items": [
    {
      "external_id": "lead-123",
      "phone": "+393401234567",
      "name": "John Doe",
      "data": {
        "company": "Acme Corp",
        "email": "john@acme.com"
      }
    },
    {
      "external_id": "lead-124",
      "phone": "+393401234568",
      "name": "Jane Smith",
      "data": {
        "company": "Tech Inc",
        "email": "jane@tech.com"
      }
    }
  ]
}

Response:

{
  "created": 1,
  "updated": 1,
  "failed": 0
}

Example:

curl -X POST "https://api.agoralia.app/api/v1/leads:upsert" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-789" \
  -d '{
    "campaign_id": 5,
    "items": [
      {
        "external_id": "lead-123",
        "phone": "+393401234567",
        "name": "John Doe"
      }
    ]
  }'

Note:

  • If a lead with the same external_id exists, it will be updated
  • If not, a new lead will be created
  • This endpoint supports idempotency

Phone Numbers​

Note: Phone number management endpoints are currently available only through the web interface. API endpoints for listing, adding, and managing phone numbers will be available in a future release.

To use a phone number in a campaign, you need to:

  1. Add the phone number via the web interface (Settings → Telephony → Phone Numbers)
  2. Get the from_number_id from the campaign creation response or web interface
  3. Use that from_number_id when creating campaigns via the API

Calls​

GET /calls​

List call records.

Required Scope: calls:read

Query Parameters:

  • campaign_id (optional): Filter by campaign ID
  • limit (optional, default: 20, max: 100): Number of calls to return
  • cursor (optional): Pagination cursor (call ID)

Response:

{
  "items": [
    {
      "id": 100,
      "status": "completed",
      "to_number": "+393401234567",
      "detected_language": "it-IT"
    }
  ],
  "next_cursor": 90
}

Example:

curl -X GET "https://api.agoralia.app/api/v1/calls?campaign_id=5&limit=50" \
  -H "X-API-Key: your-api-key-here"

Pagination​

Most list endpoints support cursor-based pagination:

  1. Make initial request without cursor
  2. If next_cursor is present in response, use it for the next page
  3. Continue until next_cursor is null

Example:

# First page
curl -X GET "https://api.agoralia.app/api/v1/agents?limit=20" \
  -H "X-API-Key: your-api-key-here"

# Response: {"items": [...], "next_cursor": 15}

# Next page
curl -X GET "https://api.agoralia.app/api/v1/agents?limit=20&cursor=15" \
  -H "X-API-Key: your-api-key-here"

Error Responses​

All endpoints return standard HTTP status codes. See Error Handling for details.

Common errors:

  • 401 Unauthorized: Invalid or missing API key
  • 403 Forbidden: API key missing required scope
  • 404 Not Found: Resource not found
  • 422 Validation Error: Invalid request body or parameters

Next Steps​