> ## 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. # Get a Hug > Returns one Hug — what it asks, its context, its channels and everyone's answers so far. Requires a realm member (or higher) with the `runs.view` permission on the realm that owns the hug given by `hug_id`. A daemon's realm token (`cliq_dt_…`) from the same realm may also read it. ## OpenAPI ````yaml /openapi/hub-by-tag/hub-hugs.yaml post /v1/hugs/get_by_id 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/get_by_id: post: tags: - Hugs summary: Get a Hug description: >- Returns one Hug — what it asks, its context, its channels and everyone's answers so far. Requires a realm member (or higher) with the `runs.view` permission on the realm that owns the hug given by `hug_id`. A daemon's realm token (`cliq_dt_…`) from the same realm may also read it. operationId: POST_v1_hugs_get_by_id requestBody: required: true content: application/json: schema: type: object properties: hug_id: type: string minLength: 1 description: The Hug. required: - hug_id examples: default: value: hug_id: 6c2d1e0f-9a8b-4c7d-8e6f-5a4b3c2d1e0f responses: '200': description: Success. content: application/json: schema: type: object required: - ok - data properties: ok: type: boolean enum: - true description: Always `true` on success. data: $ref: '#/components/schemas/HugData' example: ok: true data: id: 6c2d1e0f-9a8b-4c7d-8e6f-5a4b3c2d1e0f hug_url: https://cliqhub.io/hugs/6c2d1e0f-9a8b-4c7d-8e6f-5a4b3c2d1e0f run_id: 0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f run_name: brave-otter team: code-review phase: approve iteration: 0 realm_id: 5b0c3a7e-2f4d-4b8e-9a51-7c1d2e3f4a5b realm_name: Production realm_slug: production org_slug: acme daemon_id: 7d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d title: 'Review: approve' prompt: Please review the fix. context: - type: markdown text: 3 findings fixed. requested_inputs: - name: decision type: enum required: true choices: - value: approve label: Approve - value: route:fix label: Send back to fix - value: reject label: Reject - name: comment type: text required: false multiline: true channels: - security ui: kind: gate status: open outcome: null expires_at: '2026-10-07T10:45:00Z' created_at: '2026-10-07T10:15:00Z' closed_at: null last_reminded_at: null not_sent_to: [] responses: [] '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 record but your role in its realm 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 record does not exist or is in a realm you cannot see (404 rather than 403, so its existence is not revealed). `not_found`: No Hug has this id, or you can't view runs in its realm. content: application/json: schema: $ref: '#/components/schemas/HubErr' examples: not_found: summary: not_found value: ok: false error: code: not_found message: Not found not_found (endpoint): summary: not_found (endpoint) value: ok: false error: Hug not found code: not_found '422': description: >- `invalid_params`: The body fails the request schema: a required field is missing or a value has the wrong type or format. The message lists every issue as `field: problem`. content: application/json: schema: $ref: '#/components/schemas/HubErr' examples: invalid_params: summary: invalid_params value: ok: false error: 'hug_id: Required' code: invalid_params '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: HugData: type: object description: A Hug with its answers. properties: id: type: string hug_url: type: string run_id: type: string run_name: type: string nullable: true team: type: string nullable: true phase: type: string iteration: type: integer realm_id: type: string realm_name: type: string nullable: true realm_slug: type: string nullable: true org_slug: type: string nullable: true daemon_id: type: string title: type: string prompt: type: string description: Markdown. context: type: array items: type: object additionalProperties: true description: >- Blocks: `markdown` (text), `artifact` (artifact_id, label), `checks` (results), `transcript` (turns). requested_inputs: type: array items: type: object additionalProperties: true description: >- What it asks for: `{ name, type, label, help, required, … }` with type `text`, `number`, `boolean`, `enum`, `file` or `channel` and its constraints. channels: type: array items: type: string ui: type: object nullable: true additionalProperties: true description: Presentation hints from the requester. status: type: string enum: - open - closed - expired - cancelled outcome: type: string nullable: true description: How the requester closed it. expires_at: type: string created_at: type: string closed_at: type: string nullable: true last_reminded_at: type: string nullable: true not_sent_to: type: array items: type: object properties: name: type: string channel: type: string description: >- People its channels reach who can't view runs in the realm, so it wasn't sent to them. responses: type: array items: $ref: '#/components/schemas/HugResponse' 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. HugResponse: type: object description: One person's answer. properties: response_id: type: string responder: type: object properties: user_id: type: string name: type: string via: type: array items: type: string description: The Hug's channels that reached them. values: type: object additionalProperties: true description: >- Answers keyed by requested-input name; a file input holds `{ artifact_id, name, size, content_type }`. comment: type: string nullable: true responded_at: type: string description: ISO timestamp. 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.