Approvals
Deletes and changes made with an API key can wait for an owner's or admin's approval before they run.
2 endpointsShow
How approvals work
Each workspace API key has two settings in Settings → API keys: Deletes wait for approval and Changes wait for approval. Both are on for a new key. While one is on, a call of that kind does not run when the key makes it: it becomes a change request, and an owner or admin of the workspace approves or rejects it under Approvals in the same tab. Each request shows where the change lands (the agent, the channel, or both), what changes there (an agent's instructions section by section, the live version, who answers a channel, or each field next to how the item looks now), what approving does next, and the exact call it runs. Approving runs the call once; rejecting it, or nobody deciding within 24 hours, runs nothing.
Anyone who may edit a key can turn its approvals on; only owners and admins can turn them off. They apply to the REST API and to the MCP server alike: every MCP tool runs its REST endpoint, so a held call is held whichever way it came. Following a request needs no scope: a key reads only the requests it made.
Which calls wait
| Setting | Calls that wait |
|---|---|
| Deletes | Every DELETE, cancelling a clinic appointment (POST /v1/clinic/appointments/:id/cancel) and cancelling a business appointment (PATCH /v1/business/appointments/:id with status: "cancelled"). |
| Changes | Every PATCH and PUT (edits), and the actions that change something that already exists: deploying an agent, starting a campaign, rescheduling a clinic appointment or setting its status, and resolving, reopening, archiving, unarchiving or resuming the AI of a conversation. |
| Always | Buying a phone number (POST /v1/phone-numbers), whatever the key's settings: it charges the workspace's card now and every month. The approver sees the number, the price, the monthly cost and the card. |
| Never | Reading, creating (a contact, a message, an enrollment, an import…), and stopping something: pausing a campaign, pausing the AI of a conversation, ending a call, cancelling a contact import, switching a channel's AI off or pausing it (PUT /v1/channels/:id/ai-mode with mode off or paused), and turning a phone channel's incoming calls off (PUT /v1/channels/:id/incoming-calls with receive_calls false). Stopping is a safety action: an approval would only delay it. One create is a change: a phone channel created with confirm_move_from_channel_id takes another channel's incoming calls, so it waits as that move does. |
Each reference page marks these calls with Can wait for approval, and a purchase with Always waits for approval. A key without the scope a call needs gets the endpoint's own 403, held or not.
Every call that can wait (131)Show
Deletes
- DELETE /v1/agents/:id
- DELETE /v1/calls/:id/notes/:note_id
- DELETE /v1/contacts/:id
- DELETE /v1/contact-lists/:id
- DELETE /v1/contact-lists/:id/members/:contact_id
- DELETE /v1/campaigns/:id
- DELETE /v1/campaigns/:id/contact-lists/:list_id
- DELETE /v1/campaigns/:id/stages/:stage_id
- DELETE /v1/goals/:id
- DELETE /v1/competencies/:id
- DELETE /v1/channels/:id
- DELETE /v1/channels/:id/agent
- DELETE /v1/channels/:id/whatsapp-templates/:template_name
- DELETE /v1/phone-numbers/:id
- DELETE /v1/webhooks/:id
- DELETE /v1/clinic/locations/:id
- DELETE /v1/clinic/location-hours/:id
- DELETE /v1/clinic/rooms/:id
- DELETE /v1/clinic/spots/:id
- DELETE /v1/clinic/doctors/:id
- DELETE /v1/clinic/days-off/:id
- DELETE /v1/clinic/services/:id
- DELETE /v1/clinic/record-fields/:id
- DELETE /v1/business/hosts/:id
- DELETE /v1/business/availability-windows/:id
- DELETE /v1/business/days-off/:id
- DELETE /v1/business/closures/:id
- DELETE /v1/business/meeting-types/:id
- DELETE /v1/business/calendar-connections/:id
- POST /v1/clinic/appointments/:id/cancel
- DELETE /v1/test-scenarios/:id
- DELETE /v1/test-run-alls/:id/dismissals
- DELETE /v1/test-runs/:id/conversations/:conversation_id/verdict-reviews
- DELETE /v1/test-numbers/:id
- DELETE /v1/agents/:id/knowledge/:source_id
Changes
- PATCH /v1/agents/:id
- POST /v1/agents/:id/deploy
- PUT /v1/agents/:id/automations
- PUT /v1/agents/:id/follow-up-emails
- PUT /v1/agents/:id/human-handoff
- PUT /v1/agents/:id/pbx-transfer
- PUT /v1/agents/:id/context-settings
- PUT /v1/agents/:id/calcom
- POST /v1/agents/:id/restore
- PUT /v1/agents/:id/booking-method
- PUT /v1/agents/:id/clinic-booking
- PUT /v1/agents/:id/business-booking
- PUT /v1/agents/:id/rest-connector
- PATCH /v1/calls/:id/notes/:note_id
- PATCH /v1/conversations/:id
- POST /v1/conversations/:id/resolve
- POST /v1/conversations/:id/reopen
- POST /v1/conversations/:id/archive
- POST /v1/conversations/:id/unarchive
- POST /v1/conversations/:id/resume-ai
- POST /v1/conversations/:id/reply-now
- POST /v1/conversations/bulk-ai
- PATCH /v1/contacts/:id
- POST /v1/contacts/bulk-tags
- PUT /v1/contact-rules
- PATCH /v1/contact-fields/:id
- PATCH /v1/contact-lists/:id
- POST /v1/contact-imports/:id/start
- PATCH /v1/campaigns/:id
- PUT /v1/campaigns/:id/workflow
- POST /v1/campaigns/:id/start
- PATCH /v1/campaigns/:id/enrollments/:enrollment_id
- POST /v1/campaigns/:id/enrollments/:enrollment_id/requeue
- PUT /v1/campaigns/:id/contact-lists/:list_id
- PUT /v1/campaigns/:id/variants
- POST /v1/campaigns/:id/variants/:variant_id/promote
- POST /v1/campaigns/:id/variants/:variant_id/use-live-version
- PATCH /v1/campaigns/:id/stages/:stage_id
- PUT /v1/campaigns/:id/stages/order
- PUT /v1/campaigns/:id/inbound-channel
- PATCH /v1/tickets/:id
- PATCH /v1/goals/:id
- PATCH /v1/competencies/:id
- PUT /v1/channels/:id/phone-number
- PUT /v1/channels/:id/incoming-calls
- PUT /v1/channels/:id/voice
- PATCH /v1/channels/:id
- PUT /v1/channels/:id/agent
- PUT /v1/channels/:id/ai-mode
- PUT /v1/channels/:id/scheduling
- PATCH /v1/channels/:id/web-widget
- PATCH /v1/channels/:id/messaging-settings
- PUT /v1/channels/:id/ivr-navigation
- POST /v1/channels/:id/ai-test-numbers
- POST /v1/channels/:id/ai-test-numbers/:number_id/start-over
- PATCH /v1/channels/:id/live-room
- POST /v1/channels/:id/ai-testers
- POST /v1/channels/:id/ai-testers/:tester_id/start-over
- POST /v1/channels/:id/whatsapp-templates/:template_name/unarchive
- PATCH /v1/channels/:id/whatsapp-templates/:template_name/fields
- PATCH /v1/channels/:id/whatsapp-profile
- POST /v1/channels/:id/whatsapp-template-hold
- POST /v1/phone-numbers
- PATCH /v1/webhooks/:id
- PATCH /v1/clinic/locations/:id
- PATCH /v1/clinic/location-hours/:id
- PATCH /v1/clinic/rooms/:id
- PATCH /v1/clinic/spots/:id
- PATCH /v1/clinic/doctors/:id
- PUT /v1/clinic/doctors/:id/weekly-hours
- PATCH /v1/clinic/services/:id
- PUT /v1/clinic/record-fields/order
- PATCH /v1/clinic/record-fields/:id
- PATCH /v1/clinic/settings
- PUT /v1/clinic/reminders
- PATCH /v1/business/hosts/:id
- PATCH /v1/business/availability-windows/:id
- PATCH /v1/business/days-off/:id
- PATCH /v1/business/closures/:id
- PATCH /v1/business/meeting-types/:id
- PATCH /v1/business/calendar-connections/:id
- PUT /v1/business/reminders
- PATCH /v1/business/settings
- PATCH /v1/business/rescheduling
- PATCH /v1/business/follow-ups
- PATCH /v1/business/appointments/:id
- PATCH /v1/clinic/appointments/:id/record
- PATCH /v1/clinic/appointments/:id
- POST /v1/clinic/appointments/:id/reschedule
- POST /v1/clinic/appointments/:id/status
- PATCH /v1/test-scenarios/:id
- POST /v1/test-runs/:id/evaluate
- POST /v1/test-run-alls/:id/try-fix
- PATCH /v1/test-numbers/:id
- POST /v1/agents/:id/knowledge/:source_id/reingest
- PATCH /v1/agents/:id/knowledge/:source_id
The answer to a held call
A held call answers 202 Accepted with the change request in data.change_request, status pending, and its URL in the Location header. Nothing has changed yet: tell your user the change waits for approval, never that it is done. Making the same call again while it waits (same method, path, query and body) answers the same request, so a retry never asks twice.
curl -X DELETE "https://www.nutalk.ai/v1/goals/7b7b8def-a340-4bfd-b164-779fa5843735" \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"change_request": {
"id": "c4a7e2d1-5b3f-4e8a-9c6d-2f1b0a9e8d7c",
"status": "pending",
"approval": "delete",
"operation": "deleteGoal",
"method": "DELETE",
"path": "/v1/goals/7b7b8def-a340-4bfd-b164-779fa5843735",
"summary": "Delete a goal: “Book qualified meeting” (DELETE /v1/goals/7b7b8def-a340-4bfd-b164-779fa5843735)",
"created_at": "2026-10-13T01:30:00.000Z",
"expires_at": "2026-10-14T01:30:00.000Z",
"decided_at": null,
"finished_at": null,
"result": null
}
},
"message": "This change waits for an owner's or admin's approval in NuTalk. It runs once approved; check it with GET /v1/change-requests/{id}."
}Statuses
A request waits up to 24 hours (expires_at). Follow it with GET /v1/change-requests/:id, or list the key's requests with GET /v1/change-requests?status=pending.
| Status | Meaning |
|---|---|
pending | Waiting for an owner or admin. Nothing has run. |
executing | Approved: the call is running now. |
executed | Approved and made. result holds the HTTP status and body the endpoint answered. |
failed | Approved, but the endpoint refused the call or it could not run (for example, the key was revoked or expired in between). result says why. |
rejected | An owner or admin rejected it. Nothing ran. |
expired | Nobody decided within 24 hours. Nothing ran. |
What approving does
- It runs the call once, exactly as the key made it (the same endpoint, query, body and
Idempotency-Key), as the key. Every check the endpoint makes runs again then, with the key's scopes as they are at that moment. - A key revoked or expired since it asked runs nothing: the request ends
failed. - Only one decision ever lands, and a request is never run twice: one interrupted while it ran reads as
failed, because the change may have been made. Check the item before asking again.
Through MCP
MCP tools return the pending request too: a tool whose call is held returns data.change_request with status pending, and the server tells the assistant to say it waits for approval, never that it is done. A key that can delete or change something and has either approval on also gets two tools to follow its requests: list_change_requests and get_change_request.
Limits
A key can have up to 20 requests waiting at once, and a workspace up to 1,000. Past that, a call that would wait answers 429 with approval_queue_full until an owner or admin decides some.
/v1/change-requestsList change requests
The deletes and changes this key asked for that waited for an owner's or admin's approval, newest first, with what each one became. Only the key's own requests.
any valid keyQuery parameters
limitinteger · 1–100Results per page. Default: 20.
offsetinteger · at least 0Results to skip. Default: 0.
statuspending | executing | executed | failed | rejected | expiredOnly requests in this status (expired includes pending requests past their expiry).
Errors
400validation_errorA query parameter is invalid (details.errors lists each one).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl "https://www.nutalk.ai/v1/change-requests?status=pending" \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": [
{
"id": "c4a7e2d1-5b3f-4e8a-9c6d-2f1b0a9e8d7c",
"status": "pending",
"approval": "delete",
"operation": "deleteGoal",
"method": "DELETE",
"path": "/v1/goals/7b7b8def-a340-4bfd-b164-779fa5843735",
"summary": "Delete a goal: “Book qualified meeting” (DELETE /v1/goals/7b7b8def-a340-4bfd-b164-779fa5843735)",
"created_at": "2026-10-13T01:30:00.000Z",
"expires_at": "2026-10-14T01:30:00.000Z",
"decided_at": null,
"finished_at": null,
"result": null
}
],
"pagination": {
"total": 1,
"limit": 20,
"offset": 0,
"has_more": false
}
}/v1/change-requests/:idGet a change request
One delete or change this key asked for that waited for approval: pending (waiting for an owner or admin), executing, executed (approved and made: result holds what the endpoint answered), failed (approved, but the endpoint refused it: result says why), rejected or expired (nobody decided within 24 hours). Only the key's own requests.
any valid keyPath parameters
iduuidrequiredThe change request id.
Errors
404not_foundNo change request asked for with this key with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/change-requests/c4a7e2d1-5b3f-4e8a-9c6d-2f1b0a9e8d7c \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"id": "c4a7e2d1-5b3f-4e8a-9c6d-2f1b0a9e8d7c",
"status": "executed",
"approval": "delete",
"operation": "deleteGoal",
"method": "DELETE",
"path": "/v1/goals/7b7b8def-a340-4bfd-b164-779fa5843735",
"summary": "Delete a goal: “Book qualified meeting” (DELETE /v1/goals/7b7b8def-a340-4bfd-b164-779fa5843735)",
"created_at": "2026-10-13T01:30:00.000Z",
"expires_at": "2026-10-14T01:30:00.000Z",
"decided_at": "2026-10-13T01:42:10.000Z",
"finished_at": "2026-10-13T01:42:11.000Z",
"result": {
"status": 200,
"body": {
"success": true,
"data": {
"id": "7b7b8def-a340-4bfd-b164-779fa5843735",
"deleted": true
}
}
}
}
}