Approval Template

The question rides state; the buttons are options -- each one either fires your webhook directly from the device, or is recorded by the server into the read-only answer field. The second form is what lets an agent script, a CI job or a Home Assistant automation block on a human decision without exposing any endpoint to the internet.

Fields

The activity name is the card title and stays short; state is the question, two lines at most before it truncates. When details rows are present they take the space the question had on the Lock Screen, so make the name itself interrogative ("Send follow-up to Brightlane?") -- the question still shows in the expanded Dynamic Island and in-app.

Sending an approval field on another template is rejected with 422 rather than ignored, and so is the reverse: url_action, secondary_url_action, alarm and snooze_seconds are rejected on this template -- the options row is the button row. tap_action (tapping the card background) still works.

Options

Each option is one button. Two options render as a filled-primary next to an outlined-secondary; three or four render as a row of icon-over-label tiles, which is why icon becomes required at that count.

Two ways the answer comes back

Taps follow the standard tap rules -- an http(s) URL is a silent webhook, a custom scheme opens that app, and a button is never allowed to open the browser: an answer button that opens Safari is not an answer button. The card itself never invents state: after a tap it waits for a push, and which push that is depends on whether the option carries a url.

• Producer webhooks -- every option carries a url. The device calls your endpoint directly; your side then confirms with a PATCH (new question, new options) or ends the activity. The server never learns what was tapped, and a second device can fire the same webhook again -- use the server-recorded form when a repeat matters.
• Server-recorded -- options omit url. The server fills in a signed answer URL when it stores the option; the first tap writes answer, the resolved card is pushed to every device, and the activity ends on its own a few seconds later, unless the card has another question to ask. First answer wins -- a second device tapping later changes nothing. dismissal_ttl (an activity-level field) is how long the answered card lingers on the Lock Screen. Your code just polls:

curl "https://api.pushward.app/activities/approval-request?wait=25" \
  -H "Authorization: Bearer hlk_YOUR_TOKEN"

{
  "state": "ended",
  "content": {
    "template": "approval",
    "state": "Promote 1.11.0 to production?",
    "options": [
      { "id": "promote", "title": "Promote", "style": "primary",
        "url": "https://api.pushward.app/activity/answer?token=...", "method": "POST" },
      { "id": "hold", "title": "Hold", "style": "secondary",
        "url": "https://api.pushward.app/activity/answer?token=...", "method": "POST" }
    ],
    "answer": { "option": "promote", "at": 1788220800, "by": "user" }
  }
}

Read GET /activities/{slug} until content.answer is set. With ?wait=N (up to 25 seconds) the request is held open while the approval waits for its answer and returns as soon as it is answered or ends; when the time runs out it returns the activity unchanged, so repeat it to wait longer. Without wait, a few seconds between requests is plenty. Too many waits open at once return 429 with code answer_wait.limit_exceeded. Agents on the MCP server can call wait_for_answer with the slug instead. Each option comes back carrying the signed answer url the server filled in when it stored the url-less options (the token is shortened to ... here) and method: "POST". The two forms mix freely: a "More info" option can carry a webhook while "Approve" and "Deny" stay server-recorded.

Example: An agent asking before it acts

Create the activity once, then push the question. This is the webhook form -- both options point at the agent's own endpoint:

curl -X POST https://api.pushward.app/activities \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "approval-request",
    "name": "Approval Needed"
  }'

curl -X PATCH https://api.pushward.app/activities/approval-request \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
    "state": "ongoing",
    "content": {
      "template": "approval",
      "state": "Send the follow-up email to Brightlane?",
      "source": "Agent",
      "icon": "sparkles",
      "accent_color": "green",
      "details": [
        { "label": "To", "value": "[email protected]" },
        { "label": "Subject", "value": "Q3 proposal follow-up" }
      ],
      "options": [
        { "id": "send", "title": "Send", "style": "primary",
          "url": "https://agent.example/hooks/brightlane", "body": "{\"decision\":\"send\"}" },
        { "id": "deny", "title": "Deny", "style": "secondary",
          "url": "https://agent.example/hooks/brightlane", "body": "{\"decision\":\"deny\"}" }
      ]
    }
  }'

Drop the URLs and the same question becomes server-recorded -- nothing to host, nothing exposed; the agent polls the activity instead:

