All routes sit under /api/ai/agent/config, need Authorization: Bearer {access_token}, and return { "success": true, "data": { ... } }. Refusals return { "success": false, "message": "..." }.
Access comes only from the token: the user's company, role permissions and package. No route accepts a company ID. Another account's agent returns 404, the same as an agent that does not exist. Credentials in any response appear as [redacted].
For the plain-language guide, see Manage Voice Agents by Chat. For every field, see the settings reference.
Routes#
| Method | Path | Purpose | MCP tool |
|---|---|---|---|
| GET | /agents | Find agents: search, agent_version, page, per_page (max 50) | find_agents |
| GET | /settings-catalog | Groups, or field docs with group and agent_version | get_agent_settings_catalog |
| GET | /{agent_id}/summary | Version, status, active revision, section sizes | get_agent_config_summary |
| GET | /{agent_id}/prompt | Complete prompt or a section, in pages | get_agent_active_prompt |
| GET | /{agent_id}/settings/{group} | One group or category with current values | get_agent_settings |
| POST | /{agent_id}/changes/preview | Validate and show differences. Saves nothing. | preview_agent_change |
| POST | /changes/{change_id}/apply | Carry out an approved preview | apply_agent_change |
| GET | /{agent_id}/verify | Compare live configuration with the active revision | verify_agent_config |
| GET | /{agent_id}/revisions | History, newest first | list_agent_revisions |
| GET | /{agent_id}/revisions/{id} | One revision. include=prompt or include=settings | get_agent_revision |
| GET | /{agent_id}/revisions/{from}/compare/{to} | Differences between two revisions | compare_agent_revisions |
| POST | /{agent_id}/revisions/{id}/restore-preview | Preview going back | preview_agent_restore |
| POST | /{agent_id}/revisions/{id}/activate-preview | Preview putting a draft live | preview_agent_draft_activation |
| POST | /{agent_id}/test-call | Browser test session. Never dials a phone. | start_agent_test_session |
| GET | /calls/{call_id}/revision | The revision a past call ran on | get_call_agent_revision |
Read a prompt#
GET /api/ai/agent/config/{agent_id}/prompt
One section: project_instructions, prompt_greetings, prompt_character, prompt_transfer_instr, prompt_critical_instr, prompt_custom_vars, prompt_company_info, prompt_script_flow, prompt_call_flow, prompt_objections, prompt_appt_flow, prompt_faq_base
full is what the agent receives. own leaves out the automatic blocks.
Character to start from
Characters per page, up to 20000
This page of text
Where the next page starts. null on the last page.
false means more text remains. Keep paging until this is true.
Length of the complete text
Checksum of the complete text, to confirm you joined the pages correctly
true if platform links were hidden from this text
Preview a change#
POST /api/ai/agent/config/{agent_id}/changes/preview
Send only what should change. Anything left out stays as it is.
Section name to complete new text. Empty text is refused.
Sections to empty on purpose. project_instructions cannot be cleared.
Exact swaps: { "find": "...", "replace": "..." }. Each find must match exactly once.
Group to fields, for example { "conversation": { "interruption_sensitivity": 0.5 } }. Null values are refused.
Group to fields to empty on purpose, for example { "webhook": ["webhook_url"] }
The revision this edit was based on. Returns 409 if the agent has moved on.
Why the change is being made. Kept on the revision.
V1 or V2. Refused if the agent is not this version.
Any other field is refused, including apply_to_agent_ids: a change applies to one agent.
curl --request POST \
--url https://app.rizzdial.com/api/ai/agent/config/agent_123/changes/preview \
--header 'Authorization: Bearer {{bearer_token}}' \
--header 'Content-Type: application/json' \
--data '{
"prompt_sections": { "prompt_call_flow": "New call flow text" },
"reason": "Shorter call flow"
}'The response holds change_id, base_revision_id, expires_at_utc (60 minutes) and preview with the exact differences. If callers would not get this change, preview.warning says so and names the agent to edit instead.
Apply a change#
POST /api/ai/agent/config/changes/{change_id}/apply
Applies edits, restores and draft activations.
Must be true, sent only after the person has seen the preview and said yes
Up to 100 characters. Reuse it only to retry this approval. A retry returns the first result with replayed: true and does nothing twice.
false saves an edit as a draft. Callers do not hear a draft. Restores and draft activations always go live.
The person's approval in their words
| Status | status | Meaning |
|---|---|---|
| 200 | applied | Saved and read back. Check verification.call_serving. |
| 200 | drafted | Stored only. is_live is false. |
| 409 | stale | The agent changed after the preview. Nothing saved. |
| 409 | Another change is saving, this one was interrupted, or the key belongs to another change | |
| 410 | The preview expired | |
| 422 | Missing approval or key, or invalid request | |
| 502 | failed | Not saved. previous_configuration_preserved says whether the old configuration was confirmed intact. |
Verify#
GET /api/ai/agent/config/{agent_id}/verify
Reads the live configuration from the voice platform. Places no call.
matches_active_revision, changed_outside_this_flow or no_revision_yet
confirmed (V2: the platform holds this configuration), pending_confirmation (V1: a test call must confirm which version callers get) or forwarded (a V2 replacement answers; see serving_agent_id)
true only when live matches the active revision and call_serving.state is confirmed
What changed, when live no longer matches
Revisions#
Revisions cannot be changed or deleted. Restoring adds a new one.
observed (found live, made outside this flow), change, draft, activation or restore
active, draft or failed
Each revision also has revision_id, parent_revision_id, restored_from_revision_id, activated_from_revision_id, config_hash, prompt_history_id, requested_by, approved_by, reason, changed_paths and created_at_utc.
Test session#
POST /api/ai/agent/config/{agent_id}/test-call
Must be true, sent only after the person has asked for a test
A retry with the same key returns the same session for 30 minutes
The response has kind: "web_session", dials_a_phone: false and session, which holds access_token and, on V1, call_id, transport and ice_servers.