API reference

This page lists every endpoint an API key can call. Endpoints a key can’t use, such as managing members or webhooks, aren’t listed: do those in the app.

To create a key and make a first request, see API quick start.

Conventions

Addresses

All paths below start from your organisation’s address:

https://<your-360-host>/v1/orgs/<org-id>

So GET /agents means GET https://<your-360-host>/v1/orgs/<org-id>/agents. Ask your 360 contact for the host and your organisation ID. A path with another organisation’s ID answers 404.

Request and response bodies are JSON, with field names in camelCase. Times are ISO 8601 in UTC. Amounts of money are objects such as {"amount": "0.0425", "currency": "USD"}, with the amount as text.

Authentication and permissions

Send the key in every request:

Authorization: Bearer vb_live_xxxx…

The Permission column below says which of the key’s permissions the endpoint needs:

Permission	Covers
Read	Reading agents, calls, recordings, analytics and alerts.
Write	Reading agents, and changing agents and knowledge bases.
Calls	Starting outbound calls.

“Read or Write” means either one is enough. A key without the right permission gets 403 forbidden.

Write keys can start calls

POST /calls/outbound accepts a key with Calls or with Write. Treat every Write key as one that can call your customers.

Errors

Every error is application/problem+json:

{
  "type": "about:blank",
  "code": "validation_failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "Some fields are invalid.",
  "errors": [{ "field": "to", "message": "Use international format, e.g. +14155550123." }]
}

Field	What it is
code	What went wrong, for your code to check. New codes can appear: treat a code you don’t know by its status.
title, detail	Plain sentences you can show to a person. detail is sometimes missing.
errors	For 422 errors, the fields at fault, as field and message.

Some errors add more fields, such as retryAfterSeconds. A request body with a field the endpoint doesn’t know fails with 422: “The request has fields this endpoint doesn’t accept.” Every code is listed in Error messages.

Pages

Lists such as GET /agents and GET /calls return one page at a time:

{ "items": [ … ], "nextCursor": "25" }

Send limit (1 to 100, default 25) for the page size. When nextCursor isn’t null, send it as cursor to get the next page. Treat the cursor as an opaque value.

Idempotency keys

Requests that create something take an Idempotency-Key header: any unique text of 8 to 128 characters, such as a UUID. They’re marked Key in the tables below, and they fail with 428 precondition_required without one.

• Sending the same request again with the same key, within 24 hours, returns the first answer. Nothing is created twice.
• The same key with a different body fails with 422 idempotency_key_reused.
• Only successful answers are kept. After an error, fix the request and send it again with the same key.

ETags and If-Match

Changes to an agent’s draft, and to what’s on its lines, are protected against overwriting someone else’s work.

1. Read the thing you want to change. The answer has an ETag header.

2. Send that value back in an If-Match header with your change.

3. If someone else changed it in between, you get 412 draft_conflict or agent_conflict. Read it again, reapply your change, and send it with the new ETag.

Change	If-Match value
Save the draft, restore a draft, publish, roll back	The ETag from GET /agents/{agentId}/draft
Put a version live	The ETag from GET /agents/{agentId}

Without If-Match, or with *, the request fails with 428 precondition_required.

Rate limits

Each key can make 120 requests a minute. The allowance refills at 2 requests a second, and a key that has been quiet can send up to 120 at once. Over the limit, the request fails with:

{
  "type": "about:blank",
  "code": "rate_limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "This API key is over its request rate. Retry later.",
  "retryAfterSeconds": 3
}

Wait retryAfterSeconds, then try again. This answer has no Retry-After header, so read the body.

Other limits also answer 429:

code	When	Wait
rate_limited	More outbound calls this minute than your organisation allows (30 unless 360 changed it).	retryAfterSeconds in the body (60). No Retry-After header.
concurrency_limit	More outbound calls running at once than your organisation allows (10 unless 360 changed it).	Until a call ends.
usage_limit_reached	The daily or hourly limit on AI drafts is used up.	The Retry-After header, or retryAfterSeconds and resetsAt in the body.

All limits are in Limits.

Organisation

Method	Path	Permission	What it does
GET	/context	Any	Your organisation’s currency, locale, timezone, region and which features are on.
GET	/settings	Any	Organisation settings.
GET	https://<your-360-host>/v1/templates	Any	The agent templates. This path doesn’t include your organisation.

