> ## 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 review

> Returns one review with its payload (what the agent asks), its verdict once decided, who claimed it, and its artifacts. Agents poll this to learn the decision.

Requires a realm member (or higher) with the `reviews.view` permission on the realm that owns the review given by `review_id`. A daemon's realm token (`cliq_dt_…`) from the same realm may also read it. Notification holder may view.



## OpenAPI

````yaml /openapi/hub-by-tag/hub-reviews.yaml post /v1/reviews/get_by_id
openapi: 3.0.3
info:
  title: 'CliqHub API: Reviews'
  version: 1.0.0
  description: >-
    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).
servers:
  - url: https://{host}
    variables:
      host:
        default: cliqhub.io
        description: CliqHub host
security: []
tags:
  - name: Reviews
    description: >-
      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).
paths:
  /v1/reviews/get_by_id:
    post:
      tags:
        - Reviews
      summary: Get a review
      description: >-
        Returns one review with its payload (what the agent asks), its verdict
        once decided, who claimed it, and its artifacts. Agents poll this to
        learn the decision.


        Requires a realm member (or higher) with the `reviews.view` permission
        on the realm that owns the review given by `review_id`. A daemon's realm
        token (`cliq_dt_…`) from the same realm may also read it. Notification
        holder may view.
      operationId: POST_v1_reviews_get_by_id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                review_id:
                  type: string
                  minLength: 1
                  description: The review.
                org_id:
                  type: string
                  format: uuid
                  description: >-
                    Required when the caller has no review_notifications row and
                    needs

                    org-scoped `reviews.view` — never invent from X-Org-Id.
              required:
                - review_id
            examples:
              default:
                value:
                  review_id: 4a3b2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d
      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/ReviewData'
              example:
                ok: true
                data:
                  id: 4a3b2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d
                  run_id: 0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f
                  run_name: brave-otter
                  daemon_id: 7d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d
                  realm_id: 5b0c3a7e-2f4d-4b8e-9a51-7c1d2e3f4a5b
                  realm_name: Production
                  realm_slug: production
                  org_slug: acme
                  team: code-review
                  phase: approve
                  payload:
                    title: Approve the fix
                    fields:
                      - name: release_notes
                        type: boolean
                  verdict: null
                  status: pending
                  route_targets:
                    - fix
                  created_at: '2026-10-07T10:15:00Z'
                  timeout_at: '2026-10-07T14:15:00Z'
                  completed_at: null
                  claimed_by: null
                  claimed_at: null
                  message_count: 0
                  artifacts: []
        '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 review does not exist or is in a realm you cannot
            see (404 rather than 403, so its existence is not revealed).


            `not_found`: No review has this id, 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
                not_found (endpoint):
                  summary: not_found (endpoint)
                  value:
                    ok: false
                    error: Review 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: 'review_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:
    ReviewData:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Review UUID
        run_id:
          type: string
          format: uuid
          description: Run that triggered this review
        run_name:
          type: string
          nullable: true
          description: Display name of the run; null when not set
        daemon_id:
          type: string
          nullable: true
          description: Daemon that ran the job; null for cloud runs
        realm_id:
          type: string
          format: uuid
          nullable: true
          description: Realm UUID; null for personal runs
        realm_name:
          type: string
          nullable: true
          description: Realm display name
        realm_slug:
          type: string
          nullable: true
          description: Realm slug
        org_slug:
          type: string
          nullable: true
          description: Org slug of the realm; null for personal realms
        team:
          type: string
          nullable: true
          description: Team slug that generated this review
        phase:
          type: string
          nullable: true
          description: Phase name that triggered the review
        payload:
          type: object
          additionalProperties: true
          description: Input payload for the review
        verdict:
          type: object
          additionalProperties: true
          nullable: true
          description: Reviewer decision payload; null while pending
        status:
          type: string
          enum:
            - pending
            - decided
            - completed
            - expired
          description: Lifecycle status of the review
        route_targets:
          type: array
          items:
            type: string
          nullable: true
          description: Notification route targets (usernames, channel IDs)
        created_at:
          type: string
          description: ISO timestamp of review creation
        timeout_at:
          type: string
          description: ISO timestamp when this review expires if not decided
        completed_at:
          type: string
          nullable: true
          description: ISO timestamp of completion; null while pending/decided
        claimed_by:
          type: string
          nullable: true
          description: Username of the reviewer who claimed this; null if unclaimed
        claimed_at:
          type: string
          nullable: true
          description: ISO timestamp of claim; null if unclaimed
        message_count:
          type: integer
          description: Number of chat messages on this review
        artifacts:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: Artifact UUID
              phase:
                type: string
                nullable: true
                description: >-
                  Phase name this artifact came from; null for run-level
                  artifacts
              kind:
                type: string
                description: Artifact kind (e.g. "file", "image", "text")
              name:
                type: string
                description: Display name of the artifact
              mime_type:
                type: string
                description: MIME type
              content:
                type: string
                nullable: true
                description: >-
                  Inline content for small artifacts; null for large (use
                  download URL)
              content_preview:
                type: string
                nullable: true
                description: Truncated preview for large artifacts
              sequence:
                type: integer
                description: Display ordering index
            required:
              - id
              - phase
              - kind
              - name
              - mime_type
              - content
              - content_preview
              - sequence
          description: Artifacts submitted with this review
      required:
        - id
        - run_id
        - run_name
        - daemon_id
        - realm_id
        - realm_name
        - realm_slug
        - org_slug
        - team
        - phase
        - payload
        - verdict
        - status
        - route_targets
        - created_at
        - timeout_at
        - completed_at
        - claimed_by
        - claimed_at
        - message_count
        - artifacts
    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.