> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create workflow
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
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.
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.
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.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/workflows
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- ApiKeyAuth: []
paths:
/api/apps/{app_id}/workflows:
post:
summary: Create workflow
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
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.
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.
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.
operationId: create_workflow_api_apps__app_id__workflows_post
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the app whose workflows you want to work with.
title: App Id
description: ID of the app whose workflows you want to work with.
example: 6820f3a4e7b91d003c45a1f2
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWorkflowRequest'
responses:
'200':
description: The created workflow.
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowResponse'
'401':
description: Missing or invalid credentials.
'402':
description: >-
This workspace's plan does not include workflows. Upgrade to Builder
or above.
'403':
description: >-
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':
description: Another workflow on this app already uses this name.
'422':
description: >-
The definition or trigger is not valid. The body lists what is
wrong.
components:
schemas:
CreateWorkflowRequest:
properties:
name:
type: string
title: Name
description: >-
Name for the workflow. Must be unique among the app's workflows that
are not archived.
example: Email me new signups
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: What the workflow is for, in your own words.
example: Sends an email whenever a User record is created.
definition:
additionalProperties: true
type: object
title: Definition
description: >-
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.
example:
do: []
document:
dsl: 1.0.0
name: notify
version: 1.0.0
trigger:
additionalProperties: true
type: object
title: Trigger
description: >-
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.
example:
config:
cron_expression: 0 9 * * *
timezone: UTC
trigger_type: scheduled
change_summary:
anyOf:
- type: string
- type: 'null'
title: Change Summary
description: >-
Note describing this version, kept in the workflow's version
history.
example: Initial version
type: object
required:
- name
- definition
- trigger
title: CreateWorkflowRequest
WorkflowResponse:
properties:
id:
type: string
title: Id
description: ID of the workflow.
example: 68b1c0d4e7b91d003c45a1f2
app_id:
type: string
title: App Id
description: ID of the app the workflow belongs to.
example: 6820f3a4e7b91d003c45a1f2
file_key:
anyOf:
- type: string
- type: 'null'
title: File Key
description: >-
Name of the workflow's file in the app's code. `null` on workflows
saved before files were kept.
example: email-me-new-signups
name:
type: string
title: Name
description: Name of the workflow.
example: Email me new signups
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: What the workflow is for.
example: Sends an email whenever a User record is created.
status:
type: string
title: Status
description: 'Whether the workflow runs: `active`, `inactive`, or `archived`.'
example: active
status_reason:
anyOf:
- type: string
- type: 'null'
title: Status Reason
description: >-
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.
example: consecutive_failures
current_version_id:
anyOf:
- type: string
- type: 'null'
title: Current Version Id
description: >-
Version the workflow runs today, as the SHA-256 hash of that
definition. `null` until a definition is saved.
example: 9f2c1a7b3e5d84f60c1b2a9e7d4f8c3b6a5e2d1f0c9b8a7e6d5c4b3a2f1e0d9c
trigger:
additionalProperties: true
type: object
title: Trigger
description: >-
What starts the workflow. The trigger sits under `config`, keyed by
`trigger_type`.
example:
config:
cron_expression: 0 9 * * *
timezone: UTC
trigger_type: scheduled
app_type_context:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: App Type Context
description: Which app surface the workflow was authored against.
example:
app_type: user_app
last_run_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Run At
description: When the workflow last started running. `null` before its first run.
example: '2026-08-25T09:12:44Z'
last_run_status:
anyOf:
- type: string
- type: 'null'
title: Last Run Status
description: >-
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`.
example: success
consecutive_failures:
type: integer
title: Consecutive Failures
description: Runs that have failed in a row. Resets on the next success.
default: 0
example: 0
total_runs:
type: integer
title: Total Runs
description: Runs the workflow has started, ever.
default: 0
example: 48
successful_runs:
type: integer
title: Successful Runs
description: Runs that finished successfully, ever.
default: 0
example: 44
failed_runs:
type: integer
title: Failed Runs
description: Runs that ended in an error, ever.
default: 0
example: 3
created_date:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created Date
description: When the workflow was created.
example: '2026-07-02T11:04:00Z'
updated_date:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated Date
description: When the workflow was last changed.
example: '2026-08-20T16:31:00Z'
created_by:
anyOf:
- type: string
- type: 'null'
title: Created By
description: Email of whoever created the workflow.
example: you@example.com
definition:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Definition
description: >-
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.
example:
do: []
document:
dsl: 1.0.0
name: notify
version: 1.0.0
type: object
required:
- id
- app_id
- name
- status
title: WorkflowResponse
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````