cliqd API

The HTTP API of cliqd, the local Cliq daemon: base URL, request and reply shape, authentication, errors.

localhost:4900

cliqd is the local daemon that runs teams. The cliq CLI is a thin client of this API; use it directly from scripts, the SDK or your own tools.

The endpoint pages in this tab are generated from the daemon source (routes, request schemas, auth rules and the error registry) by scripts/generate_daemon_openapi.mjs. The full spec is openapi/daemon.yaml in the docs repo.

Base URL

http://127.0.0.1:4900

Change the port with CLIQ_DAEMON_PORT or ~/.cliqrc/daemon.json. Every path starts with /v1.

Requests

Nearly every endpoint is POST /v1/{resource}/{action} with a JSON body, even reads. Exceptions:

Endpoint	Method	Why
/v1/system/health	GET	Liveness probe, no body
/v1/runs/events	GET	Server-sent event stream; arguments in the query string

• Send Content-Type: application/json. Bodies are limited to 10 MB, except artifact uploads (runs/artifacts/submit), which are sized from the artifact limit.
• Unknown fields are ignored (dropped before the handler sees the body).
• A body that fails the endpoint’s schema is refused with 400 PAYLOAD_INVALID, listing every issue.

curl -s http://127.0.0.1:4900/v1/teams/get_by_name \
  -H 'Content-Type: application/json' \
  -d '{"scope":"acme","slug":"code-review"}'

Replies

Success is always HTTP 200:

{ "ok": true, "data": { "scope": "acme", "slug": "code-review", "version": "1.4.0" } }

A failure uses the HTTP status of the error and the same envelope:

{
  "ok": false,
  "error": {
    "code": "TEAM_NOT_FOUND",
    "message": "Team 'acme/code-review' not found"
  }
}

Field	Meaning
error.code	Stable code. Switch on this.
error.message	For people; may change between releases.
error.details	Present when there is structured detail, e.g. the schema issues of PAYLOAD_INVALID.

Each endpoint page lists the codes it can return and when. Errors lists them all.

Authentication

What a caller needs depends on where it is:

Caller	Needs
Same machine (loopback)	Nothing. The request must address localhost / 127.0.0.1 / [::1] (HOST_NOT_LOCAL otherwise).
Another host, daemon connected to CliqHub	Authorization: Bearer <token>: a dispatch JWT CliqHub signed for this daemon, a cliq_tok_… personal token whose user is in the daemon’s realm, or a local token (cliq_…) minted on that machine.
Another host, daemon not connected to CliqHub	A local token (cliq_…) minted on that machine with tokens/create; anything else is refused (403 LOCAL_ONLY).
A web page (any request with an Origin header)	Refused (403 WEB_REQUEST_REFUSED).

GET /v1/system/health needs no credential at all.

Hub commands

/v1/execute, /v1/offer_job, /v1/install and the other routes under Hub commands are how CliqHub hands work to this daemon. They take a tx_id; a repeated tx_id returns the first reply instead of running the command again. You rarely call them yourself.

Endpoints

Endpoints are grouped by resource in the sidebar. What each resource is for:

System

Liveness of the daemon process, for load balancers, container probes and scripts that wait for cliqd to come up.

Endpoint	Route
Check daemon health	GET /v1/system/health

Teams

The daemon’s local team catalog: the teams this cliqd can run. Install a team from a manifest you hold (teams/install) or from CliqHub (teams/hub_install), read it back, update it, remove it, and publish manifests to CliqHub.

A team is addressed by scope + slug (@acme/code-review → scope: "acme", slug: "code-review"). The scope local is offline-only: it needs no CliqHub sign-in and can never be published. Every other scope needs cliq login first.

Endpoint	Route
Install a team from a manifest	POST /v1/teams/install
Uninstall a team	POST /v1/teams/uninstall
List installed teams	POST /v1/teams/get
Search CliqHub’s team catalog	POST /v1/teams/search
Get one installed team	POST /v1/teams/get_by_name
Update an installed team	POST /v1/teams/update
Publish a team to CliqHub	POST /v1/teams/publish
Install a team from CliqHub	POST /v1/teams/hub_install

Workspaces

A workspace is a project folder registered with this daemon. You register it once (Register a workspace, cliq init), assign one or more installed teams to it (Assign a team to a workspace, cliq assemble), then start runs in it (Start a run, cliq run). Workspaces live in the daemon’s own catalog; the only thing written into the folder is an empty .cliq/ directory.

Most endpoints take the absolute folder path as workspace_dir; assign and remove also accept the catalog workspace_id. Relative paths are resolved against the daemon’s working directory, so always send absolute paths.

Endpoint	Route
List workspaces	POST /v1/workspaces/get
Register a workspace	POST /v1/workspaces/init
Assign a team to a workspace	POST /v1/workspaces/assemble_team
Remove a team from a workspace	POST /v1/workspaces/remove_team
Start a run	POST /v1/workspaces/run
Get workspace status	POST /v1/workspaces/status
Clean run history from a workspace	POST /v1/workspaces/clean
Unregister a workspace	POST /v1/workspaces/remove
Diagnose this daemon	POST /v1/workspaces/doctor

Runs

Runs on this daemon. Start one with Start a run (Workspaces); everything after that is here: list runs, read a run’s log, phases and tree of sub-runs, follow it live, supply the inputs a paused run is waiting for, and rerun a finished run from a phase.

Wherever a body takes run_id you may also send the run’s name, except the event endpoints, which need the id. Run ids are UUIDs.

A run’s life: running → (awaiting_input ↔ running)* → completed, failed, cancelled or crashed.

