---
title: "On-behalf update broker. Routes a typed mutation intent through scope, tenant, schema, authority, idempotency, and risk policy. Returns executed, needs_user_input, needs_approval, pending_approval, denied, or unsupported — never an unaudited side effect."
method: POST
path: "/v1/update-requests"
---

# On-behalf update broker. Routes a typed mutation intent through scope, tenant, schema, authority, idempotency, and risk policy. Returns executed, needs_user_input, needs_approval, pending_approval, denied, or unsupported — never an unaudited side effect.

`POST /v1/update-requests`

## Request

- Base URL: `https://www.kaicalls.com/api`
- URL: `https://www.kaicalls.com/api/v1/update-requests`
- Auth: HTTP bearer

## Request body

- UpdateRequest: Governed mutation request for the KaiCalls update broker. Carries the safety envelope (idempotency_key, actor, authority) required for auditable on-behalf changes.
  - `intent` 'phone.emergency_address.set' | 'transcripts.sink.configure' | 'agent.patch', required
  - `business_id` string, uuid
  - `target` object
  - `payload` object
  - `idempotency_key` string: Required for mutating requests; replays return the original outcome.
  - `actor` object
    - `type` 'agent' | 'human' | 'system' | 'integration'
    - `id` string
    - `display_name` string
  - `authority` object
    - `mode` 'none' | 'agent_asserted' | 'human_confirmed' | 'dashboard_session' | 'system_policy'
    - `confirmed_by` string
    - `confirmed_at` string, date-time
    - `confirmation_ref` string
  - `dry_run` boolean
  - `queue_for_approval` boolean
  - `reason` string
  - `source_ref` string

## Response `200`

Executed (or dry-run validated) update request.

## Other responses

- `202`: Accepted but needs approval/authority (needs_approval or pending_approval).
- `400`: needs_user_input or unsupported intent/fields.
- `403`: denied (tenant, scope, or object authorization failed).
- `409`: idempotency_conflict, rejected, or expired.

---

[API](https://skmtc.dev/kaicalls/apis/kaicalls-public-api.md) · [All operations](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/revisions/e607fc6cf36e?raw)