---
title: "Create an action"
method: POST
path: "/actions"
tags: ["actions"]
---

# Create an action

`POST /actions`

## Query parameters

- `spaceId` string, required — Space ID

## Headers

- `Authorization` string, required
- `X-Disable-Hooks` 'true', required

## Request body

- TypeCommonsAPIActionConfig
  - `slug` string — **This is deprecated. Use `operation` instead.**
  - `operation` string — This will become the job operation that is triggered
  - `mode` 'foreground' | 'background' | 'toolbarBlocking' — Foreground actions will prevent interacting with the resource until complete
  - `tooltip` string — A tooltip that appears when hovering the action button
  - `messages` TypeCommonsActionMessage[]
    - `type` 'error' | 'info', required
    - `content` string, required
  - `type` string — **This is deprecated.**
  - `description` string — The text that appears in the dialog after the action is clicked.
  - `schedule` 'weekly' | 'daily' | 'hourly'
  - `primary` boolean — A primary action will be more visibly present, whether in Sheet or Workbook.
  - `confirm` boolean — Whether to show a modal to confirm the action
  - `icon` string — Icon will work on primary actions. It will only accept an already existing Flatfile design system icon.
  - `requireAllValid` boolean — **This is deprecated. Use `constraints` instead.**
  - `requireSelection` boolean — **This is deprecated. Use `constraints` instead.**
  - `inputForm` TypeCommonsInputForm
    - `type` 'simple', required
    - `fields` TypeCommonsInputField[], required
      - `key` string, required — Unique key for a Field.
      - `label` string, required — Visible name of a Field.
      - `description` string — Brief description below the name of the Field.
      - `type` string, required — Field Types inform the user interface how to sort and display data.
      - `defaultValue` unknown
      - `config` TypeCommonsInputConfig
        - `options` TypeCommonsInputEnumPropertyOption[], required
          - `label` string — A visual label for this option, defaults to value if not provided
          - `description` string — A short description for this option
          - `color` string — An optional color to assign this option
          - `icon` string — A reference pointer to a previously registered icon
          - `meta` object — An arbitrary JSON object to be associated with this option and made available to hooks
          - `value` unknown, required
      - `constraints` TypeCommonsInputConstraint[] — Indicate additional validations that will be applied to the Field.
        - `type` 'required', required
  - `constraints` TypeCommonsActionConstraint[] — A limitation or restriction on the action.
    - union
      - object
        - `type` 'hasAllValid', required — Discriminator value: hasAllValid
        - `ignoreSelection` boolean
      - object
        - `type` 'hasSelection', required — Discriminator value: hasSelection
      - object
        - `type` 'hasData', required — Discriminator value: hasData
      - object
        - `type` 'hasColumnEnabled', required — Discriminator value: hasColumnEnabled
  - `mount` union
    - object
      - `type` 'sheet', required — Discriminator value: sheet
      - `slugs` string[]
    - object
      - `type` 'workbook', required — Discriminator value: workbook
      - `slugs` string[]
    - object
      - `type` 'field', required — Discriminator value: field
      - `keys` string[]
    - object
      - `type` 'document', required — Discriminator value: document
    - object
      - `type` 'file', required — Discriminator value: file
  - `guide` TypeCommonsGuide
    - `content` string, required — Markdown guidance for this action
  - `guardrail` TypeCommonsGuardrail
    - `content` string, required — Markdown guardrail for this action
  - `createdFrom` string — Action ID
  - `lastPropagatedAt` string, date-time — The last time this action was propagated to a workbook
  - `deletedAt` string, date-time — The time this action was deleted
  - `invalidConditionalMessaging` boolean — When enabled, shows dynamic confirmation messages based on record validation status instead of the static description
  - `validRecordsMessage` string — Custom message to show when all records are valid (only used when invalidConditionalMessaging is true)
  - `invalidRecordsMessage` string — Custom message to show when there are invalid records (only used when invalidConditionalMessaging is true)
  - `label` string, required — The text on the Button itself
  - `targetId` string, required

## Response `200`

Response with status 200

