---
title: "Create workflow"
method: POST
path: "/api/apps/{app_id}/workflows"
---

# Create workflow

`POST /api/apps/{app_id}/workflows`

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Creates a workflow and starts it running.

The new workflow is active immediately, so a scheduled trigger begins firing on its schedule and an event trigger starts listening as soon as this returns. Create it, then call [Toggle workflow status](/api-reference/toggle-workflow-status) if you want it paused instead.

Names are unique per app across everything that is not archived. Reusing a name returns a 409, so update the existing workflow with [Update workflow](/api-reference/update-workflow) rather than creating a second one. Saving also writes a matching file into the app's code, so the workflow shows up in the editor alongside everything else.

This endpoint is limited to 20 requests per minute.

<Note>A workflow is a definition plus a trigger. The definition is a CNCF Serverless Workflow v1.0 document describing the steps to run, and the trigger decides when they run. Both are free-form objects here, so check a definition with [Validate a workflow definition](/api-reference/validate-a-workflow-definition) before you save it.</Note>

<Warning>The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time. Send only the fields documented here. Other request fields are not supported and their behavior can change.</Warning>

## Path parameters

- `app_id` string, required — ID of the app whose workflows you want to work with.

## Request body

- CreateWorkflowRequest
  - `name` string, required — Name for the workflow. Must be unique among the app's workflows that are not archived.
  - `description` string, nullable — What the workflow is for, in your own words.
  - `definition` object, required — The steps to run, as a CNCF Serverless Workflow v1.0 document. Check it with [Validate a workflow definition](/api-reference/validate-a-workflow-definition) first.
  - `trigger` object, required — What starts the workflow. The trigger goes inside `config`, whose `trigger_type` picks the kind and whose remaining fields configure it. Add a top-level `condition` to skip a dispatch unless a jq expression over the payload is truthy.
  - `change_summary` string, nullable — Note describing this version, kept in the workflow's version history.

## Response `200`

The created workflow.

- WorkflowResponse
  - `id` string, required — ID of the workflow.
  - `app_id` string, required — ID of the app the workflow belongs to.
  - `file_key` string, nullable — Name of the workflow's file in the app's code. `null` on workflows saved before files were kept.
  - `name` string, required — Name of the workflow.
  - `description` string, nullable — What the workflow is for.
  - `status` string, required — Whether the workflow runs: `active`, `inactive`, or `archived`.
  - `status_reason` string, nullable — Why Base44 stopped the workflow itself, as a fixed code: `consecutive_failures`, `end_condition_reached`, `migration_activation_failed`, or `workflows_not_available`. `null` when you set the status yourself.
  - `current_version_id` string, nullable — Version the workflow runs today, as the SHA-256 hash of that definition. `null` until a definition is saved.
  - `trigger` object — What starts the workflow. The trigger sits under `config`, keyed by `trigger_type`.
  - `app_type_context` object, nullable — Which app surface the workflow was authored against.
  - `last_run_at` string, date-time, nullable — When the workflow last started running. `null` before its first run.
  - `last_run_status` string, nullable — How that run ended: `success`, `failed`, or `cancelled`. `null` before the first run. Note this is a different set of values from a run's own `status`, which reports `completed` rather than `success`.
  - `consecutive_failures` integer — Runs that have failed in a row. Resets on the next success.
  - `total_runs` integer — Runs the workflow has started, ever.
  - `successful_runs` integer — Runs that finished successfully, ever.
  - `failed_runs` integer — Runs that ended in an error, ever.
  - `created_date` string, date-time, nullable — When the workflow was created.
  - `updated_date` string, date-time, nullable — When the workflow was last changed.
  - `created_by` string, nullable — Email of whoever created the workflow.
  - `definition` object, nullable — The steps the workflow runs, as a CNCF Serverless Workflow v1.0 document. `null` when no version has been saved yet. Only this endpoint returns it; the list endpoint does not.

## Other responses

- `401` — Missing or invalid credentials.
- `402` — This workspace's plan does not include workflows. Upgrade to Builder or above.
- `403` — You don't have access to this app, the app does not exist, the app still runs the older automations engine instead of workflows, or you used a workspace API key. A missing app and an app you cannot reach are deliberately the same answer.
- `409` — Another workflow on this app already uses this name.
- `422` — The definition or trigger is not valid. The body lists what is wrong.

---

[API](https://skmtc.dev/idealspot/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/idealspot/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/idealspot/base44-app-management-api/revisions/31ef75eb64ab/schema)