> ## 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.

# CliqHub API

> The HTTP API of CliqHub: base URL, request and reply shape, authentication, and what each resource is for.

<div className="cliq-kicker">control plane</div>

CliqHub is the control plane for Cliq: the team registry, organizations and realms, the daemons connected to them, and the runs they execute. The `cliq` CLI, the console and the daemons all use this API.

The endpoint pages in this tab are generated from the CliqHub source: routes, request schemas, and who may call each route (the route policy table) by `scripts/generate_hub_openapi.py`.

## Base URL

```text theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
https://api.cliqhub.io
```

Public endpoints start with `/v1`; agent-to-agent endpoints start with `/a2a`. Endpoints under `/internal` are called only by the console backend and are not reachable from the internet.

## Requests

Nearly every endpoint is `POST /v1/{resource}/{action}` with a JSON body, even reads. The exceptions are the health check (`GET /v1/health`), the two live streams (`GET /v1/runs/stream`, `GET /v1/reviews/stream_messages`, server-sent events with arguments in the query string) and the public A2A agent card.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl -s https://api.cliqhub.io/v1/realms/get \
  -H "Authorization: Bearer $CLIQ_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"org_id":"5b0c3a7e-2f4d-4b8e-9a51-7c1d2e3f4a5b"}'
```

## Replies

Success:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{ "ok": true, "data": { "items": [], "total": 0, "offset": 0, "limit": 50 } }
```

Failure, with the HTTP status of the error, in one of two shapes. Both always carry a code.

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{ "ok": false, "error": { "code": "not_found", "message": "Not found" } }
```

An access check refused the call (401, 403, 404, and 400 when a call that needs `realm_id` or `org_id` has neither), or there is no such endpoint (`route_not_found`).

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{ "ok": false, "error": "Team @acme/code-review already exists", "code": "conflict" }
```

The endpoint refused it: `error` is the message, `code` the reason, and `details` structured detail when there is some. A body that fails the endpoint's schema is `422 invalid_params`.

Switch on the code; messages are for people and may change. Each endpoint page lists its errors with an example of each, and [Errors](/hub-api/errors) lists every code.

## Authentication

Send a token in the `Authorization` header: `Authorization: Bearer <token>`.

| Token | Prefix | Who uses it |
| - | - | - |
| User token | `cliq_tok_…` | People and automation: `cliq login` stores one, CI uses one as `cliq.api_key`. A token can be limited to fewer permissions than its user has. |
| Realm token | `cliq_dt_…` | Daemons: register, heartbeat, claim runs and report what happens in them. |
| A2A token | `cliq_a2a_…` | Agent-to-agent callers of a realm's `/a2a/…/send`. |

Mint, rotate and revoke tokens with the **Auth** endpoints, or `cliq login` / `cliq realm token`.

What a token may do is decided per endpoint by its role in the organization or realm the request names: realm member (view), operator (operate) or admin, plus a permission such as `teams.install` for some actions. Each endpoint page says exactly what it needs. When you lack access to a record, CliqHub usually answers `404 not_found` rather than `403`, so it does not reveal that the record exists.

## Endpoints

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

### System

Service health, and re-running the seed of built-in data (site administrators).

| Endpoint | Route |
| - | - |
| [Check service health](/api-reference/system/check-service-health) | `GET /v1/health` |
| [Seed an empty deployment](/api-reference/system/seed-an-empty-deployment) | `POST /v1/system/seed` |

### Auth

API tokens. Every call to CliqHub carries one as `Authorization: Bearer <token>`:

* **User token** (`cliq_tok_…`): acts as you, optionally limited by `permissions` (which
  organizations and realms, and read / write / admin per kind of resource). `cliq login`
  stores one; mint more for scripts and CI.
* **Realm token** (`cliq_dt_…`): what a daemon uses to join and work in a realm. Any
  member of the realm can mint one.
* **A2A token** (`cliq_a2a_…`): what outside agents send to a realm's A2A endpoint. One per
  realm; minting a new one replaces the old.
