Developers — CallGeni.us API

Authentication

All API requests require a Bearer token in the Authorization header. You can generate a token by calling POST /api/auth/login.

curl https://callgeni.us/api/agents \
  -H "Authorization: Bearer <your_token>" \
  -H "Accept: application/json"

Tokens are scoped to your active business (tenant). To operate on a different business, switch your active tenant first via POST /api/tenants/switch.

Base URL

https://callgeni.us/api

All endpoints are relative to this base URL. All responses are application/json.

Errors

Code	Meaning
401	Missing or invalid token
403	Token valid but not allowed to access this resource
404	Resource not found (or belongs to another tenant)
422	Validation error — `errors` object in response body
429	Rate limited — back off and retry

Agents

GET /api/agents List all agents

Returns all agents for your active business, including their current version, voice, language, and assigned phone numbers.

curl https://callgeni.us/api/agents \
  -H "Authorization: Bearer <token>"

Response: 200 [ { id, name, voice, language, current_version, has_number, status, created_at }, … ]

POST /api/agents Create an agent

Field	Type	Required	Description
name	string	yes	Agent display name
voice	string	yes	Voice ID (e.g. `aria`, `leo`)
language	string	yes	BCP-47 language code (e.g. `en-AU`, `es-MX`)
system_prompt	string	no	Base instructions for the agent
humour_level	integer 0–30	no	Personality slider
empathy_level	integer 0–100	no	Personality slider
formality_level	integer 0–100	no	Personality slider
energy_level	integer 0–100	no	Personality slider
directness_level	integer 0–100	no	Personality slider

curl -X POST https://callgeni.us/api/agents \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Reception Bot","voice":"aria","language":"en-AU","system_prompt":"You are a friendly receptionist..."}'

GET /api/agents/{id} Get agent

Returns a single agent including compiled instructions, version history summary, and assigned number.

PUT /api/agents/{id} Update agent

Accepts the same fields as Create. Every update creates a new version snapshot and re-compiles the agent instructions. The previous version is preserved and can be rolled back via POST /api/agents/{id}/versions/{version}/rollback.

DELETE /api/agents/{id} Delete agent

Permanently deletes the agent and unassigns any phone numbers. Active calls will complete before deletion takes effect.

Calls

GET /api/calls List calls

Returns paginated call records. Supports query params: per_page, agent_id, status, from (date), to (date).

curl "https://callgeni.us/api/calls?per_page=50&status=completed" \
  -H "Authorization: Bearer <token>"

GET /api/calls/{id} Get call

Returns call metadata including status, duration, from/to numbers, agent used, AI summary, and sentiment score.

GET /api/calls/{id}/transcript Get transcript

Returns the full word-by-word transcript as an ordered array of turns, each tagged with speaker (caller or agent), text, and timestamp offset in seconds.

[
  { "speaker": "agent",  "text": "Hi, thanks for calling...", "offset_sec": 0.0 },
  { "speaker": "caller", "text": "I'd like to book an appointment", "offset_sec": 3.2 }
]

GET /api/calls/{id}/recording Get recording URL

Returns a time-limited signed URL to stream or download the call recording MP3. URLs expire after 1 hour.

Phone Numbers

GET /api/numbers List provisioned numbers

Returns all phone numbers provisioned for your active business, including their assigned agent.

GET /api/numbers/available Search available numbers

Search our carrier inventory for available numbers. Params: country (AU/US/GB/CA/NZ/IE), area_code, type (local/mobile/tollfree).

POST /api/numbers Provision a number

Purchases and provisions a phone number. Required fields: phone_number (E.164), country.

POST /api/numbers/{id}/assign Assign to agent

Assigns a phone number to an agent so it handles inbound calls. Body: { "agent_id": 42 }.

Outbound Campaigns

GET /api/campaigns List campaigns

Returns all outbound campaigns with their status, target count, and completion stats.

POST /api/campaigns Create campaign

Creates a new outbound dialling campaign. Required: name, agent_id, targets (array of { phone_number, name? }).

{
  "name": "Re-engagement Q2",
  "agent_id": 42,
  "targets": [
    { "phone_number": "+61412345678", "name": "Jane Smith" },
    { "phone_number": "+61498765432" }
  ]
}

POST /api/campaigns/{id}/start Start campaign

Begins dialling all pending targets. Use POST /api/campaigns/{id}/pause to pause mid-run.

Billing

GET /api/billing/usage Current usage

Returns current billing period usage including minutes used, included minutes, wallet balance, and trial minutes remaining.

{
  "plan": "pro",
  "minutes_used": 87,
  "included_minutes": 350,
  "wallet_balance_cents": 4200,
  "trial_minutes_remaining": 0
}

Knowledge Base

POST /api/knowledge Upload document

Upload a PDF or DOCX file to the knowledge base. The document is indexed and made available to agents as a searchable knowledge source during calls. Send as multipart/form-data with a file field.

curl -X POST https://callgeni.us/api/knowledge \
  -H "Authorization: Bearer <token>" \
  -F "file=@menu.pdf"

GET /api/knowledge List documents

Returns all uploaded knowledge documents, their processing status, and which agents they're linked to.

Webhooks

Configure a webhook URL in your dashboard to receive real-time POST notifications for call events. All events are signed with an X-CallGenius-Signature HMAC-SHA256 header so you can verify authenticity.

Event	Description
call.started	A new inbound or outbound call has connected
call.ended	Call completed — includes duration and disposition
call.transcript_ready	Full transcript and AI summary are available
booking.created	Agent successfully booked an appointment
campaign.completed	All targets in an outbound campaign have been dialled

Rate Limits

API endpoints are rate-limited per token. Standard limit is 120 requests/minute. Webhook endpoints have stricter limits. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

CallGeni.us API