Integration API

Drive InfraVoice from your own backend over HTTP: create voice agents, place and manage calls, run outbound campaigns, and read back call logs, transcripts and analytics — all with a single organization API key. This page is the map; each row links to the full reference for that area.

Base URL: https://ultravoice-dev.us.inc/api/v1 Auth header: Authorization: Bearer usf-… — your organization key, one per org, from Account → Organization key. Scope: the key authenticates as your org and spans every workspace in your org — never another org's. Pass ?workspace_id=… on reads that accept it; it defaults to your primary workspace.

Authentication — organization key only

There is one way to authenticate an integration: your usf- organization key, as a bearer token.

Shell

curl https://ultravoice-dev.us.inc/api/v1/agents \
  -H "Authorization: Bearer usf-EXAMPLEkeyXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

The key is validated by a real server-side lookup (a SHA-256 hash of your key against the active-keys table), not a format check. An unknown or rotated-away key returns 401.
It resolves to your organization's owner across all its workspaces. A workspace or resource outside your org returns 403 (or 404); you can never read another org's data.
Reveal or rotate the key in the dashboard, or via POST /api/v1/auth/organizations/key/reveal and POST /api/v1/auth/organizations/key/rotate.

Key rotation & revocation

Rotating issues a new key, returns its plaintext once (in data.secret), and retires the previous key.

Shell

curl -X POST https://ultravoice-dev.us.inc/api/v1/auth/organizations/key/rotate \
  -H "Authorization: Bearer usf-EXAMPLEoldkeyXXXXXXXXXXXXXXXXXXXXXXXX"
# -> { "data": { "secret": "usf-EXAMPLEnewkeyXXXXXXXXXXXXXXXXXXXXXXXX", ... } }

The new key works immediately.
The old key is revoked immediately — rotation broadcasts the change to every service, so the previous key starts returning 401 across the whole API at once, not after a delay. Switch your integration to the new key as part of the rotate call.

Errors

Status	Meaning
`401`	Missing, invalid, or rotated-away key
`403`	Key valid, but the target workspace/resource is outside your org
`404`	Not found (or hidden by workspace scoping)

Endpoint map

Every endpoint below takes your usf- key. Follow the link for request/response detail.

Assistants → Agents — see Agents

Method	Path	Purpose
`GET` `POST`	`/api/v1/agents`	List / create agents
`GET` `PUT` `DELETE`	`/api/v1/agents/{id}`	Get / update / delete
`GET` `POST` `PUT` `DELETE`	`/api/v1/agents/{id}/tools[/{toolId}]`	Agent tools
`GET` `POST` `PUT` `DELETE`	`/api/v1/agents/{id}/knowledge-bases[/{kbId}]`	Knowledge-base bindings
`GET` `PUT`	`/api/v1/agents/{id}/telephony`	Agent phone config
`GET` `POST` `DELETE`	`/api/v1/agents/{id}/providers[/{type}]`	Model / voice / transcriber
`GET`	`/api/v1/agents/{id}/versions`	Version history, publish, rollback

Assistant → Ava — see Ava API

These take your dashboard login token (JWT), not the usf- key — the assistant acts as you.

Method	Path	Purpose
`GET` `POST`	`/api/v1/voika/chats`	List / open chats
`POST`	`/api/v1/voika/chats/{id}/conductor/stream`	Send a command and stream the turn
`POST`	`/api/v1/voika/chats/{id}/resume/stream`	Answer questions; approve, revise or cancel the plan
`POST`	`/api/v1/voika/chats/{id}/changesets/{cid}/decide/stream`	Accept / reject the proposed changes
`GET`	`/api/v1/voika/chats/{id}/artifact` · `/versions`	Current agent, readiness, version history
`POST`	`/api/v1/voika/chats/{id}/undo/stream`	Roll back to an earlier version

Calls → Telephony — see Telephony & Campaigns

Method	Path	Purpose
`POST`	`/api/v1/telephony/calls/outbound`	Place an outbound call (`agent_id`, `to_number`, …)
`GET`	`/api/v1/telephony/calls` · `/calls/{id}`	List / status
`POST`	`/api/v1/telephony/calls/{id}/end` · `/transfer`	End / transfer
`GET`	`/api/v1/telephony/numbers`	List your phone numbers (read-only)

Campaigns → Telephony — see Telephony & Campaigns

Method	Path	Purpose
`GET` `POST`	`/api/v1/campaigns`	List / create
`GET` `PATCH`	`/api/v1/campaigns/{id}`	Get / update
`POST`	`/api/v1/campaigns/{id}/{start\|pause\|cancel}`	Lifecycle
`GET`	`/api/v1/campaigns/{id}/calls` · `/export`	Calls / CSV export
`POST`	`/api/v1/campaigns/{id}/csv-upload`	Upload targets (E.164)

Call logs & transcripts → Realtime Voice → Conversations · Call Center

Method	Path	Purpose
`GET`	`/api/v1/conversations?workspace_id=…`	List call logs
`GET`	`/api/v1/conversations/{id}` · `/{id}/messages`	Conversation / transcript
`GET`	`/api/v1/call-center/calls?workspace_id=…`	Call-center calls
`GET`	`/api/v1/call-center/calls/{id}/transcripts` · `/recordings`	Per-segment transcripts / recordings

Analytics → see Insights

Method	Path	Purpose
`GET`	`/api/v1/analytics/usage`	Usage — conversations, duration, spend (org-wide)
`GET`	`/api/v1/analytics/latency` · `/tool-calls`	Latency / tool-call stats

A note on scoping shapes. Agents, conversations and call-center endpoints enforce the workspace_id you pass (a workspace outside your org is rejected). Campaigns and analytics aggregate across your whole org and treat workspace_id as advisory. Both are bounded to your organization.

Not available yet

These exist in some other platforms but have no endpoint here today — treat as roadmap, not undocumented: a Files API, standalone Knowledge-Base CRUD (ingest/query), a global Tools registry, Workflows/Squads, and phone-number provisioning (buy/release). Numbers are attached to an agent via /agents/{id}/telephony.