* **Dispatch token**: a short-lived signed token CliqHub uses when it sends work to a
  daemon; each realm has a dispatch key pair for it.

A token is shown only when it is minted or rotated. A restricted token cannot mint a token
wider than itself.

| Endpoint | Route |
| - | - |
| [Get a realm's dispatch public key](/api-reference/auth/get-a-realms-dispatch-public-key) | `POST /v1/auth/get_dispatch_public_key` |
| [List your tokens](/api-reference/auth/list-your-tokens) | `POST /v1/auth/get_tokens` |
| [Generate a token](/api-reference/auth/generate-a-token) | `POST /v1/auth/generate_token` |
| [Rotate a realm's dispatch key](/api-reference/auth/rotate-a-realms-dispatch-key) | `POST /v1/auth/rotate_dispatch_key` |
| [Rotate a token](/api-reference/auth/rotate-a-token) | `POST /v1/auth/rotate_token` |
| [Validate a token](/api-reference/auth/validate-a-token) | `POST /v1/auth/validate_token` |
| [Revoke a token](/api-reference/auth/revoke-a-token) | `POST /v1/auth/revoke_token` |

### Users

User profiles. Which users you see depends on who you are: site administrators see
everyone, organization admins see their members, everyone else sees themselves. Account
administration (create, suspend, delete, passwords) is done by site administrators in the
console.

| Endpoint | Route |
| - | - |
| [List users](/api-reference/users/list-users) | `POST /v1/users/get` |
| [Get a user](/api-reference/users/get-a-user) | `POST /v1/users/get_by_id` |
| [Update a user](/api-reference/users/update-a-user) | `POST /v1/users/update` |

### Organizations

An organization owns realms, teams (through its scopes) and people. Every organization
has four built-in roles, **Owner**, **Admin**, **Operator** and **Member**, and can define
its own: a role is a named set of permissions (List permissions shows them all). Owners can
do everything; `org.delete` and `org.transfer` belong to owners only.

**Scopes** are the organization's package namespaces (`@acme`, `@acme-labs`): teams are
published under a scope, and only the scope's members may publish to it. The organization's
**team library** lists the teams its realms may use. Organization-wide notification rules
also live here.

People join an organization through Send an invitation. Organizations are created by site
administrators for their future owner.

| Endpoint | Route |
| - | - |
| [List organizations](/api-reference/organizations/list-organizations) | `POST /v1/orgs/get` |
| [Get an organization](/api-reference/organizations/get-an-organization) | `POST /v1/orgs/get_by_id` |
| [List organization notification rules](/api-reference/organizations/list-organization-notification-rules) | `POST /v1/orgs/get_notification_rules` |
| [List reviewable targets](/api-reference/organizations/list-reviewable-targets) | `POST /v1/orgs/get_reviewable_targets` |
| [Get a role](/api-reference/organizations/get-a-role) | `POST /v1/orgs/get_role` |
| [List scopes](/api-reference/organizations/list-scopes) | `POST /v1/orgs/get_scopes` |
| [List organization teams](/api-reference/organizations/list-organization-teams) | `POST /v1/orgs/get_teams` |
| [List roles](/api-reference/organizations/list-roles) | `POST /v1/orgs/list_roles` |
| [Create a role](/api-reference/organizations/create-a-role) | `POST /v1/orgs/create_role` |
| [Create an organization](/api-reference/organizations/create-an-organization) | `POST /v1/orgs/new` |
| [Create a scope](/api-reference/organizations/create-a-scope) | `POST /v1/orgs/new_scope` |
| [Add a team to an organization](/api-reference/organizations/add-a-team-to-an-organization) | `POST /v1/orgs/add_team` |
| [Add a scope member](/api-reference/organizations/add-a-scope-member) | `POST /v1/orgs/assign_scope_member` |
| [Set organization notification rules](/api-reference/organizations/set-organization-notification-rules) | `POST /v1/orgs/set_notification_rules` |
| [Update an organization](/api-reference/organizations/update-an-organization) | `POST /v1/orgs/update` |
| [Update a role](/api-reference/organizations/update-a-role) | `POST /v1/orgs/update_role` |
| [Update a scope](/api-reference/organizations/update-a-scope) | `POST /v1/orgs/update_scope` |
| [Leave an organization](/api-reference/organizations/leave-an-organization) | `POST /v1/orgs/leave` |
| [Delete an organization](/api-reference/organizations/delete-an-organization) | `POST /v1/orgs/delete` |
| [Delete a role](/api-reference/organizations/delete-a-role) | `POST /v1/orgs/delete_role` |
| [Delete a scope](/api-reference/organizations/delete-a-scope) | `POST /v1/orgs/delete_scope` |
| [Remove a member](/api-reference/organizations/remove-a-member) | `POST /v1/orgs/remove_member` |
| [Remove an organization notification rule](/api-reference/organizations/remove-an-organization-notification-rule) | `POST /v1/orgs/remove_notification_rules` |
| [Remove a team from an organization](/api-reference/organizations/remove-a-team-from-an-organization) | `POST /v1/orgs/remove_team` |
| [Remove a scope member](/api-reference/organizations/remove-a-scope-member) | `POST /v1/orgs/unassign_scope_member` |
| [List permissions](/api-reference/organizations/list-permissions) | `POST /v1/permissions/list` |

### Invitations

Invitations bring people into an organization (as member, admin or owner) or a realm (as
member, operator or admin). Sending one emails a link; the person previews it and accepts
or declines with the token in the link. Someone without an account sets their username and
password when accepting, and gets a session token back. An invitation is `pending` until it
is accepted, declined, revoked or expires (after 7 days); sending it again to the same
address renews it.

| Endpoint | Route |
| - | - |
| [List invitations](/api-reference/invitations/list-invitations) | `POST /v1/invitations/get` |
| [Get an invitation](/api-reference/invitations/get-an-invitation) | `POST /v1/invitations/get_by_id` |
| [Preview an invitation](/api-reference/invitations/preview-an-invitation) | `POST /v1/invitations/get_by_token` |
| [Send an invitation](/api-reference/invitations/send-an-invitation) | `POST /v1/invitations/create` |
| [Accept or decline an invitation](/api-reference/invitations/accept-or-decline-an-invitation) | `POST /v1/invitations/accept` |
| [Revoke an invitation](/api-reference/invitations/revoke-an-invitation) | `POST /v1/invitations/revoke` |

### Teams

The CliqHub team registry. A team is published under a scope (`@acme/code-review`) as
numbered versions. Create a draft, change it (each change can mint the next version),
publish it to make it installable, then install it on daemons. List teams with a
`realm_id` to see a realm's roster and where each team is installed, or with a
`daemon_id` to see what one daemon has. Build a team with AI drafts a team from a
description.

Changing a team (update, rename, publish, unpublish, delete) needs its author, or the
publish permission in the organization that owns its scope.

| Endpoint | Route |
| - | - |
| [List teams](/api-reference/teams/list-teams) | `POST /v1/teams/get` |
| [Get a team](/api-reference/teams/get-a-team) | `POST /v1/teams/get_by_id` |
| [Get a team's phases](/api-reference/teams/get-a-teams-phases) | `POST /v1/teams/get_phases` |
| [List team versions](/api-reference/teams/list-team-versions) | `POST /v1/teams/get_versions` |
| [Create a team draft](/api-reference/teams/create-a-team-draft) | `POST /v1/teams/create` |
| [Rename a team](/api-reference/teams/rename-a-team) | `POST /v1/teams/rename` |
| [Update a team](/api-reference/teams/update-a-team) | `POST /v1/teams/update` |
| [Build a team with AI](/api-reference/teams/build-a-team-with-ai) | `POST /v1/teams/build` |
| [Download a team package](/api-reference/teams/download-a-team-package) | `POST /v1/teams/download` |
| [Install a team on daemons](/api-reference/teams/install-a-team-on-daemons) | `POST /v1/teams/install` |
| [Publish a team](/api-reference/teams/publish-a-team) | `POST /v1/teams/publish` |
| [Delete a team](/api-reference/teams/delete-a-team) | `POST /v1/teams/delete` |
| [Delete a team version](/api-reference/teams/delete-a-team-version) | `POST /v1/teams/delete_version` |
| [Uninstall a team from daemons](/api-reference/teams/uninstall-a-team-from-daemons) | `POST /v1/teams/uninstall` |
| [Unpublish a team](/api-reference/teams/unpublish-a-team) | `POST /v1/teams/unpublish` |

### Realms

A realm groups daemons, the people who may use them, and the teams they should run. Its
members have a role: member (can see), operator (can run and operate) or admin (can
manage). Daemons join with a realm token, people with an invitation.

A realm's **team list** is the set of teams its daemons should have: Add a team to a realm
installs it on the realm's online daemons, and daemons that join later get it too. A realm
can also have its own notification rules, and A2A access so outside agents can send it tasks.

Several of these endpoints answer `{ ok: true, realm }`-style bodies rather than
`{ ok: true, data }`; each page shows its exact shape.

| Endpoint | Route |
| - | - |
| [List realms](/api-reference/realms/list-realms) | `POST /v1/realms/get` |
| [Get a realm](/api-reference/realms/get-a-realm) | `POST /v1/realms/get_by_id` |
| [List realm members](/api-reference/realms/list-realm-members) | `POST /v1/realms/get_members` |
| [List realm notification rules](/api-reference/realms/list-realm-notification-rules) | `POST /v1/realms/get_notification_rules` |
| [Create a realm](/api-reference/realms/create-a-realm) | `POST /v1/realms/create` |
| [Add a realm member](/api-reference/realms/add-a-realm-member) | `POST /v1/realms/add_member` |
| [Add a team to a realm](/api-reference/realms/add-a-team-to-a-realm) | `POST /v1/realms/add_team` |
| [Set realm notification rules](/api-reference/realms/set-realm-notification-rules) | `POST /v1/realms/set_notification_rules` |
| [Update a realm](/api-reference/realms/update-a-realm) | `POST /v1/realms/update` |
| [Manage A2A for a realm](/api-reference/realms/manage-a2a-for-a-realm) | `POST /v1/realms/a2a` |
| [Delete a realm](/api-reference/realms/delete-a-realm) | `POST /v1/realms/delete` |
| [Remove a realm member](/api-reference/realms/remove-a-realm-member) | `POST /v1/realms/remove_member` |
| [Remove a realm notification rule](/api-reference/realms/remove-a-realm-notification-rule) | `POST /v1/realms/remove_notification_rules` |
| [Remove a team from a realm](/api-reference/realms/remove-a-team-from-a-realm) | `POST /v1/realms/remove_team` |

### Daemons

Daemons (`cliqd`) connected to CliqHub. A daemon joins a realm with a realm token
(`cliq_dt_…`, from Generate a token with `type: realm`, or `cliq login` on the daemon). With
that token it registers, sends a heartbeat, reports its installed teams, refreshes the
realm's access list and acknowledges each command CliqHub sends it. People list, inspect
and remove daemons.

A daemon is `online` while it sends heartbeats, then `stale`, then `offline`; `removed`
once deregistered or removed.

| Endpoint | Route |
| - | - |
| [Get the realm access list](/api-reference/daemons/get-the-realm-access-list) | `POST /v1/auth/acl` |
| [List daemons](/api-reference/daemons/list-daemons) | `POST /v1/daemons/get` |
| [Get a daemon](/api-reference/daemons/get-a-daemon) | `POST /v1/daemons/get_by_id` |
| [Register a daemon](/api-reference/daemons/register-a-daemon) | `POST /v1/daemons/register` |
| [Report installed teams](/api-reference/daemons/report-installed-teams) | `POST /v1/daemons/register_teams` |
| [Acknowledge a command](/api-reference/daemons/acknowledge-a-command) | `POST /v1/daemons/ack_command` |
| [Send a heartbeat](/api-reference/daemons/send-a-heartbeat) | `POST /v1/daemons/heartbeat` |
| [Deregister a daemon](/api-reference/daemons/deregister-a-daemon) | `POST /v1/daemons/deregister` |
| [Remove a daemon](/api-reference/daemons/remove-a-daemon) | `POST /v1/daemons/remove` |

### Workspaces

The workspaces (project folders) daemons have registered, as CliqHub last saw them, with the
teams assigned to each. Workspaces are created and changed on the daemon (`cliq init`,
`cliq assemble`); CliqHub records them when a run starts and keeps a catalog. You see the
workspaces of daemons in your realms.

| Endpoint | Route |
| - | - |
| [List workspaces](/api-reference/workspaces/list-workspaces) | `POST /v1/workspaces/get` |
| [Get a workspace](/api-reference/workspaces/get-a-workspace) | `POST /v1/workspaces/get_by_id` |
| [Remove a workspace](/api-reference/workspaces/remove-a-workspace) | `POST /v1/workspaces/remove` |

### Runs

Runs of a team on a daemon. People start runs (Start a run), follow them (Get a run, Stream
run activity, Search run logs, Get run telemetry), and control them (Cancel a run, Resume a
run, Supply run inputs). CliqHub hands each control to the run's daemon, which must be
online: when it is not, the call fails with a `run/daemon_offline` or `run/daemon_stranded`
conflict (cancel instead marks the run cancelled on CliqHub).

Daemons report what happens during a run through the other endpoints here, with their realm
token: Record a new run, Update run status, Complete a run, and three separate channels for
run activity (the live timeline), run telemetry (token usage and traces) and run logs (text).

| Endpoint | Route |
| - | - |
| [List runs](/api-reference/runs/list-runs) | `POST /v1/runs/get` |
| [Get a run](/api-reference/runs/get-a-run) | `POST /v1/runs/get_by_id` |
| [Search run logs](/api-reference/runs/search-run-logs) | `POST /v1/runs/get_logs` |
| [Get run status](/api-reference/runs/get-run-status) | `POST /v1/runs/get_status` |
| [Get run telemetry](/api-reference/runs/get-run-telemetry) | `POST /v1/runs/get_telemetry` |
| [Stream run activity](/api-reference/runs/stream-run-activity) | `GET /v1/runs/stream` |
| [Record a new run](/api-reference/runs/record-a-new-run) | `POST /v1/runs/create` |
| [Submit a run data record](/api-reference/runs/submit-a-run-data-record) | `POST /v1/runs/create_rdr` |
| [Start a run](/api-reference/runs/start-a-run) | `POST /v1/runs/enqueue` |
| [Update run status](/api-reference/runs/update-run-status) | `POST /v1/runs/update_status` |
| [Append run logs](/api-reference/runs/append-run-logs) | `POST /v1/runs/append_logs` |
| [Cancel a run](/api-reference/runs/cancel-a-run) | `POST /v1/runs/cancel` |
| [Claim a queued run](/api-reference/runs/claim-a-queued-run) | `POST /v1/runs/claim` |
| [Complete a run](/api-reference/runs/complete-a-run) | `POST /v1/runs/complete` |
| [Report run activity](/api-reference/runs/report-run-activity) | `POST /v1/runs/report_activity` |
| [Report run telemetry](/api-reference/runs/report-run-telemetry) | `POST /v1/runs/report_telemetry` |
| [Resume a run](/api-reference/runs/resume-a-run) | `POST /v1/runs/resume` |
| [Supply run inputs](/api-reference/runs/supply-run-inputs) | `POST /v1/runs/supply_inputs` |

### Artifacts

Files a run produced (reports, patches, screenshots), stored by CliqHub, and the run's
records (phase outputs, transcripts). Daemons upload files while the run is going; anyone
who can see the run lists and downloads them. Download links are presigned and expire after
5 minutes; ask again for a fresh one.

| Endpoint | Route |
| - | - |
| [List run artifacts](/api-reference/artifacts/list-run-artifacts) | `POST /v1/artifacts/get` |
| [Get an artifact](/api-reference/artifacts/get-an-artifact) | `POST /v1/artifacts/get_by_id` |
| [Upload an artifact](/api-reference/artifacts/upload-an-artifact) | `POST /v1/artifacts/submit` |
| [Delete an artifact](/api-reference/artifacts/delete-an-artifact) | `POST /v1/artifacts/delete` |

### Events

The notification event bus. Events have a type from CliqHub's catalog (`run.failed`,
`phase.input_required`, `hug.review_requested`, `daemon.offline`, …) or a custom type
`custom.<name>` registered for a realm. Notification rules match events and deliver them to
channels. Daemons and integrations submit events; CliqHub raises some itself. This is not
the live run timeline (that is Runs).

| Endpoint | Route |
| - | - |
| [Get an event](/api-reference/events/get-an-event) | `POST /v1/events/get_by_id` |
| [Submit an event](/api-reference/events/submit-an-event) | `POST /v1/events/submit` |
| [List custom event types](/api-reference/events/list-custom-event-types) | `POST /v1/events/custom/list` |
| [Create a custom event type](/api-reference/events/create-a-custom-event-type) | `POST /v1/events/custom/create` |
| [Remove a custom event type](/api-reference/events/remove-a-custom-event-type) | `POST /v1/events/custom/remove` |
| [List event types](/api-reference/events/list-event-types) | `POST /v1/events/types/list` |

### Reviews

Human-in-the-loop (HUG) reviews. When a team reaches a review phase, the agent opens a
review; CliqHub notifies the reviewers (people and channels named in the team or at run
start) and shows the review in their inbox. A reviewer reads it, can chat with the agent,
and gives a verdict (`PASS`, `REJECT` or `ROUTE:<phase>`); with an `all` policy every group
must answer first. The agent then picks up the decision and acknowledges it.

A review is `pending`, then `decided`, then `completed` once the agent acknowledged it, or
`expired` when nobody answered in time (4 hours by default).

| Endpoint | Route |
| - | - |
| [List reviews](/api-reference/reviews/list-reviews) | `POST /v1/reviews/get` |
| [Get a review](/api-reference/reviews/get-a-review) | `POST /v1/reviews/get_by_id` |
| [List review messages](/api-reference/reviews/list-review-messages) | `POST /v1/reviews/get_messages` |
| [Stream review messages](/api-reference/reviews/stream-review-messages) | `GET /v1/reviews/stream_messages` |
| [Open a review](/api-reference/reviews/open-a-review) | `POST /v1/reviews/create` |
| [Acknowledge a review](/api-reference/reviews/acknowledge-a-review) | `POST /v1/reviews/ack` |
| [Send a review message](/api-reference/reviews/send-a-review-message) | `POST /v1/reviews/send_message` |
| [Give a verdict](/api-reference/reviews/give-a-verdict) | `POST /v1/reviews/verdict` |

### Notification channels

Where notifications go. A channel has one or more destinations (Slack, email, a webhook,
the CliqHub inbox, or another channel by name) and belongs to an organization or a realm;
names are unique within that scope. Notification rules (on Organizations and Realms)
decide which events reach which channel. Built-in channels cannot be changed or removed.

| Endpoint | Route |
| - | - |
| [List channels](/api-reference/notification-channels/list-channels) | `POST /v1/notification_channels/get` |
| [Create a channel](/api-reference/notification-channels/create-a-channel) | `POST /v1/notification_channels/create` |
| [Update a channel](/api-reference/notification-channels/update-a-channel) | `POST /v1/notification_channels/update` |
| [Send a test notification](/api-reference/notification-channels/send-a-test-notification) | `POST /v1/notification_channels/test` |
| [Remove a channel](/api-reference/notification-channels/remove-a-channel) | `POST /v1/notification_channels/remove` |

### Notifications

Your in-app inbox in CliqHub, the notifications delivered to you through the CliqHub inbox destination of a channel.

| Endpoint | Route |
| - | - |
| [List notifications](/api-reference/notifications/list-notifications) | `POST /v1/notifications/get` |

### Agents

The agent catalog: built-in agents that ship with cliq (`is_system: true`, in every
organization) and custom agents your organization registers (`cliq agent register`). An
agent is identified by organization, name and version; only its manifest is stored here,
the code runs on daemons. Agent settings (API keys, models, …) can be set for the
organization and overridden per realm; secret values come back masked unless you hold
`agents.reveal`.

| Endpoint | Route |
| - | - |
| [List agents](/api-reference/agents/list-agents) | `POST /v1/agents/get` |
| [Get agent details](/api-reference/agents/get-agent-details) | `POST /v1/agents/get_details` |
| [Get agent settings](/api-reference/agents/get-agent-settings) | `POST /v1/agents/get_settings` |
| [Register an agent](/api-reference/agents/register-an-agent) | `POST /v1/agents/register` |
| [Update agent settings](/api-reference/agents/update-agent-settings) | `POST /v1/agents/update_settings` |
| [Deregister an agent](/api-reference/agents/deregister-an-agent) | `POST /v1/agents/deregister` |

### Settings

Deployment-wide settings that every daemon picks up (`docker.base_image`,
`hub.registry_url`, …) with `cliq settings pull`. Only site administrators change them; a
daemon's realm token can read them, plus settings set for daemons of its realm.

| Endpoint | Route |
| - | - |
| [List settings](/api-reference/settings/list-settings) | `POST /v1/settings/get` |
| [Get a setting](/api-reference/settings/get-a-setting) | `POST /v1/settings/get_by_key` |
| [Set a setting](/api-reference/settings/set-a-setting) | `POST /v1/settings/set` |
| [Remove a setting](/api-reference/settings/remove-a-setting) | `POST /v1/settings/remove` |

### Mesh

The agent mesh: a provider that lets your realms' agents be found and called by other
agents (A2A). An organization picks a provider and its settings; realms inherit it unless
they override it (Realms, Manage A2A for a realm). Organization admins manage these.

| Endpoint | Route |
| - | - |
| [Get your mesh settings](/api-reference/mesh/get-your-mesh-settings) | `POST /v1/account/mesh/get` |
| [Update your mesh settings](/api-reference/mesh/update-your-mesh-settings) | `POST /v1/account/mesh/update` |
| [List mesh adapters](/api-reference/mesh/list-mesh-adapters) | `POST /v1/mesh/adapters/list` |
| [Get organization mesh settings](/api-reference/mesh/get-organization-mesh-settings) | `POST /v1/orgs/mesh/get` |
| [Update organization mesh settings](/api-reference/mesh/update-organization-mesh-settings) | `POST /v1/orgs/mesh/update` |

### Jira

The Jira (Forge) app's connection to CliqHub: it binds a Jira workspace to a realm so Jira
can start runs and receive results. Called by the Jira app with a session or its `api_token`
(a CliqHub user token). These endpoints answer 404 when the integration is turned off.

| Endpoint | Route |
| - | - |
| [List Jira workspaces](/api-reference/jira/list-jira-workspaces) | `POST /v1/integrations/jira/get_workspaces` |
| [Connect a Jira workspace](/api-reference/jira/connect-a-jira-workspace) | `POST /v1/integrations/jira/register_workspace` |
| [Rotate a Jira webhook secret](/api-reference/jira/rotate-a-jira-webhook-secret) | `POST /v1/integrations/jira/rotate_secret` |
| [Disconnect a Jira workspace](/api-reference/jira/disconnect-a-jira-workspace) | `POST /v1/integrations/jira/disconnect_workspace` |

### A2A

Agent-to-agent (A2A) access to a realm. Outside agents read the realm's agent card to see
its skills (one per team the realm runs), then send tasks with JSON-RPC to `send`, using the
realm's A2A token. A2A must be turned on for the realm (Realms, Manage A2A for a realm).

| Endpoint | Route |
| - | - |
| [Send a task to a realm](/api-reference/a2a/send-a-task-to-a-realm) | `POST /a2a/o/{org}/r/{slug}/send` |
| [Get a realm's agent card](/api-reference/a2a/get-a-realms-agent-card) | `GET /a2a/o/{org}/r/{slug}/.well-known/agent-card.json` |


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