> ## 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. # 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](/daemon-api/overview#authentication). ## OpenAPI ````yaml /openapi/daemon-by-tag/daemon-workspaces.yaml post /v1/workspaces/run openapi: 3.1.0 info: title: cliqd API version: 1.9.48 description: >- HTTP API of `cliqd`, the local Cliq daemon. Generated from the daemon source by `scripts/generate_daemon_openapi.mjs` — do not edit by hand. See the [overview](/daemon-api/overview). servers: - url: http://127.0.0.1:4900 description: Local daemon (default port; `CLIQ_DAEMON_PORT` changes it) security: [] tags: - name: Daemon Workspaces description: >- 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. paths: /v1/workspaces/run: post: tags: - Daemon Workspaces summary: Start a run description: >- 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](/daemon-api/overview#authentication). operationId: daemon_post_workspaces_run requestBody: required: true content: application/json: schema: type: object properties: workspace_dir: type: string minLength: 1 description: Absolute workspace path name: description: Run name type: string team_ref: description: '`scope/slug` of the team to run when several are assembled' type: string minLength: 1 execution: description: Execution mode type: string enum: - docker - local run_context: default: {} description: 'Run context: correlation id, labels and inputs' type: object properties: id: description: Caller idempotency / correlation key type: string maxLength: 256 labels: description: Trigger metadata (not passed to agents) type: object propertyNames: type: string additionalProperties: type: string inputs: description: Team inputs (`{{inputs.key}}`) type: object propertyNames: type: string additionalProperties: {} required: - workspace_dir examples: simple: summary: Run the only assigned team value: workspace_dir: /home/dev/acme-api name: fix-login-timeout run_context: inputs: pr_url: https://github.com/acme/api/pull/42 ci: summary: From CI, retry-safe, one of several teams value: workspace_dir: /home/dev/acme-api team_ref: acme/code-review execution: docker run_context: id: github-run-9876543210 labels: source: github-actions branch: main inputs: pr_url: https://github.com/acme/api/pull/42 responses: '200': description: '`status: started`, `inputs_required` or `agent_not_ready`.' content: application/json: schema: type: object required: - ok - data properties: ok: type: boolean const: true data: $ref: '#/components/schemas/RunOutcome' examples: started: summary: Started value: 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 inputs_required: summary: Inputs missing (nothing started) value: ok: true data: status: inputs_required phase: review missing_inputs: - name: pr_url description: Pull request to review required: true agent: claude-code agent_not_ready: summary: Agent not configured (nothing started) value: ok: true data: status: agent_not_ready agents: - name: claude-code agent_type: exec ready: false issues: - missing required setting 'api_key' setup_hint: cliq settings set agents.claude-code.api_key '400': description: >- `PAYLOAD_INVALID` — `workspace_dir` is missing, `execution` is not `docker` or `local`, or `run_context.id` is longer than 256 characters. `WORKSPACE_BAD_REQUEST` — Several teams are assigned and no `team_ref` was sent, or `team_ref` names a team that is not assigned here. `BAD_REQUEST` — `team_ref` is not `scope/slug`, or the body is not valid JSON. content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: PAYLOAD_INVALID: summary: PAYLOAD_INVALID value: ok: false error: code: PAYLOAD_INVALID message: >- workspace_dir: Invalid input: expected string, received undefined details: - path: workspace_dir message: 'Invalid input: expected string, received undefined' WORKSPACE_BAD_REQUEST: summary: WORKSPACE_BAD_REQUEST value: ok: false error: code: WORKSPACE_BAD_REQUEST message: >- Workspace has 2 teams assembled: acme/code-review, acme/release-notes. Specify which to run with --team . BAD_REQUEST: summary: BAD_REQUEST value: ok: false error: code: BAD_REQUEST message: >- Invalid team_ref 'code-review'. Expected format: scope/slug '401': description: >- `UNAUTHORIZED` — A caller on another host sent no `Authorization: Bearer` token, or one that does not verify (expired, wrong audience). content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: UNAUTHORIZED: summary: UNAUTHORIZED value: ok: false error: code: UNAUTHORIZED message: Missing or invalid Authorization Bearer token '403': description: >- `WEB_REQUEST_REFUSED` — The request carries an `Origin` header (it came from a web page). `HOST_NOT_LOCAL` — A loopback caller addressed a `Host` other than localhost (DNS rebinding guard). `LOCAL_ONLY` — The daemon isn't connected to CliqHub (no dispatch key) and the caller is on another host. `FORBIDDEN` — A `cliq_tok_…` token's user is not in this daemon's realm ACL, or the ACL is not loaded yet. content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: WEB_REQUEST_REFUSED: summary: WEB_REQUEST_REFUSED value: ok: false error: code: WEB_REQUEST_REFUSED message: cliqd doesn't accept requests from web pages HOST_NOT_LOCAL: summary: HOST_NOT_LOCAL value: ok: false error: code: HOST_NOT_LOCAL message: cliqd only answers requests addressed to localhost LOCAL_ONLY: summary: LOCAL_ONLY value: ok: false error: code: LOCAL_ONLY message: >- This cliqd isn't connected to CliqHub yet, so from another machine it only accepts a local token (minted by tokens/create on the machine running cliqd) FORBIDDEN: summary: FORBIDDEN value: ok: false error: code: FORBIDDEN message: Access denied — identity not in realm ACL '404': description: |- `WORKSPACE_NOT_REGISTERED` — The path is not a registered workspace. `SCOPE_NOT_FOUND` — The scope in `team_ref` has no installed team. `TEAM_NOT_FOUND` — The team in `team_ref` is not installed. content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: WORKSPACE_NOT_REGISTERED: summary: WORKSPACE_NOT_REGISTERED value: ok: false error: code: WORKSPACE_NOT_REGISTERED message: >- Workspace '/home/dev/acme-api' is not registered. Run 'cliq init' first. SCOPE_NOT_FOUND: summary: SCOPE_NOT_FOUND value: ok: false error: code: SCOPE_NOT_FOUND message: Scope 'acme' not found TEAM_NOT_FOUND: summary: TEAM_NOT_FOUND value: ok: false error: code: TEAM_NOT_FOUND message: Team 'acme/code-review' not found in catalog '409': description: >- `WORKSPACE_NOT_ASSEMBLED` — No team is assigned to the workspace. `WORKSPACE_RUN_ALREADY_ACTIVE` — A run is already `running` or `awaiting_input` in this workspace. content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: WORKSPACE_NOT_ASSEMBLED: summary: WORKSPACE_NOT_ASSEMBLED value: ok: false error: code: WORKSPACE_NOT_ASSEMBLED message: >- Workspace '/home/dev/acme-api' has no team assembled. Run 'cliq assemble ' first. WORKSPACE_RUN_ALREADY_ACTIVE: summary: WORKSPACE_RUN_ALREADY_ACTIVE value: ok: false error: code: WORKSPACE_RUN_ALREADY_ACTIVE message: >- Workspace already has an active run (0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f). Stop it first or wait for it to complete. '422': description: >- `TEAM_MANIFEST_INVALID` — The team's installed manifest no longer parses or validates. content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: TEAM_MANIFEST_INVALID: summary: TEAM_MANIFEST_INVALID value: ok: false error: code: TEAM_MANIFEST_INVALID message: Team manifest failed validation '500': description: >- `INTERNAL_ERROR` — An unexpected daemon fault. The message names the request id; the cause is in the cliqd log. content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: INTERNAL_ERROR: summary: INTERNAL_ERROR value: ok: false error: code: INTERNAL_ERROR message: >- cliqd hit an unexpected error (request 7f3a…). Details are in the cliqd log. security: - {} - DaemonBearer: [] components: schemas: RunOutcome: description: > `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. oneOf: - $ref: '#/components/schemas/RunStarted' - $ref: '#/components/schemas/RunInputsRequired' - $ref: '#/components/schemas/RunAgentNotReady' ErrorReply: type: object description: >- Every failure. Switch on `error.code` — it is stable; `message` is for people and may change. required: - ok - error properties: ok: type: boolean const: false error: type: object required: - code - message properties: code: type: string description: Stable error code. See [Errors](/daemon-api/errors). example: TEAM_NOT_FOUND message: type: string description: What went wrong and, where possible, what to do. example: Team 'acme/code-review' not found details: description: >- Structured detail when there is some: the list of schema issues for `PAYLOAD_INVALID`, the agent problems for `TEAM_AGENT_CONFIG_REQUIRED`, … RunStarted: type: object description: >- The run was accepted and is executing in the background. Follow it with Stream run events. required: - status - workspace_dir - instance_id - run_id - run_name properties: status: type: string enum: - started workspace_dir: type: string example: /home/dev/acme-api instance_id: type: string description: The daemon process running it (`executor-`). example: executor-48213 run_id: type: string format: uuid example: 0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f run_name: type: string description: The `name` you sent, or the run id. example: fix-login-timeout idempotent: type: boolean description: >- `true` when `run_context.id` matched a run that is still going; that run is returned and no new run starts. Absent otherwise. example: true RunInputsRequired: type: object description: > The first phase that needs inputs is missing some. Nothing was started; call again with the values in `run_context.inputs`. required: - status - missing_inputs - phase properties: status: type: string enum: - inputs_required phase: type: string description: The phase whose inputs are missing. example: review missing_inputs: type: array items: type: object required: - name - agent properties: name: type: string description: Input key to send in `run_context.inputs`. example: pr_url description: type: string description: What the input is for, from the manifest. example: Pull request to review required: type: boolean example: true agent: type: string description: Agent of the phase that needs it. example: claude-code RunAgentNotReady: type: object description: >- An agent the team needs is missing or not configured. Nothing was started. required: - status - agents properties: status: type: string enum: - agent_not_ready agents: type: array description: The agents that are not ready. items: $ref: '#/components/schemas/AgentDiagnostic' AgentDiagnostic: type: object description: Readiness of one agent. required: - name - agent_type - ready - issues - setup_hint properties: name: type: string example: claude-code agent_type: type: string description: Agent kind from its manifest (for example `exec` or `connector`). example: exec ready: type: boolean example: false issues: type: array items: type: string description: What is wrong. Empty when ready. example: - missing required setting 'api_key' setup_hint: type: string description: The command that fixes it. example: cliq settings set agents.claude-code.api_key securitySchemes: DaemonBearer: type: http scheme: bearer description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.