Skip to content
Pilotoo
v0.1

0.1.0 Latest

ChangelogHow versions work

Triggers

Introduction

Section titled “Introduction”

Every workflow has exactly one trigger node. The trigger takes no config, and its output is the run input. The node type records how the workflow is meant to start.

Trigger Started by
trigger.manual POST /workflows/:id/runs, or the workflow_run agent tool
trigger.webhook POST /workflows/:id/hooks/:token
trigger.schedule A schedule whose target is the workflow

Starting a run by hand

Section titled “Starting a run by hand”

Post the input. The answer is 201 with the run as running, and the run continues in the background.

Terminal window
curl -X POST $API/workflows/$ID/runs -H 'content-type: application/json' \
  -d '{"input":{"userId":7}}'

A workflow that does not validate answers 400 and no run exists.

Starting a run from a webhook

Section titled “Starting a run from a webhook”

Give the workflow a trigger.webhook node, then mint a token as the workflow’s owner.

Terminal window
# Mint (or rotate) the token: 201 { "webhookToken": "..." }
curl -X POST -H "Authorization: Bearer $TOKEN" https://host/workflows/$ID/webhook


# Fire it: no identity, the token is the credential. 202 { "runId": "..." }
curl -X POST -H "Content-Type: application/json" \
  -d '{"event":"deploy"}' https://host/workflows/$ID/hooks/$WEBHOOK_TOKEN

The JSON body of the request becomes the run input. Read the run back with GET /workflows/:id/runs/:runId as the owner.

How the hook behaves

Section titled “How the hook behaves”
Behaviour Detail
Token 32 random bytes, base64url. One per workflow; minting a new one replaces the old
Visibility GET /workflows/:id shows webhookToken (null when there is none) to the owner only
Identity The run belongs to the workflow’s owner and carries no credentials, so agent or tool nodes that need the caller’s own bearer see none
Authorization The token is compared in constant time and is the whole authorization, plus one check: the owner must still hold a workflow role at fire time

Every failure answers the same 404 { "message": "Not found." }, so a caller cannot tell the cases apart:

  • a wrong or cleared token;
  • an unknown workflow;
  • a workflow without a trigger.webhook node;
  • a workflow that does not validate;
  • an owner who lost the workflow role.

Running a workflow on a schedule

Section titled “Running a workflow on a schedule”

A schedule can target a workflow instead of an agent. At each cron fire, the workflow runs as the schedule’s owner with a fixed input.

{
  "name": "Nightly report",
  "cron": "0 3 * * *",
  "timezone": "Europe/Rome",
  "target": { "kind": "workflow", "workflowId": "<workflow id>", "input": { "full": true } }
}
  • input is optional (limited in JSON length) and becomes the run input.
  • Name a workflow or an agent and prompt, not both. Creating a schedule for a workflow the owner cannot see is refused.
  • The schedule’s run mirrors the workflow run: running or paused until the workflow ends. Its identifiers are the workflow run’s, so read details under GET /workflows/:id/runs/:runId. There is no conversation.
  • A schedule is suspended if its owner loses the workflow role or the workflow is no longer available to them.

Letting an agent start a workflow

Section titled “Letting an agent start a workflow”

With workflowTools: true, an agent that lists workflow_list and workflow_run in its tools can start any workflow its user owns. See Agent tools.

Next steps

Section titled “Next steps”