- TypeActionsAPIActionResponse
  - `data` TypeCommonsAPIAction, required
    - `slug` string — **This is deprecated. Use `operation` instead.**
    - `operation` string — This will become the job operation that is triggered
    - `mode` 'foreground' | 'background' | 'toolbarBlocking' — Foreground actions will prevent interacting with the resource until complete
    - `tooltip` string — A tooltip that appears when hovering the action button
    - `messages` TypeCommonsActionMessage[]
      - `type` 'error' | 'info', required
      - `content` string, required
    - `type` string — **This is deprecated.**
    - `description` string — The text that appears in the dialog after the action is clicked.
    - `schedule` 'weekly' | 'daily' | 'hourly'
    - `primary` boolean — A primary action will be more visibly present, whether in Sheet or Workbook.
    - `confirm` boolean — Whether to show a modal to confirm the action
    - `icon` string — Icon will work on primary actions. It will only accept an already existing Flatfile design system icon.
    - `requireAllValid` boolean — **This is deprecated. Use `constraints` instead.**
    - `requireSelection` boolean — **This is deprecated. Use `constraints` instead.**
    - `inputForm` TypeCommonsInputForm
      - `type` 'simple', required
      - `fields` TypeCommonsInputField[], required
        - `key` string, required — Unique key for a Field.
        - `label` string, required — Visible name of a Field.
        - `description` string — Brief description below the name of the Field.
        - `type` string, required — Field Types inform the user interface how to sort and display data.
        - `defaultValue` unknown
        - `config` TypeCommonsInputConfig
          - `options` TypeCommonsInputEnumPropertyOption[], required
            - `label` string — A visual label for this option, defaults to value if not provided
            - `description` string — A short description for this option
            - `color` string — An optional color to assign this option
            - `icon` string — A reference pointer to a previously registered icon
            - `meta` object — An arbitrary JSON object to be associated with this option and made available to hooks
            - `value` unknown, required
        - `constraints` TypeCommonsInputConstraint[] — Indicate additional validations that will be applied to the Field.
          - `type` 'required', required
    - `constraints` TypeCommonsActionConstraint[] — A limitation or restriction on the action.
      - union
        - object
          - `type` 'hasAllValid', required — Discriminator value: hasAllValid
          - `ignoreSelection` boolean
        - object
          - `type` 'hasSelection', required — Discriminator value: hasSelection
        - object
          - `type` 'hasData', required — Discriminator value: hasData
        - object
          - `type` 'hasColumnEnabled', required — Discriminator value: hasColumnEnabled
    - `mount` union
      - object
        - `type` 'sheet', required — Discriminator value: sheet
        - `slugs` string[]
      - object
        - `type` 'workbook', required — Discriminator value: workbook
        - `slugs` string[]
      - object
        - `type` 'field', required — Discriminator value: field
        - `keys` string[]
      - object
        - `type` 'document', required — Discriminator value: document
      - object
        - `type` 'file', required — Discriminator value: file
    - `guide` TypeCommonsGuide
      - `content` string, required — Markdown guidance for this action
    - `guardrail` TypeCommonsGuardrail
      - `content` string, required — Markdown guardrail for this action
    - `createdFrom` string — Action ID
    - `lastPropagatedAt` string, date-time — The last time this action was propagated to a workbook
    - `deletedAt` string, date-time — The time this action was deleted
    - `invalidConditionalMessaging` boolean — When enabled, shows dynamic confirmation messages based on record validation status instead of the static description
    - `validRecordsMessage` string — Custom message to show when all records are valid (only used when invalidConditionalMessaging is true)
    - `invalidRecordsMessage` string — Custom message to show when there are invalid records (only used when invalidConditionalMessaging is true)
    - `label` string, required — The text on the Button itself
    - `id` string, required — Action ID
    - `targetId` string, required
    - `updatedAt` string, date-time, required
    - `createdAt` string, date-time, required

---

[API](https://skmtc.net/flatfile/apis/api-reference.md) · [All operations](https://skmtc.net/flatfile/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/flatfile/api-reference/revisions/9d3a9979cd96/schema)