Use the API

Trigger workflows programmatically from external systems, scripts, or CI/CD pipelines using an API token.

Prerequisites

• A fully configured workflow ready to run
• Access to Settings → API Tokens

Steps

1. Create an API token

1. Go to Settings → API Tokens and click + (New token).
2. Name it (e.g. "CI pipeline").
3. Choose its scope:
   • No project graphs → organization-wide (can trigger any workflow).
   • One or more project graphs → limited to workflows in those projects.
   • A single workflow → can only trigger that one workflow (most restrictive — recommended for a single automation).
4. Save, then copy the token — it's shown only once. (You can copy just the token from the token's MCP tab, which also has a reveal toggle and, for workflow-pinned tokens, a ready-to-paste curl.)

2. Trigger a workflow run

Send a POST to /api/v1/trigger with the token as a Bearer header:

curl -X POST https://orqo.ooopps.com/api/v1/trigger \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": 42}'

The body currently accepts only workflow_id. (Passing run inputs/payloads is not yet supported.)

3. Handle the response

A successful trigger returns 201 Created with the new run's identifiers:

{
  "workflow_run_id": 238,
  "session_id": "abc-123-def"
}

The run executes asynchronously — the API returns immediately after starting it. Use workflow_run_id to find the run in the UI later.

4. Understand token scope

The trigger endpoint enforces the token's scope:

Token scope	Result
Workflow not in the token's projects	403 Forbidden
Workflow pinned, different workflow requested	403 Forbidden
Unknown or cross-organization workflow_id	404 Not Found
Missing / invalid token	401 Unauthorized

Scope a token as tightly as the job needs — a single-workflow token can do nothing else, even if leaked.

5. Check run status

Find the run in the workflow's Runs view in the UI, or with the debug tooling:

bin/rails "debug:run[238]"

Common patterns

• CI/CD pipeline — trigger a review workflow after each deploy.
• Scheduled job — an external scheduler (cron, GitHub Actions) fires a workflow on a cadence.
• Form submission — a backend posts to the trigger endpoint to start an onboarding or triage workflow.

Troubleshooting

Symptom	Check
401	Token missing, expired, revoked, or mistyped.
403	The token isn't scoped to that workflow/project.
404	workflow_id is wrong or belongs to another organization.
Run created but fails immediately	Workflow misconfigured (missing LLM, agents, or credentials).

What's next

• API Access — endpoint reference
• MCP Gateway — the same token also exposes project knowledge graphs to AI clients
• Monitor Runs — track API-triggered runs