CliqHub API

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

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