{
  "state": "ongoing",
  "content": {
    "template": "approval",
    "state": "Promote 1.11.0 to production?",
    "source": "Forgejo CI",
    "icon": "shippingbox.fill",
    "accent_color": "blue",
    "options": [
      { "id": "promote", "title": "Promote", "style": "primary" },
      { "id": "hold", "title": "Hold", "style": "secondary" }
    ]
  }
}

Either form takes a deadline; here nobody answering within five minutes counts as "hold":

{ "content": { "end_date": 1788221100, "on_expire": "hold" } }

Several questions on one card

One approval card can ask up to ten questions in turn, the way a release checklist or a coding agent asks them. Send step and step_count with the first question, wait for its answer, then PATCH the next question onto the same card with step one higher. The card stays on the Lock Screen between questions, with its place shown as 2/3.

• step and step_count come together or not at all, with 1 <= step <= step_count <= 10. Anything else is a 422.
• A changed step starts a new answer round: the stored answer is cleared and server-recorded options get new answer URLs, even when they are the same Yes and No as last time. Changing step_count alone does not.
• An answer on a step before the last is pushed to every device and returned to a waiting GET ?wait=, but the card stays ongoing for the next question. The answer on the last step ends the card a few seconds later, as on a card with one question.
• An answered step that never gets its next question is ended 10 minutes after the answer, or at end_date if that comes first. It ends with that answer.
• end_date and on_expire are one deadline for the whole card. When it passes on an open question the default is recorded and the card ends, on whatever step it is.
• iOS cannot change the activity name in place, so give the card a name that fits every question ("Release 2.4", "Claude Code"). What changes per step goes in state, details, options and icon.
• On iPhone the server puts 2/3 in the trailing ear of the compact Dynamic Island, unless you set compact_trailing_label or compact_trailing_icon yourself.

A release that asks three things, server-recorded, so there is nothing to host. Create the card, then ask the first question:

curl -X POST https://api.pushward.app/activities \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "release-2-4",
    "name": "Release 2.4"
  }'

curl -X PATCH https://api.pushward.app/activities/release-2-4 \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
    "state": "ongoing",
    "content": {
      "template": "approval",
      "state": "Run the database migrations now?",
      "source": "Forgejo CI",
      "icon": "shippingbox.fill",
      "step": 1,
      "step_count": 3,
      "options": [
        { "id": "yes", "title": "Yes", "style": "primary" },
        { "id": "no", "title": "No", "style": "secondary" }
      ]
    }
  }'

curl "https://api.pushward.app/activities/release-2-4?wait=25" \
  -H "Authorization: Bearer hlk_YOUR_TOKEN"

{
  "state": "ongoing",
  "content": {
    "template": "approval",
    "state": "Run the database migrations now?",
    "step": 1,
    "step_count": 3,
    ...
    "answer": { "option": "yes", "at": 1788220800, "by": "user" }
  }
}

Repeat the wait until content.answer is set. The card is still ongoing: it shows the answer and "Next question..." until you send the next one. Check that content.step is the step you asked before acting on the answer, then patch the next question in. The options here are the same as before; the new step is what starts a new round:

curl -X PATCH https://api.pushward.app/activities/release-2-4 \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
    "content": {
      "state": "Tag 2.4.0 and push the tag?",
      "step": 2,
      "step_count": 3,
      "options": [
        { "id": "yes", "title": "Yes", "style": "primary" },
        { "id": "no", "title": "No", "style": "secondary" }
      ]
    }
  }'

Wait the same way, then ask the last question. Its answer is the card's outcome, and the card ends on its own a few seconds after it:

curl -X PATCH https://api.pushward.app/activities/release-2-4 \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
    "content": {
      "state": "Publish the release notes?",
      "step": 3,
      "step_count": 3,
      "options": [
        { "id": "now", "title": "Now", "style": "primary", "icon": "checkmark.circle" },
        { "id": "draft", "title": "As draft", "icon": "doc.text" },
        { "id": "skip", "title": "Skip", "style": "destructive", "icon": "xmark.circle" }
      ]
    }
  }'

Use Cases

• Agents -- "Should I send this?": the script blocks on a human decision
• Deploy gates -- pipeline green, "Staging, prod, or skip?" from the Lock Screen
• Home automation -- "Unlock the gate for the courier?" pointing at Home Assistant webhooks
• Paging -- "Ack the incident?" with a deadline that escalates when it expires