Update a binding
PATCH /api/v1/telephony/inbound/bindings/{id} — swap the agent without re-provisioning the provider.
PATCH /api/v1/telephony/inbound/bindings/{id}Swap the agent attached to this binding. The provider-side webhook URL and stored credentials are untouched — only the resolved agentSnapshot changes.
Use re-POST for credential changes
This endpoint is the cheap path for "use a different agent on this number." To change credentials, re-POST POST /call type=inbound — that's the only path that re-runs provider verification + provisioning.
Request body
Exactly one of:
| Pattern | Result |
|---|---|
{ "agent": { ... } } | Inline transient agent — a full Agent Config. |
{ "agentId": "<uuid>" } | Use a saved agent (persistent mode). |
Plus optional contextVariables (object of strings) — these are baked into the stored snapshot; system built-ins like {{current_time}} still resolve fresh on every call. Model ids are validated against the live catalog at this boundary (422 on unknown models).
Sending both agent and agentId, or omitting both, returns 400.
Response
200 OK with the updated binding detail. Same shape as GET /telephony/inbound/bindings/{id}.
Examples
curl -X PATCH https://dashboard.zoxa.ai/api/v1/telephony/inbound/bindings/5 \
-H "X-API-Key: zsk_..." \
-H "Content-Type: application/json" \
-d '{ "agentId": "550e8400-e29b-41d4-a716-446655440000" }'await fetch(`https://dashboard.zoxa.ai/api/v1/telephony/inbound/bindings/${id}`, {
method: "PATCH",
headers: { "X-API-Key": "zsk_...", "Content-Type": "application/json" },
body: JSON.stringify({ agentId: "550e8400-..." }),
});import httpx
httpx.patch(
f"https://dashboard.zoxa.ai/api/v1/telephony/inbound/bindings/{binding_id}",
headers={"X-API-Key": "zsk_..."},
json={"agentId": "550e8400-..."},
)Errors
| Status | detail | When |
|---|---|---|
400 | "provide_agent_or_agentId_not_both" | Both agent and agentId sent. |
400 | "must_provide_agent_or_agentId" | Neither sent. |
400 | format-error string | Resolved snapshot fails schema validation. |
404 | "binding_not_found" | Id doesn't exist in your org. |
404 | "agent_not_found" | Referenced agentId doesn't exist in your org. |