Schedule a recurring workflow run

Create a schedule trigger source, enable it, and follow the continuous Workflow Run it fires into.

This guide creates a schedule trigger source on a Workflow, enables it, and reads the continuous Workflow Run that fires on each occurrence. The schedule decides when work starts; the Workflow's revisions decide what the work does.

Before you start

You need:

  • a published Workflow;
  • an API key with the automation manage capability and the workflow.trigger_source.control action grant. The reads in this guide require the automation read capability, which manage also covers.

See API keys to create a key, and API overview for capability levels, action grants, and the error contract.

Set the origin and key once for the examples, then read the Workflow id:

export API_ORIGIN="https://api.openfactor.ai"
export API_KEY="<your API key>"

WORKFLOW_ID=$(curl -sS "$API_ORIGIN/v1/workflows?limit=20" \
  -H "Authorization: Bearer $API_KEY" | jq -r '.workflows[0].workflow.id')

Steps

1. Create the schedule trigger source

POST /v1/workflows/{workflowId}/trigger-sources accepts a title and a config. A schedule config carries a spec and an occurrencePolicy:

  • spec.cron is an array of cron expressions.
  • spec.intervalMs is a fixed delay in milliseconds.
  • spec.timezone is the zone the cron expressions are read in. It defaults to UTC. Interval specs do not use it.

Provide cron, intervalMs, or both. When both are present, the sooner firing wins. A spec that is neither gives 400 workflow_runtime_invalid; so does a cron expression the scheduler cannot parse.

SOURCE=$(curl -sS -X POST \
  "$API_ORIGIN/v1/workflows/$WORKFLOW_ID/trigger-sources" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekday morning triage",
    "config": {
      "type": "schedule",
      "spec": { "cron": ["0 9 * * 1-5"], "timezone": "UTC" },
      "occurrencePolicy": "skip"
    }
  }')

TRIGGER_SOURCE_ID=$(printf '%s' "$SOURCE" | jq -r '.triggerSource.id')

The response is 201 with the new triggerSource. It starts disabled: enabled is false, workflowRunId is null, and nextFireAt is null. lockVersion starts at 1 and changes on every update, enable, and disable; send the current value as expectedLockVersion whenever a call requires it.

2. Read the trigger sources

GET /v1/workflows/{workflowId}/trigger-sources lists the sources for the Workflow. Filter with ?type=schedule.

curl -sS "$API_ORIGIN/v1/workflows/$WORKFLOW_ID/trigger-sources?type=schedule" \
  -H "Authorization: Bearer $API_KEY" |
  jq '.triggerSources[] | {id, title, enabled, nextFireAt, lockVersion}'

Once the source is enabled, nextFireAt is the next time it will fire.

3. Enable it

POST /v1/workflow-trigger-sources/{triggerSourceId}/enable takes no body. It starts one continuous Workflow Run pinned to the Workflow's latest revision and binds the source to it. Every later occurrence fires into that same Run, so the Run stays active between firings.

ENABLED=$(curl -sS -X POST \
  "$API_ORIGIN/v1/workflow-trigger-sources/$TRIGGER_SOURCE_ID/enable" \
  -H "Authorization: Bearer $API_KEY")

printf '%s' "$ENABLED" |
  jq '{enabled: .triggerSource.enabled,
       workflowRunId: .triggerSource.workflowRunId,
       nextFireAt: .triggerSource.nextFireAt}'

LOCK_VERSION=$(printf '%s' "$ENABLED" | jq -r '.triggerSource.lockVersion')

Enable advances lockVersion twice - once when it claims the source and once when it binds the Run - so read the version from this response instead of reusing the create value.

Follow the Run with GET /v1/workflow-runs/{workflowRunId} as described in Workflow and Run lifecycle.

Enabling a generic Workflow schedule does not consume a recurring Factory schedule slot. Only the schedule that a Factory activation creates consumes one; see plan limits.

4. Choose an occurrence policy

occurrencePolicy decides what happens when an occurrence arrives while an earlier one is still running:

PolicyBehavior
allow_allAdmit every occurrence independently.
buffer_allQueue each occurrence behind the latest one still running.
buffer_oneKeep at most one queued occurrence; coalesce the rest into it.
skipDrop the occurrence while an earlier one is still running.

Use skip for a frequent schedule where only the newest work matters, and buffer_all when every occurrence must eventually run.

5. Update, disable, or delete

PATCH /v1/workflow-trigger-sources/{triggerSourceId} changes title or config under patch, guarded by the current expectedLockVersion:

UPDATED=$(curl -sS -X PATCH \
  "$API_ORIGIN/v1/workflow-trigger-sources/$TRIGGER_SOURCE_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"expectedLockVersion\": $LOCK_VERSION,
    \"patch\": {
      \"config\": {
        \"type\": \"schedule\",
        \"spec\": { \"cron\": [\"0 9 * * 1-5\"], \"timezone\": \"UTC\" },
        \"occurrencePolicy\": \"buffer_all\"
      }
    }
  }")

LOCK_VERSION=$(printf '%s' "$UPDATED" | jq -r '.triggerSource.lockVersion')

POST /v1/workflow-trigger-sources/{triggerSourceId}/disable requires the current expectedLockVersion. It stops admitting new firings and asks the bound Workflow Run to finish, so occurrences already buffered still drain:

curl -sS -X POST \
  "$API_ORIGIN/v1/workflow-trigger-sources/$TRIGGER_SOURCE_ID/disable" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"expectedLockVersion\": $LOCK_VERSION}"

DELETE /v1/workflow-trigger-sources/{triggerSourceId} returns 204. A source must be disabled before you can delete it.

Errors

  • 400 workflow_runtime_invalid - the spec has neither cron nor intervalMs, a cron expression does not parse, or the request body is malformed.
  • 401 - the request is missing a valid API key.
  • 403 - the key lacks the automation manage capability or the workflow.trigger_source.control action grant.
  • 404 - the Workflow or trigger source does not exist for the key.
  • 409 workflow_runtime_conflict - expectedLockVersion is stale, the source is still enabled when you delete it, or the source is bound to a different Workflow revision.

See API overview for the full error contract.

Next steps