Start a run

Starts a run of the workspace’s team and returns as soon as it is accepted; the run continues in the background. Follow it with Stream run events (GET /v1/runs/events) or poll List runs.

Before starting, the daemon checks, in order:

1. Idempotency. With run_context.id, a run with that id that is still going is returned (idempotent: true) instead of starting another. Use it for retries from CI or webhooks.
2. One run at a time. A workspace runs one run at a time (WORKSPACE_RUN_ALREADY_ACTIVE).
3. Agents. Every agent the team uses must be installed and configured. If not, the reply is status: agent_not_ready (HTTP 200) with what to fix.
4. Inputs. Inputs the first phases need must be in run_context.inputs or have a default in the manifest. If not, the reply is status: inputs_required (HTTP 200) listing them.

With several teams assigned, pick one with team_ref (scope/slug). run_context.labels are stored with the run for your own filtering and are not passed to agents. execution: docker runs agents in containers instead of on this machine.

From the CLI: cliq run.

No credential is needed from this machine. From another host, send Authorization: Bearer with a dispatch token CliqHub signed for this daemon or a cliq_tok_… personal token of a user in the daemon’s realm; this only works once the daemon is connected to CliqHub. See Authentication.

POST /v1/workspaces/run

cURL

simple

curl --request POST \ --url http://127.0.0.1:4900/v1/workspaces/run \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "workspace_dir": "/home/dev/acme-api", "name": "fix-login-timeout", "run_context": { "inputs": { "pr_url": "https://github.com/acme/api/pull/42" } } } '

200

started

{ "ok": true, "data": { "status": "started", "workspace_dir": "/home/dev/acme-api", "instance_id": "executor-48213", "run_id": "0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f", "run_name": "fix-login-timeout" } }

Authorizations

Authorization · string · header · required

Not needed from the same machine. From another host: a dispatch JWT CliqHub signed for this daemon, or a cliq_tok_… personal token whose user is in the daemon's realm.

Body

application/json

workspace_dir · string · required

Absolute workspace path

Minimum string length: 1

name · string

Run name

team_ref · string

scope/slug of the team to run when several are assembled

Minimum string length: 1

execution · enum<string>

Execution mode

Available options: docker, local

run_context · object

Run context: correlation id, labels and inputs

Show child attributes

Response

200

application/json

status: started, inputs_required or agent_not_ready.

ok · boolean · required

data · object · required

status says which: started (the run is going), inputs_required or agent_not_ready (nothing was started; fix and call again). All three are HTTP 200.

Option 1

Option 2

Option 3

Show child attributes