Notify API reference

Notify API · Approvals

post/v1/workspaces/{workspace_id}/approvalsAuth

Request 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 15) 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 · uuid

Id of the workspace.

Headers

Idempotency-Key*string

Required. 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*string

The key of a notification type with `approval` set.

Example: "deploy.approval"

approvers*array

Who 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*string

The question, in one line. Templates get it as `approval.title`.

Example: "Deploy api v2.14 to production?"

bodystring

What the approver needs to decide (plain text, line breaks kept). `approval.body` in templates.

Example: "3 migrations, 41 commits. Rollback: redeploy v2.13."

requesterobject

Who is asking. Defaults to the API key or the MCP agent that calls.

dataobject

Template data for the type's templates, like a send's `data` (at most 16 KB as JSON).

Example: {"service":"api","version":"v2.14"}

metadataobject

Yours, 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_secondsinteger

When nobody answered by then, the request ends with the type's `timeout_outcome` (default: the type's `default_expires_in_seconds`).

Example: 3600

wait_secondsinteger

Wait 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=15`.

tenantstring

Tenant for the inbox filter, like a send's `tenant`.

Response · 200 The same Idempotency-Key and body: the existing request.

id*string · uuid

The approval request id.

type*string

The 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*string

The question.

body*string

The details.

requester*object

Who asked.

approvers*array

Approver external ids (null entries for erased recipients are dropped).

metadata*object

Your metadata, as sent.

expires_at*string · date-time

When it times out.

decided_by*string

Who answered (external id); null while pending, on timeout or cancel.

reason*string

The approver's reason, if they gave one.

decided_via*object

Where 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-time

When it was answered, expired or cancelled.

notification_id*string · uuid

The notification that carried it (see the message log for every channel's delivery).

created_at*string · date-time

Created.

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"
}