Skip to main content
Any published workflow can be started from outside Champ with a single HTTP request. This is the way to kick off automation from your own backend, a cron job, or another tool — no UI, no webhook required to start. The flow is:
  1. Create an API token in the dashboard.
  2. POST to the runs endpoint with your workflow ID and an input payload.
  3. Poll the run, or subscribe to a webhook, to get the result.

​
Create an API token

  1. Go to Tokens in the dashboard.
  2. Click Create Token, choose the API scope, and click Create.
  3. Copy the token immediately — it’s shown once and cannot be retrieved again. API tokens look like api_xxxxxxxx….
The token is scoped to your organization. Treat it as a secret: store it in an environment variable or secrets manager, and delete it from the Tokens page if it’s ever exposed.
Tokens are tied to the organization, not to a single workflow — one API token can trigger any published workflow in your org.

​
Find your workflow ID

Open the workflow in the dashboard. The numeric ID is shown on the workflow view page and is the last segment of its URL (https://dash.champ.ai/app/workflows/<WORKFLOW_ID>). You’ll use it in the request path below.

​
Trigger a run

Send a POST request to the runs endpoint: 
curl -X POST https://api.champ.ai/api/external/v1/workflows/{WORKFLOW_ID}/runs \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"input": {"key": "value"}}'
​
WORKFLOW_ID
integer
required
Path parameter. The numeric ID of a published workflow.
​
Authorization
string
required
Request header. Bearer <YOUR_API_TOKEN> — an API-scoped token from the Tokens page.
​
input
object
Request body. A JSON object passed to the workflow’s Start node. Provide the fields your workflow expects; omit it (or pass {}) for workflows that take no input.
The run starts immediately and the request returns right away — execution continues asynchronously. The response is the newly created run: 
{
  "workflow_run": {
    "id": 456,
    "workflow_id": 123,
    "trigger_id": 789,
    "status": "pending",
    "mode": "live",
    "workflow_version": 4,
    "workflow_draft": false,
    "input": { "key": "value" },
    "output": null,
    "created_at": "2026-05-19T12:34:56Z",
    "updated_at": "2026-05-19T12:34:56Z",
    "url": "https://api.champ.ai/api/external/v1/workflows/123/runs/456"
  }
}
FieldDescription
idUnique run ID. Use it to poll for status.
statusRun status — see run statuses. Newly created runs are pending.
inputThe input payload the run was started with.
outputThe workflow’s final output. null until the run reaches a terminal state.
urlAbsolute URL to poll this run’s status.
Only published workflows can be triggered via the API. Ticketing workflows cannot be started this way — they run off ticket events instead.

​
Check run status

Because runs execute asynchronously, the POST response will usually show status: "pending" with output: null. Poll the run — using the url from the response, or by constructing it yourself — until it reaches a terminal state: 
curl https://api.champ.ai/api/external/v1/workflows/{WORKFLOW_ID}/runs/{RUN_ID} \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
The response is the same workflow_run shape as above. Once status is completed, the output field holds the workflow’s result.

​
Run statuses

StatusMeaning
pendingRun created, not yet started.
in_progressRun is executing.
completedRun finished successfully — output is populated.
failedRun terminated with an error.
suspendedRun is paused, waiting on an external signal.
skippedRun did not execute.
Instead of polling, set up a webhook subscription to be notified when a run reaches completed or failed. The webhook payload includes the run’s input and output.

​
Errors

StatusWhen
401Missing or invalid Authorization header.
404Workflow or run not found — or the workflow isn’t published.
422The workflow can’t be run via the external API (e.g. ticketing workflows).
Errors return a JSON body with an error message.