Skip to main content

Use the API

Trigger workflows programmatically using ORQO's API endpoints. This allows external systems, scripts, and CI/CD pipelines to start workflow runs and receive results.

Prerequisites​

  • A fully configured workflow ready to run
  • API access to your ORQO instance

Steps​

1. Understand the API architecture​

ORQO exposes a REST API for programmatic interaction. The primary use case is triggering workflow runs from external systems:

External System → POST /api/v1/webhooks/:app_id → ORQO → Workflow Run

Webhook-based triggering uses the same inbound webhook infrastructure as app integrations, making it a consistent entry point for all external events.

2. Create an API app​

If you do not already have an app for API access, create one:

  1. Navigate to Settings > Apps
  2. Click New App
  3. Name it "API" or "External Trigger"
  4. Set capabilities to Receive
  5. Leave the adapter URL blank (uses DirectAdapter)
  6. Save the app

This creates a dedicated webhook endpoint for API calls.

API app configuration

3. Get the webhook endpoint​

Your API endpoint is:

POST https://your-orqo-domain.com/api/v1/webhooks/:app_id

Replace :app_id with the ID shown on the app card.

4. Trigger a workflow run​

Send a POST request to the webhook endpoint with a JSON payload:

curl -X POST https://your-orqo-domain.com/api/v1/webhooks/42 \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": 15,
    "task": "Research the latest trends in AI agent frameworks",
    "metadata": {
      "source": "ci-pipeline",
      "ref": "main"
    }
  }'
FieldRequiredDescription
workflow_idYesThe workflow to execute
taskNoTask description passed to the first stage
metadataNoArbitrary JSON stored with the run for tracing

5. Handle the response​

A successful trigger returns a 200 OK with the created run's details:

{
  "run_id": 238,
  "status": "pending",
  "workflow_id": 15,
  "started_at": null
}

The run starts asynchronously. Use the run ID to check status later.

info

Workflow runs execute asynchronously. The API returns immediately after creating the run -- it does not wait for the workflow to complete.

6. Check run status​

Query the run status by expanding the workflow's Runs & Triggers tab in the UI, or use the debug tools:

bin/rails "debug:run[238]"

This shows the run's current status, session ID, and timing information.

7. Secure your webhook endpoint​

For production use, configure signature verification on the API app to prevent unauthorized triggers:

  1. Add a signing secret to the app's credentials or config
  2. Configure the receive config with the signature header and algorithm
  3. Sign your API requests with HMAC using the shared secret
# Generate HMAC signature
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)

curl -X POST https://your-orqo-domain.com/api/v1/webhooks/42 \
  -H "Content-Type: application/json" \
  -H "X-Signature-256: sha256=$SIGNATURE" \
  -d "$PAYLOAD"
tip

Always use signature verification in production. Without it, anyone who discovers your webhook URL can trigger workflow runs.

8. Common integration patterns​

CI/CD pipeline: Trigger a review workflow after each deployment to analyze code changes and generate reports.

Scheduled external job: Use an external scheduler (cron, Airflow, GitHub Actions) to trigger ORQO workflows with specific parameters.

Chained workflows: One workflow's output triggers another workflow via the API, creating a pipeline of independent workflows.

Form submission: A web form posts to the webhook endpoint, triggering a workflow that processes the submission (e.g., customer onboarding, support ticket triage).

9. Debug API issues​

If your API calls are not triggering runs:

SymptomCheck
404 responseVerify the app ID in the URL is correct
401/403 responseCheck signature verification config
Run created but fails immediatelyCheck workflow configuration (missing LLM, agents, credentials)
No responseVerify ORQO is reachable and the URL is correct

What's next​

Learn more​