CliqHub API

control plane

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

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.

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:

{ "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.

{ "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).

{ "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 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	`GET /v1/health`
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	`POST /v1/auth/get_dispatch_public_key`
List your tokens	`POST /v1/auth/get_tokens`
Generate a token	`POST /v1/auth/generate_token`
Rotate a realm’s dispatch key	`POST /v1/auth/rotate_dispatch_key`
Rotate a token	`POST /v1/auth/rotate_token`
Validate a token	`POST /v1/auth/validate_token`
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	`POST /v1/users/get`
Get a user	`POST /v1/users/get_by_id`
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	`POST /v1/orgs/get`
Get an organization	`POST /v1/orgs/get_by_id`
List organization notification rules	`POST /v1/orgs/get_notification_rules`
List reviewable targets	`POST /v1/orgs/get_reviewable_targets`
Get a role	`POST /v1/orgs/get_role`
List scopes	`POST /v1/orgs/get_scopes`
List organization teams	`POST /v1/orgs/get_teams`
List roles	`POST /v1/orgs/list_roles`
Create a role	`POST /v1/orgs/create_role`
Create an organization	`POST /v1/orgs/new`
Create a scope	`POST /v1/orgs/new_scope`
Add a team to an organization	`POST /v1/orgs/add_team`
Add a scope member	`POST /v1/orgs/assign_scope_member`
Set organization notification rules	`POST /v1/orgs/set_notification_rules`
Update an organization	`POST /v1/orgs/update`
Update a role	`POST /v1/orgs/update_role`
Update a scope	`POST /v1/orgs/update_scope`
Leave an organization	`POST /v1/orgs/leave`
Delete an organization	`POST /v1/orgs/delete`
Delete a role	`POST /v1/orgs/delete_role`
Delete a scope	`POST /v1/orgs/delete_scope`
Remove a member	`POST /v1/orgs/remove_member`
Remove an organization notification rule	`POST /v1/orgs/remove_notification_rules`
Remove a team from an organization	`POST /v1/orgs/remove_team`
Remove a scope member	`POST /v1/orgs/unassign_scope_member`
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	`POST /v1/invitations/get`
Get an invitation	`POST /v1/invitations/get_by_id`
Preview an invitation	`POST /v1/invitations/get_by_token`
Send an invitation	`POST /v1/invitations/create`
Accept or decline an invitation	`POST /v1/invitations/accept`
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	`POST /v1/teams/get`
Get a team	`POST /v1/teams/get_by_id`
Get a team’s phases	`POST /v1/teams/get_phases`
List team versions	`POST /v1/teams/get_versions`
Create a team draft	`POST /v1/teams/create`
Rename a team	`POST /v1/teams/rename`
Update a team	`POST /v1/teams/update`
Build a team with AI	`POST /v1/teams/build`
Download a team package	`POST /v1/teams/download`
Install a team on daemons	`POST /v1/teams/install`
Publish a team	`POST /v1/teams/publish`
Delete a team	`POST /v1/teams/delete`
Delete a team version	`POST /v1/teams/delete_version`
Uninstall a team from daemons	`POST /v1/teams/uninstall`
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	`POST /v1/realms/get`
Get a realm	`POST /v1/realms/get_by_id`
List realm members	`POST /v1/realms/get_members`
List realm notification rules	`POST /v1/realms/get_notification_rules`
Create a realm	`POST /v1/realms/create`
Add a realm member	`POST /v1/realms/add_member`
Add a team to a realm	`POST /v1/realms/add_team`
Set realm notification rules	`POST /v1/realms/set_notification_rules`
Update a realm	`POST /v1/realms/update`
Manage A2A for a realm	`POST /v1/realms/a2a`
Delete a realm	`POST /v1/realms/delete`
Remove a realm member	`POST /v1/realms/remove_member`
Remove a realm notification rule	`POST /v1/realms/remove_notification_rules`
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	`POST /v1/auth/acl`
List daemons	`POST /v1/daemons/get`
Get a daemon	`POST /v1/daemons/get_by_id`
Register a daemon	`POST /v1/daemons/register`
Report installed teams	`POST /v1/daemons/register_teams`
Acknowledge a command	`POST /v1/daemons/ack_command`
Send a heartbeat	`POST /v1/daemons/heartbeat`
Deregister a daemon	`POST /v1/daemons/deregister`
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	`POST /v1/workspaces/get`
Get a workspace	`POST /v1/workspaces/get_by_id`
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	`POST /v1/runs/get`
Get a run	`POST /v1/runs/get_by_id`
Search run logs	`POST /v1/runs/get_logs`
Get run status	`POST /v1/runs/get_status`
Get run telemetry	`POST /v1/runs/get_telemetry`
Stream run activity	`GET /v1/runs/stream`
Record a new run	`POST /v1/runs/create`
Submit a run data record	`POST /v1/runs/create_rdr`
Start a run	`POST /v1/runs/enqueue`
Update run status	`POST /v1/runs/update_status`
Append run logs	`POST /v1/runs/append_logs`
Cancel a run	`POST /v1/runs/cancel`
Claim a queued run	`POST /v1/runs/claim`
Complete a run	`POST /v1/runs/complete`
Report run activity	`POST /v1/runs/report_activity`
Report run telemetry	`POST /v1/runs/report_telemetry`
Resume a run	`POST /v1/runs/resume`
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	`POST /v1/artifacts/get`
Get an artifact	`POST /v1/artifacts/get_by_id`
Upload an artifact	`POST /v1/artifacts/submit`
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	`POST /v1/events/get_by_id`
Submit an event	`POST /v1/events/submit`
List custom event types	`POST /v1/events/custom/list`
Create a custom event type	`POST /v1/events/custom/create`
Remove a custom event type	`POST /v1/events/custom/remove`
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	`POST /v1/reviews/get`
Get a review	`POST /v1/reviews/get_by_id`
List review messages	`POST /v1/reviews/get_messages`
Stream review messages	`GET /v1/reviews/stream_messages`
Open a review	`POST /v1/reviews/create`
Acknowledge a review	`POST /v1/reviews/ack`
Send a review message	`POST /v1/reviews/send_message`
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	`POST /v1/notification_channels/get`
Create a channel	`POST /v1/notification_channels/create`
Update a channel	`POST /v1/notification_channels/update`
Send a test notification	`POST /v1/notification_channels/test`
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	`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	`POST /v1/agents/get`
Get agent details	`POST /v1/agents/get_details`
Get agent settings	`POST /v1/agents/get_settings`
Register an agent	`POST /v1/agents/register`
Update agent settings	`POST /v1/agents/update_settings`
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	`POST /v1/settings/get`
Get a setting	`POST /v1/settings/get_by_key`
Set a setting	`POST /v1/settings/set`
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	`POST /v1/account/mesh/get`
Update your mesh settings	`POST /v1/account/mesh/update`
List mesh adapters	`POST /v1/mesh/adapters/list`
Get organization mesh settings	`POST /v1/orgs/mesh/get`
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	`POST /v1/integrations/jira/get_workspaces`
Connect a Jira workspace	`POST /v1/integrations/jira/register_workspace`
Rotate a Jira webhook secret	`POST /v1/integrations/jira/rotate_secret`
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	`POST /a2a/o/{org}/r/{slug}/send`
Get a realm’s agent card	`GET /a2a/o/{org}/r/{slug}/.well-known/agent-card.json`

​Base URL

​Requests

​Replies

​Authentication

​Endpoints

​System

​Auth

​Users

​Organizations

​Invitations

​Teams

​Realms

​Daemons

​Workspaces

​Runs

​Artifacts

​Events

​Reviews

​Notification channels

​Notifications

​Agents

​Settings

​Mesh

​Jira

​A2A