Endpoint	Route
Stream run events	GET /v1/runs/events
Push a run event	POST /v1/runs/events
Subscribe to run events	POST /v1/runs/events/subscribe
Unsubscribe from run events	POST /v1/runs/events/unsubscribe
List runs	POST /v1/runs/get
Read a run log	POST /v1/runs/logs
Get a run tree	POST /v1/runs/tree
Send a run data record	POST /v1/runs/create_rdr
Supply run inputs	POST /v1/runs/supply_inputs
Check for supplied inputs	POST /v1/runs/check_inputs
Resume a run from a phase	POST /v1/runs/resume
List run phases	POST /v1/runs/phases

Artifacts

Files a run produces (reports, patches, screenshots), stored by CliqHub. An agent uploads them through its daemon while the run is going; anyone who can see the run reads them from CliqHub. Both endpoints call CliqHub directly, so the daemon must be signed in.

Endpoint	Route
Upload an artifact	POST /v1/runs/artifacts/submit
Get an artifact	POST /v1/artifacts/get_by_id

Agents

Agents this daemon can run, found on its agents path (CLIQ_AGENTS_PATH or the agents.path setting; ~/.cliqrc/agents is always searched last), and their registration in your CliqHub organization. Built-in agents ship with cliq; a custom agent is a folder with an agent manifest. Teams that use a custom agent can only be published and run through CliqHub once the agent is registered there.

Endpoint	Route
List local agents	POST /v1/agents/get
Get a local agent	POST /v1/agents/get_by_id
Register an agent with CliqHub	POST /v1/agents/register
Unregister an agent from CliqHub	POST /v1/agents/unregister

Settings

Settings are key = value pairs, the same ones cliq settings reads and writes. Keys under agents., hub., hub_connect., daemon., logging., notifications., docker., cliq. and a few other prefixes are daemon-wide. Any other key is a workspace secret, stored for one workspace and needing workspace_dir.

Secret values (API keys, tokens, passwords, and every workspace secret) are only shown to callers on the same machine; from another host they read as •••• (secret, hidden). Values are JSON: strings, numbers, booleans, objects.

Endpoint	Route
List settings	POST /v1/settings/get
Get a setting	POST /v1/settings/get_by_key
Set a setting	POST /v1/settings/set

Instances

An instance is a run seen from the process side: where it executes (on this machine or in a Docker container) and how to stop it. The instance id is the run id; the run’s name works too. Used by cliq instance list | info | stop.

Endpoint	Route
List instances	POST /v1/instances/get
Get an instance	POST /v1/instances/get_by_id
Stop an instance	POST /v1/instances/stop

Daemon

This daemon process: who it is and who it is signed in as, a summary of what it holds, and restart.

Endpoint	Route
Get daemon status	POST /v1/daemon/status
Restart the daemon	POST /v1/daemon/restart
Get daemon summary	POST /v1/daemon/summary

Sign-in

Signing this daemon in to CliqHub, choosing the realm it belongs to, and minting CliqHub tokens with its sign-in. cliq login and cliq logout use these endpoints.

A daemon that has never joined a realm enrolls in one the first time it signs in. Once enrolled it stays in that realm: signing in again keeps it, and moving it to another realm needs cliqd started with --allow-realm-override plus an explicit confirmation. Sign-in and sign-out are only accepted from the machine running cliqd.

Endpoint	Route
Sign in to CliqHub	POST /v1/login
Sign out of CliqHub	POST /v1/logout
Mint a CliqHub token	POST /v1/auth/token
Rotate a dispatch key	POST /v1/auth/rotate_dispatch

Local tokens

Tokens this daemon mints and stores for itself (cliq_ followed by 64 hex characters), kept in its settings store as a hash. No CLI command uses them today.

A caller on another host can send one as Authorization: Bearer cliq_…, also when the daemon isn’t connected to CliqHub (e.g. a Docker port mapping). Revoked tokens are refused. These routes answer only on the machine running cliqd, so a token can’t be minted remotely (see Authentication).

Endpoint	Route
Create a local token	POST /v1/tokens/create
List local tokens	POST /v1/tokens/get
Revoke a local token	POST /v1/tokens/revoke

HUG

Human-in-the-loop (HUG) reviews: when a team needs a person, an agent creates a review through the daemon. The daemon proxies to CliqHub when enrolled, or stores locally when in standalone mode. Verdicts, inputs, and chat messages are delivered through POST /v1/hug/verdict and polled via POST /v1/hug/poll_verdict.

Waiting messages are kept in the daemon’s memory only, so they are lost if the daemon restarts before the agent polls.

Endpoint	Route
Create a HUG review	POST /v1/hug/create_review
Get review status	POST /v1/hug/get_review
Nudge reviewers	POST /v1/hug/remind
Send chat message to reviewer	POST /v1/hug/send_message
Deliver a verdict, input, or chat message	POST /v1/hug/verdict
Poll pending messages	POST /v1/hug/poll_verdict

Hub commands

How CliqHub hands work to this daemon: start or offer a run, cancel or resume one, install or uninstall a team, register a workspace and assign teams to it. CliqHub sends them when someone acts in CliqHub, over the daemon’s CliqHub connection with a dispatch token. You rarely call them yourself; use the Teams, Workspaces and Runs endpoints instead.

Every command carries tx_id, CliqHub’s command id. A repeated tx_id returns the first reply instead of running the command again, and the daemon acknowledges each command back to CliqHub (ok, or error with the reason), including a body that fails validation.

Endpoint	Route
Execute a run	POST /v1/execute
Offer a run	POST /v1/offer_job
Install an authorized team	POST /v1/install
Cancel a run	POST /v1/cancel
Initialize a workspace	POST /v1/init
Assign a team	POST /v1/assemble
Unbind a team	POST /v1/unbind
Uninstall a team	POST /v1/uninstall
Resume a run	POST /v1/resume