> ## 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.

# Workflows API Overview

> Get started with the Base44 Workflows API

<Note>
  The Workflows API is in beta. Its endpoints and responses may change.
</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: on a schedule, or when something happens in the app. The Workflows API lets you author workflows, start and pause them, run one on demand, and read what happened on every run.

Use the Workflows API to:

* Create, read, update, and archive an app's workflows.
* Check a definition before you save it.
* Start a workflow, pause it, or run one immediately.
* Read run history, step by step, and cancel a run in flight.
* Read a workflow's saved versions, including the one a past run executed.

## Prerequisites

* A personal API key. See [Authentication](/developers/references/app-management/get-started/authentication) to get one. These endpoints share the App Management API's `api_key` header and base URL.
* An app you can edit, on a plan that includes workflows.

## App ID

Endpoints that act on a specific app include the app's ID in the URL path as `app_id`.

**To get your app ID:**

1. Go to [app.base44.com](https://app.base44.com/).
2. Open your app in the app editor.
3. Copy the app ID from the editor URL: `"https://app.base44.com/apps/<app_id>/editor"`.

## Workflows need a Builder plan

Authoring, activating, and running workflows require a workspace on Builder or above. Those endpoints answer 402 when the plan does not include workflows.

Reading and archiving stay open on any plan, so a workspace that has lost the capability can still see its workflows and clean them up. Pausing a running workflow is deliberately open too, so you can stop one you can no longer start.

Apps that still run the older automations engine answer 403 on every endpoint here.

## Triggers

The trigger goes inside `config`, and its `trigger_type` picks the kind:

```json theme={null}
{
  "config": {
    "trigger_type": "scheduled",
    "cron_expression": "0 9 * * *",
    "timezone": "UTC"
  }
}
```

Add a top-level `condition` to skip a dispatch unless a jq expression over the trigger payload is truthy.

## Versions are content hashes

Every definition change saves a new immutable version, and the version ID is the SHA-256 hash of that definition rather than a Base44 object ID. A run records the version it executed, so you can always read back the definition a past run actually ran, even after the workflow moved on.

## Two different status vocabularies

A workflow's own `status` is `active`, `inactive`, or `archived`, and its `last_run_status` is `success`, `failed`, or `cancelled`.

A run's `status` is `running`, `completed`, `failed`, or `cancelled`. A finished run reports `completed`, while the workflow that owns it reports `success` for the same run. Branch on the field you actually read.

## Running a workflow yourself

Some triggers carry a payload that refers to real data in the app, and a synthetic payload cannot stand in for it. Call [Get workflow run-now options](/api-reference/get-workflow-run-now-options) first: it tells you whether this workflow needs you to replay a previous run's payload, and which runs you can replay.

Runs you start this way execute for real and consume credits. They are recorded as test runs, which is what keeps them out of the replay list later.

## Rate limits

Each endpoint has its own per-minute limit per app. Reads are generous, and the endpoints that cost real work are tight: running a workflow and generating suggestions allow 5 requests per minute, and explaining a failed run allows 5. Each endpoint's reference page states its own limit.