Overview

Author an app’s workflows and read their runs with the Base44 Apps API

The Apps API is in beta. Its endpoints and responses may change.

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 workflow endpoints let you author workflows, start and pause them, run one on demand, and read what happened on every run.

Use these endpoints 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 access token. See Authentication to get one.
• 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.
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.

Branches

Creating, updating, archiving, restoring, and toggling a workflow’s status are only allowed on the app’s main branch. Called from any other branch, the call is rejected, in either direction of toggling, including just pausing a workflow. Switch to main, or merge the branch, before calling one of these from a branch.

Reading a workflow, listing its versions, checking a definition, running a workflow, and reading or cancelling a run all work from any branch.

Triggers

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

{
  "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.

The trigger_type field is one of:

• scheduled: fires on a cron schedule.
• entity: fires when an entity record is created, updated, or deleted.
• connector: fires on an incoming connector webhook.
• in_app_agent: fires on in-app agent events, for example a conversation starting.
• app_user_auth: fires when an app user signs up or logs in.
• app_publish: fires when the app is published from the app editor.
• app_payment: fires on a payment event from the app’s connected payment provider.
• webhook: fires on an inbound POST to a workspace webhook’s listener URL.
• goal_file: fires when the owner edits the one managed goal note that owns the workflow. This only applies to goal-owned Superagent workflows.

Tasks and activities

A definition’s do list is made of tasks, and every task is one of three types. A call task invokes an activity, for example sending an email. A switch task branches on a condition. A wait task pauses for a duration or until a time.

An activity is the specific thing a call task invokes. Which activities exist depends on the app, unlike the three task types, which are the same everywhere. Validate a workflow definition reports both: the fixed set of task types, and the activities available on the app you called it for.

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.

Workflow status

A workflow’s own status is active, inactive, or archived. Active workflows run on their trigger. Inactive ones are paused: the schedule and trigger are torn down, but the workflow and its definition are kept, and Toggle workflow status starts it again. Archived workflows are soft-deleted, and Restore workflow brings one back.

The status_reason field explains a status change Base44 made on its own, as one of consecutive_failures, end_condition_reached, migration_activation_failed, or workflows_not_available. It’s null whenever you changed the status yourself, through Create, Update, Toggle, Archive, or Restore.

The last_run_status field reports how the workflow’s most recent run ended, as success, failed, or cancelled. A run’s own status, from Get workflow run or List runs for a workflow, uses a different vocabulary: running, completed, failed, or cancelled. The same finished run reports completed there and success here. Branch on the field you actually read.

Run 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 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, stated as the base limit for a Free-plan workspace in the description of its 429 response. Reads are generous, and the endpoints that cost real work are tight: running a workflow, generating suggestions, and explaining a failed run each allow 5 requests per minute. Listing a workflow’s versions and reading one back share a single allowance. See Rate limits for how the limit scales with your plan.

Endpoints

Management

• List workflows: List the app’s workflows.
• Create workflow: Create a workflow and start it running.
• Get workflow: Read a workflow, including the definition it currently runs.
• Update workflow: Change the fields you send. A changed definition saves a new version.
• Archive workflow: Stop a workflow and keep its history.
• Restore workflow: Restore an archived workflow and try to start it again.
• Toggle workflow status: Switch a workflow between active and inactive.
• Validate a workflow definition: Check a definition for problems without saving it.

Versions

• List workflow versions: List a workflow’s saved versions, newest first.
• Get workflow version: Read one version’s full definition.

Runs

• Get workflow run-now options: See what running a workflow now needs.
• Run a workflow now: Run a workflow without waiting for its trigger.
• List workflow runs for an app: List runs across every workflow on the app.
• List runs for a workflow: List one workflow’s runs.
• Get workflow run: Read one run with its step-by-step log.
• Analyze a failed workflow run: Get a plain-language explanation of why a run failed.
• Cancel a workflow run: Request that a running workflow stop.

Insights

• Suggest workflows: Get suggestions for workflows worth building.
• Get workflow stats: Count each workflow’s runs over a time window.