---
title: "Create Action Endpoint"
method: POST
path: "/v1/actions"
tags: ["actions"]
---

# Create Action Endpoint

`POST /v1/actions`

## Request

- Base URL: `https://api.actionbox.cloud`
- URL: `https://api.actionbox.cloud/v1/actions`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string, nullable
- `X-Actionbox-Blocking` boolean
- `X-Actionbox-Client` string, nullable
- `authorization` string, nullable

## Request body

- ActionCreate
  - `chat_delivery` 'inherit' | 'disabled'
  - `context_request_mode` 'unsupported' | 'poll' | 'callback'
  - `title` string, required
  - `description` string
  - `priority` 'low' | 'normal' | 'high' | 'urgent'
  - `open_url` string, uri, nullable
  - `dedupe_key` string, nullable
  - `callback_url` string, uri, nullable
  - `controls` ActionControl[]
    - `key` string, required
    - `label` string, required
    - `kind` 'callback' | 'link' | 'actionbox', required
    - `url` string, uri, nullable
    - `destructive` boolean
    - `expires_at` string, date-time, nullable
  - `expires_at` string, date-time, nullable
  - `on_expire` union
    - ReturnExpiredOutcome
      - `type` 'return_expired'
    - ResolveOnExpireOutcome
      - `type` 'resolve', required
      - `response` union, required
        - BooleanResponse
          - `type` 'boolean', required
          - `value` boolean, required
        - TextResponse
          - `type` 'text', required
          - `value` string, required
        - IntegerResponse
          - `type` 'integer', required
          - `value` integer, required
        - NumberResponse
          - `type` 'number', required
          - `value` union, required
            - integer
            - number
        - RatingResponse
          - `type` 'rating', required
          - `value` integer, required
        - SingleChoiceResponse
          - `type` 'single_choice', required
          - `value` string, required
        - MultiChoiceResponse
          - `type` 'multi_choice', required
          - `value` string[], required
        - FormResponse
          - `type` 'form', required
          - `values` object, required
      - `reason` string, nullable
  - `context` union[]
    - union
      - KeyValueContext
        - `title` string, nullable
        - `type` 'key_value', required
        - `items` object, required
      - TextualContext
        - `title` string, nullable
        - `type` 'code' | 'diff' | 'logs' | 'command', required
        - `content` string, required
        - `language` string, nullable
      - JsonContext
        - `title` string, nullable
        - `type` 'json', required
        - `value` unknown, required
      - MetricsContext
        - `title` string, nullable
        - `type` 'metrics', required
        - `items` MetricItem[], required
          - `label` string, required
          - `value` union, required
            - string
            - integer
            - number
          - `unit` string, nullable
      - LinksContext
        - `title` string, nullable
        - `type` 'links', required
        - `items` LinkItem[], required
          - `label` string, required
          - `url` string, uri, required
  - `decision_class` string, nullable
  - `decision_context` DecisionContext
    - `schema_version` 1
    - `reason` string, required
    - `current_state` string, nullable
    - `proposed_change` string, required
    - `expected_effect` string, nullable
    - `risk_level` 'unknown' | 'low' | 'medium' | 'high' | 'critical', required
    - `risk_summary` string, nullable
    - `reversibility` 'unknown' | 'reversible' | 'partially_reversible' | 'irreversible', required
    - `rollback_plan` string, nullable
    - `affected_scope` string[]
  - `options` ActionOptionInput[]
    - `id` string, required
    - `label` string, required
    - `style` 'default' | 'primary' | 'destructive'
  - `interaction` union
    - BooleanInteraction
      - `label` string, required
      - `type` 'boolean', required
      - `true_label` string
      - `false_label` string
    - SingleChoiceInteraction
      - `label` string, required
      - `type` 'single_choice', required
      - `options` ActionOptionInput[], required
        - `id` string, required
        - `label` string, required
        - `style` 'default' | 'primary' | 'destructive'
    - MultiChoiceInteraction
      - `label` string, required
      - `type` 'multi_choice', required
      - `options` ActionOptionInput[], required
        - `id` string, required
        - `label` string, required
        - `style` 'default' | 'primary' | 'destructive'
      - `min_selections` integer
      - `max_selections` integer, nullable
    - TextInteraction
      - `label` string, required
      - `type` 'text', required
      - `placeholder` string, nullable
      - `multiline` boolean
      - `min_length` integer
      - `max_length` integer
    - IntegerInteraction
      - `label` string, required
      - `type` 'integer', required
      - `min` integer, nullable
      - `max` integer, nullable
      - `step` integer
      - `unit` string, nullable
    - NumberInteraction
      - `label` string, required
      - `type` 'number', required
      - `min` union
        - integer
        - number
      - `max` union
        - integer
        - number
      - `step` union
        - integer
        - number
      - `unit` string, nullable
    - RatingInteraction
      - `label` string, required
      - `type` 'rating', required
      - `min` integer
      - `max` integer
      - `low_label` string, nullable
      - `high_label` string, nullable
    - FormInteraction
      - `label` string, required
      - `type` 'form', required
      - `fields` union[], required
        - union
          - FormBooleanField
            - `label` string, required
            - `type` 'boolean', required
            - `true_label` string
            - `false_label` string
            - `id` string, required
            - `required` boolean
          - FormSingleChoiceField
            - `label` string, required
            - `type` 'single_choice', required
            - `options` ActionOptionInput[], required
              - …
            - `id` string, required
            - `required` boolean
          - FormMultiChoiceField
            - `label` string, required
            - `type` 'multi_choice', required
            - `options` ActionOptionInput[], required
              - …
            - `min_selections` integer
            - `max_selections` integer, nullable
            - `id` string, required
            - `required` boolean
          - FormTextField
            - `label` string, required
            - `type` 'text', required
            - `placeholder` string, nullable
            - `multiline` boolean
            - `min_length` integer
            - `max_length` integer
            - `id` string, required
            - `required` boolean
          - FormIntegerField
            - `label` string, required
            - `type` 'integer', required
            - `min` integer, nullable
            - `max` integer, nullable
            - `step` integer
            - `unit` string, nullable
            - `id` string, required
            - `required` boolean
          - FormNumberField
            - `label` string, required
            - `type` 'number', required
            - `min` union
              - …
            - `max` union
              - …
            - `step` union
              - …
            - `unit` string, nullable
            - `id` string, required
            - `required` boolean
          - FormRatingField
            - `label` string, required
            - `type` 'rating', required
            - `min` integer
            - `max` integer
            - `low_label` string, nullable
            - `high_label` string, nullable
            - `id` string, required
            - `required` boolean
  - `metadata` object
  - `visibility` 'workspace' | 'restricted'
  - `reviewer_user_ids` string[]
  - `reviewer_emails` string[]
  - `approval_policy` ApprovalPolicy
    - `schema_version` 1
    - `mode` 'any' | 'all' | 'quorum', required
    - `required_approvals` integer, nullable
    - `approval_option_id` string, nullable
    - `rejection_option_id` string, nullable
    - `allow_source_override` boolean
  - `assignee_user_id` string, nullable
  - `assignee_email` string, nullable
  - `run_id` string, nullable

## Response `201`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/actionbox/apis/actionbox-api.md) · [All operations](https://skmtc.dev/actionbox/apis/actionbox-api/llms.txt) · [OpenAPI document](https://skmtc.dev/actionbox/apis/actionbox-api/revisions/bfb9b622e725?raw)