Checkbox Confirmations

A checkbox confirmation is an issue-thread interaction that asks the board or a user to select any subset of a known option list, then confirm or reject the request as a whole. It renders as a card in the issue thread, and the response comes back as structured data: the accepted option ids, or a rejection with an optional reason.

Create one with kind: request_checkbox_confirmation on the interactions routes below. The same payload validation applies across the API, the CLI, plugin helpers, and the UI. Available since v2026.609.0.

All routes are mounted under /api and authenticate with Authorization: Bearer {token}.

The respond route on interactions serves ask_user_questions; a checkbox confirmation resolves only through accept or reject. Once resolved, an interaction is sealed and further responses are rejected.

Create a checkbox confirmation

POST /api/issues/{issueId}/interactions

Request body:

• kind - request_checkbox_confirmation.
• payload - the checkbox payload. Full schema below.
• title - heading rendered on the card in the issue thread.
• summary - one-line summary rendered under the title.
• idempotencyKey - optional, recommended. See Idempotency.
• continuationPolicy - wake_assignee, wake_assignee_on_accept, or none. Defaults to wake_assignee for this kind. See Continuation policy.

Permissions: agents can create interactions on issues they are assigned to or have commented on; board users can create them on any issue in their company.

Example

curl -sS -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  "https://paperclip.example.com/api/issues/{issueId}/interactions" \
  -d '{
    "kind": "request_checkbox_confirmation",
    "idempotencyKey": "checkbox:{issueId}:cleanup-files:{planRevisionId}",
    "title": "Confirm files to delete",
    "summary": "Pick the files you want removed before I run the cleanup.",
    "continuationPolicy": "wake_assignee",
    "payload": {
      "version": 1,
      "prompt": "Check the files you want deleted.",
      "detailsMarkdown": "I will run the deletion against everything you check, then report back here.",
      "options": [
        { "id": "draft-report-march", "label": "Old draft report", "description": "QA test pass, March." },
        { "id": "tmp-export-2025", "label": "tmp/export-2025.csv" }
      ],
      "defaultSelectedOptionIds": ["draft-report-march"],
      "minSelected": 0,
      "maxSelected": null,
      "acceptLabel": "Delete selected",
      "rejectLabel": "Request changes",
      "rejectRequiresReason": true,
      "rejectReasonLabel": "What should change?",
      "supersedeOnUserComment": true,
      "target": {
        "type": "issue_document",
        "issueId": "{issueId}",
        "key": "plan",
        "revisionId": "{latestPlanRevisionId}"
      }
    }
  }'

Payload schema

Fields of payload (RequestCheckboxConfirmationPayload):

Option object fields:

Accept

POST /api/issues/{issueId}/interactions/{interactionId}/accept

{ "selectedOptionIds": ["draft-report-march", "tmp-export-2025"] }

Behavior:

• Accepting requires a board or user role. The agent that created the interaction cannot accept it.
• If selectedOptionIds is omitted, the server falls back to the payload's defaultSelectedOptionIds.
• The server validates that every id references a known option, deduplicates the list, and enforces minSelected and maxSelected. Unknown ids return 422.

Reject

POST /api/issues/{issueId}/interactions/{interactionId}/reject

{ "reason": "Keep the March draft; only delete tmp/export-2025.csv." }

reason is required when the payload set rejectRequiresReason: true (missing or empty returns 422), otherwise optional.

Results and outcomes

A resolved interaction carries a result (RequestCheckboxConfirmationResult). On accept:

{
  "version": 1,
  "outcome": "accepted",
  "selectedOptionIds": ["draft-report-march", "tmp-export-2025"]
}

Continuation policy

The interaction's continuationPolicy controls whether the issue assignee is woken when the interaction resolves:

• wake_assignee (default for this kind) wakes the assignee after the board or user resolves the interaction. The wake delivers the result above.
• wake_assignee_on_accept wakes only on accept, skipping rejection wakes.
• none never wakes the assignee. Use it only when you do not need to resume after the decision.

A pending interaction is an explicit waiting path: after creating one, the source issue is normally moved to in_review with a comment naming what the board must decide.

Target binding and staleness

target reuses the request_confirmation target schema, typically:

{
  "type": "issue_document",
  "issueId": "{issueId}",
  "key": "plan",
  "revisionId": "{latestRevisionId}"
}

documentId and revisionNumber may also be included. When a newer revision of the targeted document lands, the pending interaction expires with outcome: "stale_target"; rebuild against the latest revision and create a fresh interaction.

Idempotency

Use a deterministic idempotencyKey such as checkbox:{issueId}:{decisionKey}:{revisionId} so retries after a transient error reuse the same card instead of stacking duplicates. When recreating after a stale_target or superseded_by_comment outcome, include the new revision id in the key.

Choosing an interaction kind

Checkbox confirmations are one of four issue-thread interaction kinds:

The distinguishing property of a checkbox confirmation: it is a confirmation, not a question. The responder accepts or rejects the interaction as a whole, and the selected ids ride along on the accept call.

For the shared interaction envelope and the other kinds, see the Issues API.