Start a workflow the agent's release allows
Starts a GitHub Actions run of workflow (a file under .github/workflows/) on ref in the session's repository. The agent's release must turn on actions under the workspace ceiling and list the pair in its allowlist: ref matches an entry's ref glob (* does not cross /), or is the catalog entry's branch when the entry has no ref. A ref under agent/ is refused (agent_ref_refused) whatever the allowlist says. A refused call never reaches GitHub and leaves a dispatch_workflow receipt with the reason_code.
inputs go to GitHub as given and are never stored: the receipt keeps the workflow, the ref and the input names only. A run GitHub reports back is recorded with the session, so a later rerun can prove the platform started it; run is null when GitHub did not name it.
Scope: sessions:write (API key or cookie session). Idempotency-Key: ignored.
AuthorizationBearer <token>For servers and scripts: an API key sent as an HTTP bearer token, Bearer <key>. It holds exactly the scopes it was issued with; a key issued before scopes existed holds none. It never needs the CSRF header, and it cannot manage agents, members, teams or API keys. Issue one in the web console under Settings → API keys; each operation names the scope it needs.
Scope: sessions:write
id*stringThe session's id.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidX-Requested-With?"werft-web"Required with a cookie session: the literal werft-web.
"werft-web"application/json- body
workflow*string^[A-Za-z0-9._-]+\.ya?ml$ref*string^(?!refs\/)(?!\/)(?!.*\/\/)(?!.*\.\.)[^\s~^:?*[\\]+(?<![/.])$1 <= length <= 255inputs?Started; the receipt and the run GitHub named.
application/json- response
receipt_id*string^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidrun*|nullcurl -X POST 'https://example.com/v1/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/github/workflow-dispatches' \ -H 'Content-Type: application/json' \ -d '{ "workflow": "deploy-preview.yml", "ref": "main", "inputs": { "environment": "preview" }}'{ "receipt_id": "c4a1e9d2-7b3f-4e8a-a6c5-1d2e3f4a5b6c", "run": { "id": 9012345678, "html_url": "https://github.com/acme/sample-app/actions/runs/9012345678" }}