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

runs

enqueue

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"
    ]
  }
}
'

{
  "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

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

enum<boolean>

required

Always true on success.

Available options:

true

data

object

required

Option 1
Option 2

Show child attributes

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"
    ]
  }
}
'

{
  "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
    }
  }
}

Introduction

System

Auth

Users

Organizations

Invitations

Teams

Realms

Daemons

Workspaces

Runs

Artifacts

Events

Reviews

Notification channels

Notifications

Agents

Settings

Mesh

Jira

A2A

Start a run

Authorizations

Body

Response