/v1/workspaces/{workspace_id}/approvalsAuthRequest an approval
Asks one or more people a yes/no question on the type's channels and records the first answer. In the inbox the item gets Approve and Reject buttons (or render it with `<NotifyApproval/>`); emails and pushes carry a signed link per approver (`approval.url`, `approval.approve_url`, `approval.reject_url`) to a hosted page that needs no sign-in. The answer arrives as the signed `approval.resolved` webhook and on `GET /approvals/{approval_id}`. Nobody answered by `expires_at`: the type's `timeout_outcome` applies (default `expired`). Pass `wait_seconds` (up to 25) to wait for the answer in this call. The type must have `approval` set; its notifications can only be sent here. An `Idempotency-Key` is required: the same key and body return the same request (200), a different body is a 409.
Path parameters
workspace_id*string · uuidId of the workspace.
Headers
Idempotency-Key*stringRequired. 1 to 256 characters of `A-Z a-z 0-9 . _ : -`, for example the id of the action you ask about (`deploy:dep_91`).
Request body
type*stringThe key of a notification type with `approval` set.
Example: "deploy.approval"
approvers*arrayWho may answer: up to 10 existing recipients (your user ids). Each gets the request on the type's channels; the first answer decides.
Example: ["user_123"]
title*stringThe question, in one line. Templates get it as `approval.title`.
Example: "Deploy api v2.14 to production?"
bodystringWhat the approver needs to decide (plain text, line breaks kept). `approval.body` in templates.
Example: "3 migrations, 41 commits. Rollback: redeploy v2.13."
requesterobjectWho is asking. Defaults to the API key or the MCP agent that calls.
dataobjectTemplate data for the type's templates, like a send's `data` (at most 16 KB as JSON).
Example: {"service":"api","version":"v2.14"}
metadataobjectYours, never shown to the approver: returned on the request and in the `approval.resolved` webhook (at most 4 KB), for example the id of the action to run.
Example: {"deployment_id":"dep_91"}
expires_in_secondsintegerWhen nobody answered by then, the request ends with the type's `timeout_outcome` (default: the type's `default_expires_in_seconds`).
Example: 3600
wait_secondsintegerWait up to this many seconds for an answer before responding (0: respond at once). An agent can then poll `GET /approvals/{approval_id}?wait_seconds=25`.
tenantstringTenant for the inbox filter, like a send's `tenant`.
Response · 200 The same Idempotency-Key and body: the existing request.
id*string · uuidThe approval request id.
type*stringThe notification type key.
Example: "deploy.approval"
status*object`pending` until someone answers; then `approved` or `rejected`; `expired` (or the type's timeout outcome) when nobody answered in time; `cancelled` when the requester withdrew it.
title*stringThe question.
body*stringThe details.
requester*objectWho asked.
approvers*arrayApprover external ids (null entries for erased recipients are dropped).
metadata*objectYour metadata, as sent.
expires_at*string · date-timeWhen it times out.
decided_by*stringWho answered (external id); null while pending, on timeout or cancel.
reason*stringThe approver's reason, if they gave one.
decided_via*objectWhere the answer came from: `inbox` (in-app buttons or `<NotifyApproval/>`), `hosted_page` (the link in an email or push), `api` (your backend), `timeout`.
decided_at*string · date-timeWhen it was answered, expired or cancelled.
notification_id*string · uuidThe notification that carried it (see the message log for every channel's delivery).
created_at*string · date-timeCreated.
Example
Request
POST https://api.notify.productcraft.co/v1/workspaces/{workspace_id}/approvals
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"type": "deploy.approval",
"approvers": [
"user_123"
],
"title": "Deploy api v2.14 to production?",
"body": "3 migrations, 41 commits. Rollback: redeploy v2.13.",
"requester": {},
"data": {
"service": "api",
"version": "v2.14"
},
"metadata": {
"deployment_id": "dep_91"
},
"expires_in_seconds": 3600,
"wait_seconds": 0,
"tenant": "string"
}Response
{
"id": "00000000-0000-0000-0000-000000000000",
"type": "deploy.approval",
"status": {},
"title": "string",
"body": "string",
"requester": {},
"approvers": [
"string"
],
"metadata": {},
"expires_at": "2026-01-01T00:00:00.000Z",
"decided_by": "string",
"reason": "string",
"decided_via": {},
"decided_at": "2026-01-01T00:00:00.000Z",
"notification_id": "00000000-0000-0000-0000-000000000000",
"created_at": "2026-01-01T00:00:00.000Z"
}