> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcliq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# cliqd API

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

<div className="cliq-kicker">localhost:4900</div>

`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

```text theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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`:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{ "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:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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](/daemon-api/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](/api-reference/daemon-system/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](/api-reference/daemon-teams/install-a-team-from-a-manifest) | `POST /v1/teams/install` |
| [Uninstall a team](/api-reference/daemon-teams/uninstall-a-team) | `POST /v1/teams/uninstall` |
| [List installed teams](/api-reference/daemon-teams/list-installed-teams) | `POST /v1/teams/get` |
| [Search CliqHub's team catalog](/api-reference/daemon-teams/search-cliqhubs-team-catalog) | `POST /v1/teams/search` |
| [Get one installed team](/api-reference/daemon-teams/get-one-installed-team) | `POST /v1/teams/get_by_name` |
| [Update an installed team](/api-reference/daemon-teams/update-an-installed-team) | `POST /v1/teams/update` |
| [Publish a team to CliqHub](/api-reference/daemon-teams/publish-a-team-to-cliqhub) | `POST /v1/teams/publish` |
| [Install a team from CliqHub](/api-reference/daemon-teams/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](/api-reference/daemon-workspaces/list-workspaces) | `POST /v1/workspaces/get` |
| [Register a workspace](/api-reference/daemon-workspaces/register-a-workspace) | `POST /v1/workspaces/init` |
| [Assign a team to a workspace](/api-reference/daemon-workspaces/assign-a-team-to-a-workspace) | `POST /v1/workspaces/assemble_team` |
| [Remove a team from a workspace](/api-reference/daemon-workspaces/remove-a-team-from-a-workspace) | `POST /v1/workspaces/remove_team` |
| [Start a run](/api-reference/daemon-workspaces/start-a-run) | `POST /v1/workspaces/run` |
| [Get workspace status](/api-reference/daemon-workspaces/get-workspace-status) | `POST /v1/workspaces/status` |
| [Clean run history from a workspace](/api-reference/daemon-workspaces/clean-run-history-from-a-workspace) | `POST /v1/workspaces/clean` |
| [Unregister a workspace](/api-reference/daemon-workspaces/unregister-a-workspace) | `POST /v1/workspaces/remove` |
| [Diagnose this daemon](/api-reference/daemon-workspaces/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](/api-reference/daemon-runs/stream-run-events) | `GET /v1/runs/events` |
| [Push a run event](/api-reference/daemon-runs/push-a-run-event) | `POST /v1/runs/events` |
| [Subscribe to run events](/api-reference/daemon-runs/subscribe-to-run-events) | `POST /v1/runs/events/subscribe` |
| [Unsubscribe from run events](/api-reference/daemon-runs/unsubscribe-from-run-events) | `POST /v1/runs/events/unsubscribe` |
| [List runs](/api-reference/daemon-runs/list-runs) | `POST /v1/runs/get` |
| [Read a run log](/api-reference/daemon-runs/read-a-run-log) | `POST /v1/runs/logs` |
| [Get a run tree](/api-reference/daemon-runs/get-a-run-tree) | `POST /v1/runs/tree` |
| [Send a run data record](/api-reference/daemon-runs/send-a-run-data-record) | `POST /v1/runs/create_rdr` |
| [Supply run inputs](/api-reference/daemon-runs/supply-run-inputs) | `POST /v1/runs/supply_inputs` |
| [Check for supplied inputs](/api-reference/daemon-runs/check-for-supplied-inputs) | `POST /v1/runs/check_inputs` |
| [Resume a run from a phase](/api-reference/daemon-runs/resume-a-run-from-a-phase) | `POST /v1/runs/resume` |
| [List run phases](/api-reference/daemon-runs/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](/api-reference/daemon-artifacts/upload-an-artifact) | `POST /v1/runs/artifacts/submit` |
| [Get an artifact](/api-reference/daemon-artifacts/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](/api-reference/daemon-agents/list-local-agents) | `POST /v1/agents/get` |
| [Get a local agent](/api-reference/daemon-agents/get-a-local-agent) | `POST /v1/agents/get_by_id` |
| [Register an agent with CliqHub](/api-reference/daemon-agents/register-an-agent-with-cliqhub) | `POST /v1/agents/register` |
| [Unregister an agent from CliqHub](/api-reference/daemon-agents/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](/api-reference/daemon-settings/list-settings) | `POST /v1/settings/get` |
| [Get a setting](/api-reference/daemon-settings/get-a-setting) | `POST /v1/settings/get_by_key` |
| [Set a setting](/api-reference/daemon-settings/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](/api-reference/daemon-instances/list-instances) | `POST /v1/instances/get` |
| [Get an instance](/api-reference/daemon-instances/get-an-instance) | `POST /v1/instances/get_by_id` |
| [Stop an instance](/api-reference/daemon-instances/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](/api-reference/daemon-daemon/get-daemon-status) | `POST /v1/daemon/status` |
| [Restart the daemon](/api-reference/daemon-daemon/restart-the-daemon) | `POST /v1/daemon/restart` |
| [Get daemon summary](/api-reference/daemon-daemon/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](/api-reference/daemon-sign-in/sign-in-to-cliqhub) | `POST /v1/login` |
| [Sign out of CliqHub](/api-reference/daemon-sign-in/sign-out-of-cliqhub) | `POST /v1/logout` |
| [Mint a CliqHub token](/api-reference/daemon-sign-in/mint-a-cliqhub-token) | `POST /v1/auth/token` |
| [Rotate a dispatch key](/api-reference/daemon-sign-in/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](/daemon-api/overview#authentication)).

| Endpoint | Route |
| - | - |
| [Create a local token](/api-reference/daemon-local-tokens/create-a-local-token) | `POST /v1/tokens/create` |
| [List local tokens](/api-reference/daemon-local-tokens/list-local-tokens) | `POST /v1/tokens/get` |
| [Revoke a local token](/api-reference/daemon-local-tokens/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](/api-reference/daemon-hug/create-a-hug-review) | `POST /v1/hug/create_review` |
| [Get review status](/api-reference/daemon-hug/get-review-status) | `POST /v1/hug/get_review` |
| [Nudge reviewers](/api-reference/daemon-hug/nudge-reviewers) | `POST /v1/hug/remind` |
| [Send chat message to reviewer](/api-reference/daemon-hug/send-chat-message-to-reviewer) | `POST /v1/hug/send_message` |
| [Deliver a verdict, input, or chat message](/api-reference/daemon-hug/deliver-a-verdict-input-or-chat-message) | `POST /v1/hug/verdict` |
| [Poll pending messages](/api-reference/daemon-hug/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](/api-reference/daemon-hub-commands/execute-a-run) | `POST /v1/execute` |
| [Offer a run](/api-reference/daemon-hub-commands/offer-a-run) | `POST /v1/offer_job` |
| [Install an authorized team](/api-reference/daemon-hub-commands/install-an-authorized-team) | `POST /v1/install` |
| [Cancel a run](/api-reference/daemon-hub-commands/cancel-a-run) | `POST /v1/cancel` |
| [Initialize a workspace](/api-reference/daemon-hub-commands/initialize-a-workspace) | `POST /v1/init` |
| [Assign a team](/api-reference/daemon-hub-commands/assign-a-team) | `POST /v1/assemble` |
| [Unbind a team](/api-reference/daemon-hub-commands/unbind-a-team) | `POST /v1/unbind` |
| [Uninstall a team](/api-reference/daemon-hub-commands/uninstall-a-team) | `POST /v1/uninstall` |
| [Resume a run](/api-reference/daemon-hub-commands/resume-a-run) | `POST /v1/resume` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.