> ## 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. # Open a Hug > A daemon opens a Hug for one phase iteration of a run (an agent's `ctx.ask`). `spec` is the SDK's HugSpec (title, prompt, context, requested_inputs, channels, expires_in_min, reminders). CliqHub resolves the channels and posts the Hug to them. People the channels reach who can't view runs in the realm are left out and recorded; a Hug that reaches nobody who could answer is refused. Retrying with the same `hug_id` returns the same Hug. Answers `201`. Requires a daemon's realm token (`cliq_dt_…`) for the realm given by `realm_id`. Run in the realm; daemon of the realm. ## OpenAPI ````yaml /openapi/hub-by-tag/hub-hugs.yaml post /v1/hugs/create openapi: 3.0.3 info: title: 'CliqHub API: Hugs' version: 1.0.0 description: >- A Hug is a run asking people for input: an agent (a review gate, or its own `ctx.ask`) opens one with a prompt, context (markdown, files, check results, an earlier conversation) and the inputs it needs — text, number, boolean, a choice, a file, a channel. CliqHub posts it to the Hug's channels; anyone it reaches who can view runs in the realm answers on the Hug page, and can change their answer while it is open. Every answer is sent back to the agent, which decides when it has heard enough and closes the Hug; it expires after its time (at most 7 days). Seeing a Hug needs `runs.view` on its realm; answering also needs the Hug to be addressed to you (your own channel, or one of its shared channels). `create`, `close` and `get_events` are for daemons only. servers: - url: https://{host} variables: host: default: cliqhub.io description: CliqHub host security: [] tags: - name: Hugs description: >- A Hug is a run asking people for input: an agent (a review gate, or its own `ctx.ask`) opens one with a prompt, context (markdown, files, check results, an earlier conversation) and the inputs it needs — text, number, boolean, a choice, a file, a channel. CliqHub posts it to the Hug's channels; anyone it reaches who can view runs in the realm answers on the Hug page, and can change their answer while it is open. Every answer is sent back to the agent, which decides when it has heard enough and closes the Hug; it expires after its time (at most 7 days). Seeing a Hug needs `runs.view` on its realm; answering also needs the Hug to be addressed to you (your own channel, or one of its shared channels). `create`, `close` and `get_events` are for daemons only. paths: /v1/hugs/create: post: tags: - Hugs summary: Open a Hug description: >- A daemon opens a Hug for one phase iteration of a run (an agent's `ctx.ask`). `spec` is the SDK's HugSpec (title, prompt, context, requested_inputs, channels, expires_in_min, reminders). CliqHub resolves the channels and posts the Hug to them. People the channels reach who can't view runs in the realm are left out and recorded; a Hug that reaches nobody who could answer is refused. Retrying with the same `hug_id` returns the same Hug. Answers `201`. Requires a daemon's realm token (`cliq_dt_…`) for the realm given by `realm_id`. Run in the realm; daemon of the realm. operationId: POST_v1_hugs_create requestBody: required: true content: application/json: schema: type: object properties: hug_id: type: string minLength: 1 maxLength: 100 description: Daemon-minted id; a retried create returns this Hug. run_id: type: string minLength: 1 description: The run asking. daemon_id: type: string minLength: 1 description: The daemon running it. realm_id: type: string minLength: 1 description: The run's realm. phase: type: string minLength: 1 description: The phase asking. iteration: type: integer default: 0 description: The phase's iteration (0 first). spec: type: object additionalProperties: true description: What it asks (the SDK's HugSpec). required: - run_id - daemon_id - realm_id - phase - iteration - spec examples: default: value: hug_id: 6c2d1e0f-9a8b-4c7d-8e6f-5a4b3c2d1e0f run_id: 0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f daemon_id: 7d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d realm_id: 5b0c3a7e-2f4d-4b8e-9a51-7c1d2e3f4a5b phase: approve iteration: 0 spec: title: 'Review: approve' prompt: Please review the fix. requested_inputs: - name: decision type: enum choices: - value: approve - value: reject channels: - security expires_in_min: 30 responses: '201': description: Created. content: application/json: schema: type: object required: - ok - data properties: ok: type: boolean enum: - true description: Always `true` on success. data: type: object properties: hug_id: type: string hug_url: type: string example: ok: true data: hug_id: 6c2d1e0f-9a8b-4c7d-8e6f-5a4b3c2d1e0f hug_url: https://cliqhub.io/hugs/6c2d1e0f-9a8b-4c7d-8e6f-5a4b3c2d1e0f '401': description: >- `unauthorized`: No `Authorization` header, or the token is malformed, expired or revoked. content: application/json: schema: $ref: '#/components/schemas/HubErr' examples: unauthorized: summary: unauthorized value: ok: false error: code: unauthorized message: Authentication required '403': description: >- `forbidden`: You can see the realm but your role there is too low or lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/HubErr' examples: forbidden: summary: forbidden value: ok: false error: code: forbidden message: You do not have access to do this '404': description: >- `not_found`: The realm does not exist, was deleted, or you are not a member of it (404 rather than 403, so its existence is not revealed). content: application/json: schema: $ref: '#/components/schemas/HubErr' examples: not_found: summary: not_found value: ok: false error: code: not_found message: Not found '422': description: >- `invalid_hug`: The spec isn't a valid Hug (or has no expiry). `invalid_params`: No channel, or every named channel is unknown in the realm and its org. `no_one_can_answer`: Every person the channels reach lacks `runs.view` on the realm, and no channel reaches people CliqHub can't name. content: application/json: schema: $ref: '#/components/schemas/HubErr' examples: invalid_params: summary: invalid_params value: ok: false error: >- Hug sent to unknown channel 'legal' — no channel with that name in this realm or its org code: invalid_params invalid_hug: summary: invalid_hug value: ok: false error: >- Invalid Hug: requested_inputs.0.name: must be a lowercase identifier code: invalid_hug no_one_can_answer: summary: no_one_can_answer value: ok: false error: >- Hug refused: nobody it reaches can view runs in this realm — kai (via 'legal'). Give them a role with runs.view, or change the channels. code: no_one_can_answer '500': description: >- `internal_error`: An unexpected server fault. Retry later; if it persists, report it with the time of the request. content: application/json: schema: $ref: '#/components/schemas/HubErr' examples: internal_error: summary: internal_error value: ok: false error: Internal server error code: internal_error security: - BearerAuth: [] components: schemas: HubErr: type: object required: - ok - error description: >- Every failure. Route-policy denials (401/403/404, and 400 when neither realm_id nor org_id was sent) answer `error` as `{ code, message }`; errors raised by the endpoint answer `error` as the message with the code beside it in `code`. Every error has a code. See [Errors](/hub-api/errors). properties: ok: type: boolean description: Always false on error error: description: The message, or `{ code, message }` for an access denial. oneOf: - type: string - type: object required: - code - message properties: code: type: string message: type: string code: type: string description: Stable error code of an endpoint error. details: type: object additionalProperties: true description: Structured detail, when there is some. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: cliq_tok_* | cliq_dt_* description: >- User PAT (`cliq_tok_…`, including session-scoped) or realm token (`cliq_dt_…`). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.