Interaction and Decision Types

Model acknowledgements, typed choices, required text, numeric input, ratings, and forms for human decisions.

ActionBox lets the calling system define the response shape before a person reviews an Action. The API validates the submitted response against that shape and returns it as a typed value.

Informational Actions and boolean decisions

An Action with neither options nor interaction is informational. The dashboard shows Acknowledge, and the decision endpoint accepts an empty body. ActionBox does not infer Approve and Reject choices for an Action that has no response schema.

For a true/false decision, define a boolean interaction explicitly:

{
  "title": "Approve the customer refund?",
  "interaction": {
    "type": "boolean",
    "label": "Approve a $4,850 refund for this customer?",
    "true_label": "Approve",
    "false_label": "Reject"
  }
}

The response is a typed envelope:

{
  "type": "boolean",
  "value": true
}

Choice interactions

Concise single-choice options

The top-level options field is a shorthand for a single_choice interaction. It accepts at most three unique options, each with an id, label, and optional style (default, primary, or destructive):

{
  "title": "How should we continue?",
  "options": [
    { "id": "scale_up", "label": "Scale up", "style": "primary" },
    { "id": "hold", "label": "Hold", "style": "default" }
  ]
}

Use interaction.type = "single_choice" when you need more than three options. A typed single-choice interaction accepts 1–50 unique options:

{
  "title": "Choose a rollout strategy",
  "interaction": {
    "type": "single_choice",
    "label": "Select one strategy",
    "options": [
      { "id": "canary", "label": "Canary" },
      { "id": "gradual", "label": "Gradual rollout" },
      { "id": "hold", "label": "Hold" }
    ]
  }
}

For a single-choice Action, the decision request can use either option_id: "canary" or the typed response {"type":"single_choice","value":"canary"}. The ID must match an available option.

Multi-choice

Use multi_choice when the reviewer can select more than one option. It accepts 1–50 options and optional min_selections and max_selections bounds:

{
  "title": "Select the checks to rerun",
  "interaction": {
    "type": "multi_choice",
    "label": "Choose one or more checks",
    "options": [
      { "id": "unit", "label": "Unit tests" },
      { "id": "integration", "label": "Integration tests" },
      { "id": "security", "label": "Security scan" }
    ],
    "min_selections": 1,
    "max_selections": 3
  }
}

The response value is an array of option IDs, with no duplicates.

Text, numeric, and rating input

The API also supports these interaction types:

Type	Use it for	Constraints
`text`	A short or multiline written response	`min_length` and `max_length` from 0–2,000 characters
`integer`	A whole-number response	Optional `min`, `max`, `step`, and `unit`
`number`	A decimal or whole-number response	Optional numeric `min`, `max`, `step`, and `unit`
`rating`	A bounded integer rating	Integer `min` and `max` plus optional low/high labels

To require written justification, set min_length to at least 1, or include a required text field in a form.

{
  "title": "Explain the rollout decision",
  "interaction": {
    "type": "text",
    "label": "Why should the rollout proceed?",
    "placeholder": "Summarize the evidence for the reviewer.",
    "multiline": true,
    "min_length": 1,
    "max_length": 2000
  }
}

Forms

Use form to collect several typed values in one decision. A form contains 1–12 fields; field IDs must be unique. Each field can be boolean, choice, text, integer, number, or rating, and can be marked required.

{
  "title": "Approve and document the rollout",
  "interaction": {
    "type": "form",
    "label": "Complete the rollout review",
    "fields": [
      {
        "id": "decision",
        "type": "single_choice",
        "label": "What should happen?",
        "options": [
          { "id": "approve", "label": "Approve" },
          { "id": "hold", "label": "Hold" }
        ],
        "required": true
      },
      {
        "id": "reason",
        "type": "text",
        "label": "Reason",
        "multiline": true,
        "min_length": 1,
        "max_length": 2000,
        "required": true
      }
    ]
  }
}

The matching response is:

{
  "type": "form",
  "values": {
    "decision": "approve",
    "reason": "The canary completed without errors."
  }
}

Review code and diffs

Store code, SQL, logs, commands, or a diff as typed context when the reviewer needs to inspect the exact proposed change. Context supports up to 12 blocks; textual blocks can contain up to 20,000 characters each, and account plan limits may impose a lower total size.

{
  "title": "Review the index migration",
  "context": [
    {
      "type": "diff",
      "title": "Migration preview",
      "language": "sql",
      "content": "@@ -12,3 +12,4 @@\n CREATE TABLE invoices (\n   id UUID PRIMARY KEY,\n+  created_at TIMESTAMP NOT NULL\n );"
    }
  ],
  "options": [
    { "id": "apply", "label": "Apply migration" },
    { "id": "hold", "label": "Hold" }
  ]
}

The web dashboard displays these blocks as reviewable code context. Rendering details can vary by client; the context remains part of the Action payload and is covered by the Action fingerprint. Never put credentials, tokens, or other secrets in an Action or its context.

Resolve against the current schema

Submit action_version and the current fingerprint with the decision when possible. If the Action changed while it was being reviewed, ActionBox rejects the stale response so the person can review the latest context.

Next: Creating Actions or Decisions and outcomes.