Agents

Method	Path	Permission	What it does
GET	/agents	Read or Write	List agents, a page at a time. q searches by name.
POST	/agents	Write, Key	Create an agent: {"from": "template", "templateId": "…", "name": "…"}, or {"from": "blank", "name": "…"}.
GET	/agents/{agentId}	Read or Write	One agent, with what’s on its staging (test) and production (live) lines. Returns an ETag.

The API calls the test line staging and the live line production.

Drafts and versions

See Drafts and versions for how they fit together.

Method	Path	Permission	What it does
GET	/agents/{agentId}/draft	Read or Write	The draft’s full config. Returns an ETag.
PUT	/agents/{agentId}/draft	Write, If-Match	Save the draft: {"config": {…}}. Send the whole config, as GET returned it, with your changes.
GET	/agents/{agentId}/draft/history	Read or Write	Earlier saves of the draft, a page at a time.
GET	/agents/{agentId}/draft/history/{snapshotId}	Read or Write	One earlier save.
POST	/agents/{agentId}/draft/restore/{snapshotId}	Write, If-Match	Make an earlier save the draft again.
POST	/agents/{agentId}/publish	Write, If-Match, Key	Publish the draft as a new version: {"environment": "staging", "note": "…"}. It goes on the test line; the first version also goes live.
POST	/agents/{agentId}/promote	Write, If-Match, Key	Put a version live: {"versionId": "…"}.
POST	/agents/{agentId}/rollback/{versionId}	Write, If-Match, Key	Copy a version into the draft, to publish it again.
GET	/agents/{agentId}/versions	Read or Write	The agent’s versions, newest first.
GET	/agents/{agentId}/versions/{versionId}	Read or Write	One version, with its config.
GET	/agents/{agentId}/diff?from=…&to=…	Read or Write	What changed, field by field. from and to are each a version ID, draft, staging or production.
POST	/agents/{agentId}/guardrails/try	Write	Try one custom check against a sample caller line.

environment must be staging. A pathway with problems can’t be published: the answer is 422 pathway_invalid, with the problems in issues.

Calls

Method	Path	Permission	What it does
POST	/calls/outbound	Calls or Write, Key	Start an outbound call. See Start an outbound call.
GET	/calls	Read	The call log, newest first, a page at a time, with a summary. Filter with agentId, source (phone or test), outcome, analysisOutcome, status, and q: a phone number, or words said in the call.
GET	/calls/{callId}	Read	One call: transcript, tool calls, what was collected, analysis, recording state and cost.
GET	/calls/{callId}/analysis	Read	The call’s post-call analysis.
POST	/calls/{callId}/analysis	Write	Run the post-call analysis again.
GET	/calls/{callId}/recording	Read	The recording, as audio/ogg or audio/mpeg. Supports Range. 409 recording_unavailable when there’s none.
GET	/outcomes	Read	Your organisation’s list of call outcomes.
GET	/diagnoses?callId=…, /diagnoses/{diagnosisId}	Read	The latest AI review of a call, or one review by its ID.
GET	/dnc, /dnc/export	Read	Your do-not-call list, as JSON or CSV.

{callId} is the jobId from the call.ended webhook, or an id from GET /calls.

Analytics and alerts

Method	Path	Permission	What it does
GET	/analytics/overview	Read	Calls, outcomes and other totals for a period.
GET	/analytics/latency	Read	Reply times. days: 1 to 90, default 7.
GET	/analytics/cost	Read	What calls cost in a period.
GET	/analytics/export	Read	The calls in a period, as CSV.
GET	/analytics/agents/{agentId}/trends	Read	One agent’s trends. days: 1 to 90, default 7.
GET	/alerts/rules	Read	Your alert rules.
GET	/alerts/incidents, /alerts/incidents/{incidentId}	Read	Alerts that fired.

Overview, cost and export take from and to (YYYY-MM-DD in your organisation’s timezone, or a full ISO date-time), agentId, version and source (phone or test). Without dates, they cover the last 7 days. A period can be at most 92 days.

Knowledge bases

Only when knowledge bases are on for your organisation. Otherwise these answer 403 feature_disabled.

