---
title: "Create Action"
method: POST
path: "/workspaces/{workspace_id}/actions"
tags: ["actions"]
---

# Create Action

`POST /workspaces/{workspace_id}/actions`

## Request

- Base URL: `https://platform.tracecat.com/api`
- URL: `https://platform.tracecat.com/api/workspaces/{workspace_id}/actions`
- Auth: one of:
  - API key in cookie `fastapiusersauth`
  - HTTP bearer

Create a new action for a workflow.

## Path parameters

- `workspace_id` string, uuid, required

## Request body

- ActionCreate
  - `workflow_id` union, required
    - string
    - string
  - `type` string, required
  - `title` string, required
  - `description` string
  - `inputs` string
  - `control_flow` object, nullable
    - `run_if` string, nullable
    - `for_each` union
      - string
      - string[]
    - `join_strategy` 'any' | 'all'
    - `retry_policy` ActionRetryPolicy
      - `max_attempts` integer: Total number of execution attempts. 0 means unlimited, 1 means no retries.
      - `timeout` integer: Timeout for the action in seconds. Agent-backed AI actions clamp to the deployment's agent timeout bounds (see ActionStatement).
      - `retry_until` string, nullable: Retry until a specific condition is met.
    - `start_delay` number: Delay before starting the action in seconds. If `wait_until` is also provided, the `wait_until` timer will take precedence.
    - `wait_until` string, nullable: Wait until a specific date and time before starting. Overrides `start_delay` if both are provided.
    - `environment` string, nullable: Override environment for this action's execution
    - `tunnel` string, nullable: Workspace tunnel to route this action's HTTP(S) traffic through
    - `mask_output` boolean: If true, redact this action's result in workflow execution API responses while preserving internal workflow data flow between actions.
    - `unsafe_disable_secret_error_withholding` boolean: Legacy field, ignored. Error diagnostics always mask known secrets and observed secret-derived values.
  - `position_x` number
  - `position_y` number
  - `upstream_edges` ActionEdge[]
    - `source_id` string, required
    - `source_type` 'trigger' | 'udf', required
    - `source_handle` 'success' | 'error'

## Response `200`

Successful Response

- ActionReadMinimal
  - `id` string, uuid, required
  - `workflow_id` string, required
  - `type` string, required
  - `title` string, required
  - `description` string, required
  - `status` string, required

## Other responses

- `422`: Validation Error

---

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