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
automationmanagecapability and theworkflow.trigger_source.controlaction grant. The reads in this guide require theautomationreadcapability, whichmanagealso 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.cronis an array of cron expressions.spec.intervalMsis a fixed delay in milliseconds.spec.timezoneis the zone the cron expressions are read in. It defaults toUTC. 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:
| Policy | Behavior |
|---|---|
allow_all | Admit every occurrence independently. |
buffer_all | Queue each occurrence behind the latest one still running. |
buffer_one | Keep at most one queued occurrence; coalesce the rest into it. |
skip | Drop 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 neithercronnorintervalMs, 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 theautomationmanagecapability or theworkflow.trigger_source.controlaction grant.404- the Workflow or trigger source does not exist for the key.409 workflow_runtime_conflict-expectedLockVersionis 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
- Start a workflow - start a Workflow by hand and read its result
- Workflow and Run lifecycle - how Workflows, Workflow Runs, and Runs relate
- API overview - authentication, capabilities, and endpoint families
- API keys - create a key scoped to one task