Method	Path	Permission	What it does
GET	/knowledge-bases	Read or Write	List knowledge bases.
POST	/knowledge-bases	Write, Key	Create one: {"name": "…", "description": "…"}.
GET	/knowledge-bases/{kbId}	Read or Write	One knowledge base.
PATCH	/knowledge-bases/{kbId}	Write	Change its name (up to 120 characters) or description (up to 500).
DELETE	/knowledge-bases/{kbId}	Write	Delete it. 409 kb_in_use while an agent uses it.
GET	/knowledge-bases/{kbId}/chunks	Read or Write	The text pieces the agent searches.
POST	/knowledge-bases/{kbId}/query	Read or Write	Ask a test question and see what would be found: {"query": "…", "topK": 5}.
POST	/knowledge-bases/{kbId}/sources/files	Write, Key	Upload a file as multipart form data, in the field file: PDF, DOCX, TXT, MD or CSV, up to 20 MB.
POST	/knowledge-bases/{kbId}/sources/urls	Write, Key	Add a website: {"url": "https://…", "maxPages": 50}. maxPages is 1 to 500.
POST	/knowledge-bases/{kbId}/sources/{sourceId}/resync	Write	Fetch a source again.
DELETE	/knowledge-bases/{kbId}/sources/{sourceId}	Write	Remove a source.

Models, voices and prices

Method	Path	Permission	What it does
GET	/catalog/models	Read or Write	Speech-to-text, LLM, text-to-speech and all-in-one models, with prices.
GET	/catalog/voices	Read or Write	Voices.
GET	/catalog/voices/{voiceId}/preview	Read or Write	A voice sample.
GET	/catalog/languages	Read or Write	Languages.
GET	/catalog/presets	Read or Write	The presets: Budget, Balanced, Performance and Ultra.
GET	/catalog/tuning	Read or Write	Voice tuning options.
POST	/quote	Read or Write	Price per minute and expected reply time for a config.
POST	/quote/best-under-budget	Read or Write	The best set of models that fits a price per minute.
POST	/pathway/validate	Read or Write	Check a pathway for problems, when pathways are on.

AI drafting

Method	Path	Permission	What it does
POST	/ai-jobs	Write, Key	Start AI work: draft an agent or a pathway, or rewrite a prompt field. Counts towards the AI drafts usage limit. A version_summary job needs only Read or Write and doesn’t count.
GET	/ai-jobs/{jobId}	Read or Write	The job’s status and result.
POST	/ai-jobs/{jobId}/answers	Write	Answer the job’s questions, when it asks some.

A finished agent job can be turned into an agent with POST /agents and {"from": "ai", "aiJobId": "…"}.

Other endpoints

Method	Path	Permission	What it does
GET	/agents/{agentId}/test-profiles	Read or Write	Saved test inputs.
GET	/agents/{agentId}/scenarios	Read or Write	Saved scenarios for simulated callers, when simulations are on.
GET	/agents/{agentId}/scenario-results	Read or Write	Each scenario’s latest result.
GET	/secrets	Write	Your stored tool credentials: names and last 4 characters only.
POST	/secrets	Write	Store a new tool credential.
GET	/numbers	Read or Write	Your phone numbers and the agent each points at.
GET	/phone-agent	Read or Write	The agent that answers your organisation’s calls.
GET	/number-requests, /requests	Read or Write	Your requests to 360.
GET	/telephony/status	Read or Write	Whether outbound calling and call recordings are set up.
GET	/telephony/settings, /telephony/providers	Read or Write	Telephony settings and providers.
GET	/integrations/salesforce	Read or Write	Whether Salesforce is connected.
GET	/integrations/salesforce/call-logs	Read	Calls written to Salesforce.
GET	/cti, /cti/queues, /cti/writebacks	Read	360 CTI connection, queues and call results sent back.
GET	/memory/settings	Read	Caller memory settings.
GET	/usage-limits	Read or Write	Today’s use of each usage limit.
GET	/onboarding	Read or Write	Getting-started progress.
PUT	/onboarding/dismissal	Write	Hide the getting-started checklist.
GET	/lifecycle	Read or Write	Whether the organisation is active or scheduled for deletion.

What keys can’t do

No key can call these, whatever its permissions. Do them in the app:

• Delete or restore an agent.
• Run tests: test calls, test chats, simulated calls, and AI reviews.
• Manage alerts, phone numbers, telephony, integrations, webhooks, API keys, provider keys, members or 360 staff access.
• Change organisation settings, caller memory or outcomes, or the do-not-call list.
• See billing or the audit log.