Start a run

Starts a run of a team, in one of two ways:

• On a realm (realm_id): CliqHub offers the run to every online daemon of the realm and the first to claim it runs it. The reply is the queue item, already claimed.
• On one daemon (daemon_id, with workspace_id and team_id): CliqHub sends the run to that daemon. The reply has the new run_id.

Before sending, CliqHub checks the team’s required inputs, that the reviewers name phases the team has, that notify_channels exist in the realm, and that every custom agent the team uses is registered in the organization. Inputs can be sent as inputs or run_context.inputs; run_context.id is your own correlation id.

Requires a realm operator (or higher) with the teams.run permission on the realm given by realm_id. When you target daemons with daemon_id instead, you need that role on each daemon’s realm. Token scope dispatch.

POST /v1/runs/enqueue

cURL

realm

curl --request POST \ --url https://{host}/v1/runs/enqueue \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "realm_id": "5b0c3a7e-2f4d-4b8e-9a51-7c1d2e3f4a5b", "team_id": "3f6c2a8e-6b1d-4c1e-9a57-0d2f4b8e91c4", "inputs": { "pr_url": "https://github.com/acme/api/pull/42" }, "reviewers": { "approve": [ "sshah" ] } } '

200

realm

{ "ok": true, "data": { "item": { "id": "e1d2c3b4-a5f6-4789-8a0b-1c2d3e4f5a6b", "realm_id": "5b0c3a7e-2f4d-4b8e-9a51-7c1d2e3f4a5b", "kind": "run", "payload": { "team_id": "3f6c2a8e-6b1d-4c1e-9a57-0d2f4b8e91c4" }, "priority": 0, "status": "claimed", "claimed_by": "7d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "claimed_at": 1759834200500, "run_id": "0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f", "results": null, "submitted_by": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "submitted_at": 1759834200000, "error": null, "created_at": 1759834200000, "updated_at": 1759834200500 } } }

Authorizations

Authorization · string · header · required

User PAT (cliq_tok_…, including session-scoped) or realm token (cliq_dt_…).

Body

application/json

realm_id · string

Start the run on whichever online daemon of this realm claims it. Send this or daemon_id.

Minimum string length: 1

daemon_id · string

Start the run on this daemon. Send this or realm_id; needs workspace_id and team_id.

Minimum string length: 1

team_id · string

The team to run (id, or scope/slug on the realm path).

Minimum string length: 1

workspace_id · string

Workspace to run in (daemon path: required).

Minimum string length: 1

workspace_path · string

Absolute folder on the daemon, when the workspace is not known to CliqHub yet.

manifest_yaml · string

Run this manifest instead of the installed team's.

run_name · string

Display name. A name is generated when omitted.

execution_type · enum<string>

local (default) or docker.

Available options: local, docker

priority · integer

Higher numbers are offered first when the realm has a queue.

inputs · object

Team inputs by name.

Show child attributes

run_context · object

Correlation id, labels stored with the run, and inputs.

Show child attributes

payload · object

Older form of the realm request; prefer the fields above.

reviewers · object

Reviewers per human phase for this run: { phase: [username] }; replaces the team defaults for those phases

Show child attributes

notify_channels · string[]

Notification channels (name or id in the run's realm) that receive this run's lifecycle events instead of the realm rules

Required array length: 1 - 200 elements

Required string length: 1 - 200

Response

200

application/json

Realm path: { item }, the claimed queue item. Daemon path: { run_id, daemon_id, accepted }.

ok · enum<boolean> · required

Always true on success.

Available options: true

data · object · required

Option 1

Option 2

Show child attributes