> ## 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. # Register an agent with CliqHub > Sends an agent's manifest to CliqHub so it is registered in your organization (the one this daemon is signed in to). The agent is found by `name` on the agents path, or read from the folder `path` when you send one. Only the manifest is sent; the agent's code stays on the daemons that have it. Registering a version that is already registered fails unless `force` is `true`. From the CLI: `cliq agent register jira-sync`. 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-agents.yaml post /v1/agents/register 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 Agents description: >- 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. paths: /v1/agents/register: post: tags: - Daemon Agents summary: Register an agent with CliqHub description: >- Sends an agent's manifest to CliqHub so it is registered in your organization (the one this daemon is signed in to). The agent is found by `name` on the agents path, or read from the folder `path` when you send one. Only the manifest is sent; the agent's code stays on the daemons that have it. Registering a version that is already registered fails unless `force` is `true`. From the CLI: `cliq agent register jira-sync`. 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_agents_register requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 description: Agent name path: description: Agent directory (instead of resolving by name) type: string minLength: 1 force: description: Re-register an existing version type: boolean required: - name examples: by_name: value: name: jira-sync by_path: summary: From a folder, overwriting the registered version value: name: jira-sync path: /home/dev/src/jira-sync force: true responses: '200': description: Success. content: application/json: schema: type: object required: - ok - data properties: ok: type: boolean const: true data: $ref: '#/components/schemas/AgentRegistered' example: ok: true data: name: jira-sync version: 0.3.0 registered: true updated: false '400': description: >- `PAYLOAD_INVALID` — The body (query string for `GET`) fails the request schema. `details` lists each issue. `BAD_REQUEST` — The body is not valid JSON or is larger than the route allows (10 MB; artifact uploads more). content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: PAYLOAD_INVALID: summary: PAYLOAD_INVALID value: ok: false error: code: PAYLOAD_INVALID message: 'name: Invalid input: expected string, received undefined' details: - path: name message: 'Invalid input: expected string, received undefined' BAD_REQUEST: summary: BAD_REQUEST value: ok: false error: code: BAD_REQUEST message: >- Request body could not be read: Unexpected token } in JSON at position 12 '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: >- `AGENT_NOT_FOUND` — No agent with this name is on the agents path, or the manifest in `path` cannot be read. content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: AGENT_NOT_FOUND: summary: AGENT_NOT_FOUND value: ok: false error: code: AGENT_NOT_FOUND message: Agent 'jira-sync' not found on the agents path '409': description: >- `AGENT_ALREADY_EXISTS` — This version is already registered in your organization and `force` is not `true`. content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: AGENT_ALREADY_EXISTS: summary: AGENT_ALREADY_EXISTS value: ok: false error: code: AGENT_ALREADY_EXISTS message: >- Agent 'jira-sync' is already registered (use --force to overwrite) '422': description: >- `HUB_NOT_CONFIGURED` — This daemon is not signed in to CliqHub, or it has no CliqHub organization id (sign in again with `cliq login`). content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: HUB_NOT_CONFIGURED: summary: HUB_NOT_CONFIGURED value: ok: false error: code: HUB_NOT_CONFIGURED message: Hub session not configured — run `cliq login` first '500': description: >- `INTERNAL_ERROR` — CliqHub could not be reached, or another unexpected fault. 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. '502': description: >- `HUB_REQUEST_FAILED` — CliqHub refused the registration for another reason (for example an invalid manifest or missing permission). The message is CliqHub's. content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: HUB_REQUEST_FAILED: summary: HUB_REQUEST_FAILED value: ok: false error: code: HUB_REQUEST_FAILED message: Hub returned HTTP 403 security: - {} - DaemonBearer: [] components: schemas: AgentRegistered: type: object required: - name - version - registered - updated properties: name: type: string description: >- The manifest's name (or the name you sent when the manifest has none). example: jira-sync version: type: - string - 'null' example: 0.3.0 registered: type: boolean const: true updated: type: boolean description: >- `true` when an existing registration of this version was overwritten (`force`). example: false 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`, … 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.