> ## 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. # List your Hugs > Lists the Hugs addressed to you, newest first, in a realm or across an organization; by default only `open` ones. Only realms where you can view runs. Requires a signed-in user token; with `realm_id`, a realm member (or higher) with the `runs.view` permission on that realm; with `org_id`, a role with the `runs.view` permission in that organization. With neither, the results are limited to what you can see. ## OpenAPI ````yaml /openapi/hub-by-tag/hub-hugs.yaml post /v1/hugs/get 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: post: tags: - Hugs summary: List your Hugs description: >- Lists the Hugs addressed to you, newest first, in a realm or across an organization; by default only `open` ones. Only realms where you can view runs. Requires a signed-in user token; with `realm_id`, a realm member (or higher) with the `runs.view` permission on that realm; with `org_id`, a role with the `runs.view` permission in that organization. With neither, the results are limited to what you can see. operationId: POST_v1_hugs_get requestBody: required: true content: application/json: schema: type: object properties: realm_id: type: string description: Only Hugs in this realm. org_id: type: string format: uuid description: >- Every realm of this organization (required without `realm_id`). statuses: type: array items: type: string enum: - open - closed - expired - cancelled description: >- Statuses to include: `open` (default), `closed`, `expired`, `cancelled`. limit: type: integer minimum: 1 description: Page size. Default 50. offset: type: integer description: Rows to skip, for paging. examples: default: value: org_id: 2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f 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: type: object properties: items: type: array items: $ref: '#/components/schemas/HugListItem' total: type: integer offset: type: integer limit: type: integer example: ok: true data: items: - hug_id: 6c2d1e0f-9a8b-4c7d-8e6f-5a4b3c2d1e0f hug_url: >- https://cliqhub.io/hugs/6c2d1e0f-9a8b-4c7d-8e6f-5a4b3c2d1e0f title: 'Review: approve' realm_id: 5b0c3a7e-2f4d-4b8e-9a51-7c1d2e3f4a5b realm_name: Production realm_slug: production org_slug: acme run_id: 0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f run_name: brave-otter team: code-review phase: approve status: open responded: false created_at: 1759834500000 expires_at: 1759836300000 closed_at: null last_reminded_at: null total: 1 offset: 0 limit: 50 type: array '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 or organization but your role 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 or organization you named does not exist or you cannot see it. 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_params`: Neither `realm_id` nor `org_id` was sent.' content: application/json: schema: $ref: '#/components/schemas/HubErr' examples: invalid_params: summary: invalid_params value: ok: false error: >- org_id: org_id is required when listing Hugs without realm_id 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: HugListItem: type: object description: One Hug addressed to you. properties: hug_id: type: string hug_url: type: string description: The Hug page. title: type: string realm_id: type: string realm_name: type: string nullable: true realm_slug: type: string nullable: true org_slug: type: string nullable: true run_id: type: string run_name: type: string nullable: true team: type: string nullable: true phase: type: string status: type: string enum: - open - closed - expired - cancelled responded: type: boolean description: Whether you have answered. created_at: type: number description: Epoch ms. expires_at: type: number description: Epoch ms. closed_at: type: number nullable: true last_reminded_at: type: number nullable: true 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.