> ## Documentation Index > Fetch the complete documentation index at: https://docs.tracecat.com/llms.txt > Use this file to discover all available pages before exploring further. # Replace Workflow Draft > Replace the workflow's draft with the supplied document. Validates the definition, then rewrites the action graph, layout, schedules, and case trigger in one transaction. Omit ``schedules`` from the document to leave the workflow's schedules untouched (they can be managed independently via ``/schedules``). Publishing is separate: call ``POST /workflows/{id}/commit`` afterwards to create a new version. ## OpenAPI ````yaml https://platform.tracecat.com/api/openapi.json put /workspaces/{workspace_id}/workflows/{workflow_id}/draft openapi: 3.1.0 info: title: Tracecat API summary: Tracecat API description: The open source AI automation platform for security teams and agents. termsOfService: >- https://docs.google.com/document/d/e/2PACX-1vQvDe3SoVAPoQc51MgfGCP71IqFYX_rMVEde8zC4qmBCec5f8PLKQRdxa6tsUABT8gWAR9J-EVs2CrQ/pub contact: name: Tracecat Founders email: founders@tracecat.com license: name: AGPL-3.0 url: https://www.gnu.org/licenses/agpl-3.0.html version: '1' servers: - url: /api security: [] tags: - name: public description: Public facing endpoints - name: workflows description: Workflow management - name: actions description: Action management - name: triggers description: Workflow triggers - name: secrets description: Secret management - name: variables description: Workspace variable management paths: /workspaces/{workspace_id}/workflows/{workflow_id}/draft: put: tags: - workflows summary: Replace Workflow Draft description: |- Replace the workflow's draft with the supplied document. Validates the definition, then rewrites the action graph, layout, schedules, and case trigger in one transaction. Omit ``schedules`` from the document to leave the workflow's schedules untouched (they can be managed independently via ``/schedules``). Publishing is separate: call ``POST /workflows/{id}/commit`` afterwards to create a new version. operationId: workflows-replace_workflow_draft parameters: - name: workspace_id in: path required: true schema: type: string format: uuid title: Workspace Id - name: workflow_id in: path required: true schema: anyOf: - type: string pattern: wf_[0-9a-zA-Z]+ - type: string pattern: wf-[0-9a-f]{32} title: Workflow Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkflowDraftUpdate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/WorkflowDraftRead' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyCookie: [] - ServiceAccountApiKeyBearer: [] components: schemas: WorkflowDraftUpdate: properties: document: $ref: '#/components/schemas/WorkflowEditDocument-Input' base_revision: anyOf: - type: string - type: 'null' title: Base Revision type: object required: - document title: WorkflowDraftUpdate description: >- Wholesale replacement of a workflow draft. ``document`` is the full desired draft state (metadata, definition, layout, schedules, case trigger). ``schedules`` is optional: when omitted, the workflow's existing schedules are left untouched so they can be owned by the standalone ``/schedules`` resource; when present, they are replaced. Other omitted sections fall back to their defaults and are treated as changed. When ``base_revision`` is set, the update is rejected with 409 if the current draft revision differs. WorkflowDraftRead: properties: workflow_id: type: string pattern: wf_[0-9a-zA-Z]+ title: Workflow Id draft_revision: type: string title: Draft Revision document: $ref: '#/components/schemas/WorkflowEditDocument-Output' type: object required: - workflow_id - draft_revision - document title: WorkflowDraftRead description: Canonical editable draft document plus its content-hash revision. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError WorkflowEditDocument-Input: properties: metadata: $ref: '#/components/schemas/WorkflowEditMetadata' definition: $ref: '#/components/schemas/WorkflowEditDefinition-Input' layout: $ref: '#/components/schemas/WorkflowLayout' schedules: items: $ref: '#/components/schemas/WorkflowSchedule' type: array title: Schedules case_trigger: anyOf: - $ref: '#/components/schemas/CaseTriggerConfig' - type: 'null' additionalProperties: false type: object required: - metadata - definition title: WorkflowEditDocument WorkflowEditDocument-Output: properties: metadata: $ref: '#/components/schemas/WorkflowEditMetadata' definition: $ref: '#/components/schemas/WorkflowEditDefinition-Output' layout: $ref: '#/components/schemas/WorkflowLayout' schedules: items: $ref: '#/components/schemas/WorkflowSchedule' type: array title: Schedules case_trigger: anyOf: - $ref: '#/components/schemas/CaseTriggerConfig' - type: 'null' additionalProperties: false type: object required: - metadata - definition title: WorkflowEditDocument ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError WorkflowEditMetadata: properties: title: type: string maxLength: 100 minLength: 3 title: Title description: type: string maxLength: 1000 title: Description status: type: string enum: - online - offline title: Status alias: anyOf: - type: string - type: 'null' title: Alias error_handler: anyOf: - type: string - type: 'null' title: Error Handler additionalProperties: false type: object required: - title - description - status title: WorkflowEditMetadata WorkflowEditDefinition-Input: properties: entrypoint: $ref: '#/components/schemas/DSLEntrypoint-Input' actions: items: $ref: '#/components/schemas/ActionStatement-Input' type: array title: Actions config: $ref: '#/components/schemas/DSLConfig-Input' returns: anyOf: - {} - type: 'null' title: Returns additionalProperties: false type: object title: WorkflowEditDefinition WorkflowLayout: properties: trigger: anyOf: - $ref: '#/components/schemas/LayoutPosition' - type: 'null' viewport: anyOf: - $ref: '#/components/schemas/LayoutViewport' - type: 'null' actions: items: $ref: '#/components/schemas/LayoutActionPosition' type: array title: Actions type: object title: WorkflowLayout WorkflowSchedule: properties: status: type: string enum: - online - offline title: Status default: online inputs: anyOf: - additionalProperties: true type: object - type: 'null' title: Inputs cron: anyOf: - type: string - type: 'null' title: Cron every: anyOf: - type: string format: duration - type: 'null' title: Every offset: anyOf: - type: string format: duration - type: 'null' title: Offset start_at: anyOf: - type: string format: date-time - type: 'null' title: Start At end_at: anyOf: - type: string format: date-time - type: 'null' title: End At timeout: type: number title: Timeout default: 0 type: object title: WorkflowSchedule CaseTriggerConfig: properties: status: type: string enum: - online - offline title: Status default: offline event_types: items: $ref: '#/components/schemas/CaseEventType' type: array title: Event Types tag_filters: items: type: string type: array title: Tag Filters type: object title: CaseTriggerConfig WorkflowEditDefinition-Output: properties: entrypoint: $ref: '#/components/schemas/DSLEntrypoint-Output' actions: items: $ref: '#/components/schemas/ActionStatement-Output' type: array title: Actions config: $ref: '#/components/schemas/DSLConfig-Output' returns: anyOf: - {} - type: 'null' title: Returns additionalProperties: false type: object title: WorkflowEditDefinition DSLEntrypoint-Input: properties: ref: anyOf: - type: string - type: 'null' title: Ref description: The entrypoint action ref expects: anyOf: - additionalProperties: $ref: '#/components/schemas/ExpectedField-Input' type: object - type: 'null' title: Expects description: >- Expected trigger input schema. Use this to specify the expected shape of the trigger input. type: object title: DSLEntrypoint ActionStatement-Input: properties: id: anyOf: - type: string format: uuid - type: 'null' title: Id description: >- The action ID. If this is populated means there is a corresponding actionin the database `Action` table. ref: type: string pattern: ^[a-z0-9_]+$ title: Ref description: Unique reference for the task description: type: string title: Description default: '' action: type: string pattern: ^[a-z0-9_.]+$ title: Action description: Action type. Equivalent to the UDF key. args: additionalProperties: true type: object title: Args description: Arguments for the action depends_on: items: type: string type: array title: Depends On description: Task dependencies run_if: anyOf: - type: string - type: 'null' title: Run If description: Condition to run the task for_each: anyOf: - type: string - items: type: string type: array - type: 'null' title: For Each description: Iterate over a list of items and run the task for each item. retry_policy: $ref: '#/components/schemas/ActionRetryPolicy' description: Retry policy for the action. start_delay: type: number title: Start Delay description: >- Delay before starting the action in seconds. If `wait_until` is also provided, the `wait_until` timer will take precedence. default: 0 wait_until: anyOf: - type: string - type: 'null' title: Wait Until description: >- Wait until a specific date and time before starting. Overrides `start_delay` if both are provided. join_strategy: $ref: '#/components/schemas/JoinStrategy' description: >- The strategy to use when joining on this task. By default, all branches must complete successfully before the join task can complete. default: all environment: anyOf: - type: string - type: 'null' title: Environment description: >- Override environment for this action's execution. Can be a template expression. tunnel: anyOf: - type: string maxLength: 63 minLength: 1 - type: 'null' title: Tunnel description: >- Name of a workspace tunnel to route this action's HTTP(S) traffic through. Overrides the workflow's default tunnel. mask_output: type: boolean title: Mask Output description: >- If true, redact this action's result in workflow execution API responses while preserving internal workflow data flow between actions. default: false unsafe_disable_secret_error_withholding: type: boolean title: Unsafe Disable Secret Error Withholding description: >- Legacy field, ignored. Error diagnostics always mask known secrets and observed secret-derived values. default: false type: object required: - ref - action title: ActionStatement DSLConfig-Input: properties: scheduler: type: string enum: - static - dynamic title: Scheduler description: The type of scheduler to use. default: dynamic environment: type: string title: Environment description: >- The workflow's target execution environment. This is used to isolate secrets across different environments.If not provided, the default environment (default) is used. default: default timeout: type: number title: Timeout description: >- Workflow timeout in seconds. If set to 0, the workflow has no timeout. default: 0 tunnel: anyOf: - type: string maxLength: 63 minLength: 1 - type: 'null' title: Tunnel description: Default workspace tunnel for actions that do not set their own. type: object title: DSLConfig description: |- This is the runtime configuration for the workflow. Activities don't need access to this. LayoutPosition: properties: x: anyOf: - type: number - type: 'null' title: X 'y': anyOf: - type: number - type: 'null' title: 'Y' position: anyOf: - additionalProperties: type: number type: object - type: 'null' title: Position type: object title: LayoutPosition LayoutViewport: properties: x: anyOf: - type: number - type: 'null' title: X 'y': anyOf: - type: number - type: 'null' title: 'Y' zoom: anyOf: - type: number - type: 'null' title: Zoom type: object title: LayoutViewport LayoutActionPosition: properties: ref: type: string title: Ref x: anyOf: - type: number - type: 'null' title: X 'y': anyOf: - type: number - type: 'null' title: 'Y' position: anyOf: - additionalProperties: type: number type: object - type: 'null' title: Position type: object required: - ref title: LayoutActionPosition CaseEventType: type: string enum: - case_created - case_updated - case_closed - case_reopened - case_viewed - priority_changed - severity_changed - status_changed - fields_changed - assignee_changed - attachment_created - attachment_deleted - tag_added - tag_removed - payload_changed - task_created - task_deleted - task_status_changed - task_priority_changed - task_workflow_changed - task_assignee_changed - dropdown_value_changed - table_row_linked - table_row_unlinked - comment_created - comment_updated - comment_deleted - comment_reply_created - comment_reply_updated - comment_reply_deleted - parent_changed - sub_cases_added - sub_cases_removed title: CaseEventType description: Case activity type values. DSLEntrypoint-Output: properties: ref: anyOf: - type: string - type: 'null' title: Ref description: The entrypoint action ref expects: anyOf: - additionalProperties: $ref: '#/components/schemas/ExpectedField-Output' type: object - type: 'null' title: Expects description: >- Expected trigger input schema. Use this to specify the expected shape of the trigger input. type: object title: DSLEntrypoint ActionStatement-Output: properties: ref: type: string pattern: ^[a-z0-9_]+$ title: Ref description: Unique reference for the task description: type: string title: Description default: '' action: type: string pattern: ^[a-z0-9_.]+$ title: Action description: Action type. Equivalent to the UDF key. args: additionalProperties: true type: object title: Args description: Arguments for the action depends_on: items: type: string type: array title: Depends On description: Task dependencies run_if: anyOf: - type: string - type: 'null' title: Run If description: Condition to run the task for_each: anyOf: - type: string - items: type: string type: array - type: 'null' title: For Each description: Iterate over a list of items and run the task for each item. retry_policy: $ref: '#/components/schemas/ActionRetryPolicy' description: Retry policy for the action. start_delay: type: number title: Start Delay description: >- Delay before starting the action in seconds. If `wait_until` is also provided, the `wait_until` timer will take precedence. default: 0 wait_until: anyOf: - type: string - type: 'null' title: Wait Until description: >- Wait until a specific date and time before starting. Overrides `start_delay` if both are provided. join_strategy: $ref: '#/components/schemas/JoinStrategy' description: >- The strategy to use when joining on this task. By default, all branches must complete successfully before the join task can complete. default: all environment: anyOf: - type: string - type: 'null' title: Environment description: >- Override environment for this action's execution. Can be a template expression. tunnel: anyOf: - type: string maxLength: 63 minLength: 1 - type: 'null' title: Tunnel description: >- Name of a workspace tunnel to route this action's HTTP(S) traffic through. Overrides the workflow's default tunnel. mask_output: type: boolean title: Mask Output description: >- If true, redact this action's result in workflow execution API responses while preserving internal workflow data flow between actions. default: false unsafe_disable_secret_error_withholding: type: boolean title: Unsafe Disable Secret Error Withholding description: >- Legacy field, ignored. Error diagnostics always mask known secrets and observed secret-derived values. default: false type: object required: - ref - action title: ActionStatement DSLConfig-Output: properties: environment: type: string title: Environment description: >- The workflow's target execution environment. This is used to isolate secrets across different environments.If not provided, the default environment (default) is used. default: default timeout: type: number title: Timeout description: >- Workflow timeout in seconds. If set to 0, the workflow has no timeout. default: 0 tunnel: anyOf: - type: string maxLength: 63 minLength: 1 - type: 'null' title: Tunnel description: Default workspace tunnel for actions that do not set their own. type: object title: DSLConfig description: |- This is the runtime configuration for the workflow. Activities don't need access to this. ExpectedField-Input: properties: type: type: string title: Type description: anyOf: - type: string - type: 'null' title: Description default: title: Default enum: anyOf: - items: type: string type: array - type: 'null' title: Enum optional: anyOf: - type: boolean - type: 'null' title: Optional additionalProperties: false type: object required: - type title: ExpectedField description: |- Schema for a field in a template action's expects definition. Note: The default field uses a sentinel to distinguish between "no default specified" (required field) and "default is explicitly None" (optional field). ActionRetryPolicy: properties: max_attempts: type: integer title: Max Attempts description: >- Total number of execution attempts. 0 means unlimited, 1 means no retries. default: 1 timeout: type: integer title: Timeout description: >- Timeout for the action in seconds. Agent-backed AI actions clamp to the deployment's agent timeout bounds (see ActionStatement). default: 300 retry_until: anyOf: - type: string - type: 'null' title: Retry Until description: Retry until a specific condition is met. type: object title: ActionRetryPolicy JoinStrategy: type: string enum: - any - all title: JoinStrategy ExpectedField-Output: additionalProperties: true type: object securitySchemes: APIKeyCookie: type: apiKey in: cookie name: fastapiusersauth ServiceAccountApiKeyBearer: type: http description: Tracecat service account API key. scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.