> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moonbounce.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List review items

> With status=open (the default), the reviewer's open items, oldest fill first and in rank order within it. Listing only reads: call POST /v1/review/items/fill (MCP `fill_review_queue`) first, which tops the queue up to the daily budget and expires items queued more than 3 days ago. Listing does not count as showing an item (see /shown). Blind items (spot checks) carry no prediction until answered. `remaining_today` counts every open item matching the filter, not just this page, even for status=done. status=done lists this reviewer's answered, withdrawn, skipped and expired items, newest settled first, then id descending. Settled items carry handled from the reviewer's latest answer (POST .../change replaces it; a correction through POST /v1/feedback does not). Skipped and expired blind items keep their prediction and summary hidden. With counts=true, a first page (no cursor) of either state also carries `counts`: the reviewer's open, done and done-today totals and a per-decision breakdown, ignoring decision_id; cursor pages and pages that don't ask omit it.



## OpenAPI

````yaml /openapi.json get /v1/review/items
openapi: 3.1.0
info:
  title: Moonbounce Decisions API
  version: 0.0.0
  description: >-
    Moonbounce decisions: evaluate an item's state against a decision structure
    (System One questions, attributes you supply and aggregations over both),
    record feedback and seed examples, review a ranked queue, and improve the
    structure through suggestions that ship as code diffs, each with a preview
    (backtest) and an evidence label.


    **Authentication.** Send an API key as `Authorization: Bearer <key>` on
    every operation except `GET /health` and `POST /v1/structures/hash`. Call
    the API from a server, never a browser: a key must not reach one, and the
    API sends no CORS headers. A key belongs to one organization and one
    environment: production, or test for a key with the `env:test` permission.
    Test traffic never counts as production traffic.


    **Requests.** JSON bodies (`Content-Type: application/json`) of at most 1
    MB, parsed strictly: duplicate keys, lone surrogates, integers outside
    ±(2^53 - 1), `__proto__` keys, U+0000 and nesting deeper than 64 are a 400.


    **Retries.** Send an `Idempotency-Key` on every POST under /v1 that takes
    one (all but `POST /v1/structures/hash` and `POST /v1/review/items/fill`,
    whose retry is another fill within the day's budget). Keep it for the
    request's retries. The same key with the same request returns the first
    stored result, marked `Idempotent-Replayed: true`, for 24 hours (410 if that
    result was since deleted); with another request it is 422
    IDEMPOTENCY_KEY_REUSED. Keys are scoped to the organization and environment
    across every operation, so use a fresh key per request. A request that
    failed before its result was stored runs again when retried. 429 and 503
    under /v1 may carry `Retry-After` (seconds); a daily QUOTA_EXCEEDED cap
    instead names its reset time.


    **Errors.** Every error under /v1 is `{"error": {"type", "message",
    "reason"?, "param"?, "details"?}}` (ErrorBody); `GET /health` answers its
    own shape. Every response carries a `Request-Id` header. Rate limits apply
    per key, and per client IP for requests without a valid key; a 429
    RATE_LIMITED carries `Retry-After`.
servers:
  - url: https://api.moonbounce.ai
    description: Production
security: []
paths:
  /v1/review/items:
    get:
      tags:
        - review
      summary: List review items
      description: >-
        With status=open (the default), the reviewer's open items, oldest fill
        first and in rank order within it. Listing only reads: call POST
        /v1/review/items/fill (MCP `fill_review_queue`) first, which tops the
        queue up to the daily budget and expires items queued more than 3 days
        ago. Listing does not count as showing an item (see /shown). Blind items
        (spot checks) carry no prediction until answered. `remaining_today`
        counts every open item matching the filter, not just this page, even for
        status=done. status=done lists this reviewer's answered, withdrawn,
        skipped and expired items, newest settled first, then id descending.
        Settled items carry handled from the reviewer's latest answer (POST
        .../change replaces it; a correction through POST /v1/feedback does
        not). Skipped and expired blind items keep their prediction and summary
        hidden. With counts=true, a first page (no cursor) of either state also
        carries `counts`: the reviewer's open, done and done-today totals and a
        per-decision breakdown, ignoring decision_id; cursor pages and pages
        that don't ask omit it.
      operationId: listReviewItems
      parameters:
        - schema:
            type: string
            enum:
              - open
              - done
            default: open
          required: false
          name: status
          in: query
        - schema:
            $ref: '#/components/schemas/DecisionId'
          required: false
          name: decision_id
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
          required: false
          name: limit
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 1024
          required: false
          name: cursor
          in: query
        - schema:
            type: boolean
            default: false
            description: >-
              `true` adds `counts` to a first page (no `cursor`). Default
              `false`.
          required: false
          description: '`true` adds `counts` to a first page (no `cursor`). Default `false`.'
          name: counts
          in: query
      responses:
        '200':
          description: The queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewQueue'
        '400':
          description: 'Invalid request: `param` names the field at fault when one applies'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '401':
          description: Missing or invalid API key (reason KEY_INVALID)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: The key may not do this
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '429':
          description: >-
            RATE_LIMITED: retry after Retry-After seconds; QUOTA_EXCEEDED:
            details.reset_at gives the daily reset time (no Retry-After)
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying, when waiting helps.
              required: false
              description: Seconds to wait before retrying, when waiting helps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '503':
          description: >-
            Temporarily unavailable, with Retry-After (for example reason
            AUTH_UNAVAILABLE, ENGINE_UNAVAILABLE or STORE_UNAVAILABLE): retry
            with the same Idempotency-Key
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying, when waiting helps.
              required: true
              description: Seconds to wait before retrying, when waiting helps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
        - bearerAuth:
            - decisions:develop
components:
  schemas:
    DecisionId:
      type: string
      pattern: ^[a-z][a-z0-9_.-]{0,127}$
    ReviewQueue:
      type: object
      properties:
        environment:
          $ref: '#/components/schemas/Environment'
        items:
          type: array
          items:
            $ref: '#/components/schemas/ReviewItem'
        next_cursor:
          type:
            - string
            - 'null'
        has_more:
          type: boolean
        remaining_today:
          type: integer
          minimum: 0
        counts:
          $ref: '#/components/schemas/ReviewCounts'
      required:
        - environment
        - items
        - next_cursor
        - has_more
        - remaining_today
      additionalProperties: true
      x-moonbounce-sdk-known-fields: true
    ErrorBody:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              $ref: '#/components/schemas/ErrorType'
            reason:
              type: string
              pattern: ^[A-Z][A-Z0-9_]+$
              description: >-
                Set where a caller can act on it, one of the reasons in the
                ErrorReason schema. New reasons may be added: treat an unknown
                one by the status and `type`.
            message:
              type: string
              description: For people; don't parse it.
            param:
              type: string
              description: >-
                The request field at fault, as a dotted path
                (`attribute_values.region`, `claims.1.value`).
            details:
              type: object
              properties:
                issues:
                  type: array
                  items:
                    $ref: '#/components/schemas/ErrorIssue'
              additionalProperties: {}
          required:
            - type
            - message
          additionalProperties: true
          x-moonbounce-sdk-known-fields: true
      required:
        - error
      additionalProperties: true
      x-moonbounce-sdk-known-fields: true
    Environment:
      type: string
      enum:
        - production
        - test
      description: >-
        The environment of the key that made the call: `production` or `test`.
        Evaluations, feedback, reviews and suggestions are separate per
        environment; registered structures are shared.
    ReviewItem:
      type: object
      properties:
        environment:
          $ref: '#/components/schemas/Environment'
        id:
          $ref: '#/components/schemas/InbId'
        decision_id:
          $ref: '#/components/schemas/DecisionIdOutput'
        decision_index:
          type: integer
          minimum: 0
        evaluation_id:
          $ref: '#/components/schemas/EvlIdOutput'
        version:
          type: object
          properties:
            structure_hash:
              $ref: '#/components/schemas/StructureHashOutput'
          required:
            - structure_hash
          additionalProperties: true
          x-moonbounce-sdk-known-fields: true
        lane:
          $ref: '#/components/schemas/ReviewLane'
        reason:
          type: object
          properties:
            tag:
              $ref: '#/components/schemas/ReviewReasonTag'
            text:
              type: string
          required:
            - tag
            - text
          additionalProperties: true
          x-moonbounce-sdk-known-fields: true
        tags:
          type: array
          items:
            $ref: '#/components/schemas/ReviewReasonTag'
          minItems: 1
        blind:
          type: boolean
        rank:
          type: number
        queued_at:
          $ref: '#/components/schemas/Timestamp'
        shown_at:
          $ref: '#/components/schemas/Timestamp'
        content:
          anyOf:
            - $ref: '#/components/schemas/ReviewContent'
            - type: 'null'
        summary:
          type: string
        outcome_choices:
          type: array
          items:
            $ref: '#/components/schemas/OutcomeChoice'
        cuts:
          type: array
          items:
            type: object
            properties:
              at:
                type: number
              outcome:
                $ref: '#/components/schemas/NameOutput'
            required:
              - at
              - outcome
            additionalProperties: true
            x-moonbounce-sdk-known-fields: true
          minItems: 1
        below:
          $ref: '#/components/schemas/NameOutput'
        questions:
          type: array
          items:
            $ref: '#/components/schemas/ReviewQuestion'
        prediction:
          $ref: '#/components/schemas/ReviewPrediction'
        handled:
          $ref: '#/components/schemas/ReviewHandled'
      required:
        - environment
        - id
        - decision_id
        - evaluation_id
        - version
        - lane
        - reason
        - tags
        - blind
        - rank
        - queued_at
        - content
        - outcome_choices
        - questions
      additionalProperties: true
      x-moonbounce-sdk-known-fields: true
    ReviewCounts:
      type: object
      properties:
        open:
          type: integer
          minimum: 0
          description: >-
            Open items: not answered, skipped, expired or withdrawn, and the
            evaluation has no human feedback. It equals an unfiltered listing's
            `remaining_today`. Listing never fills: POST /v1/review/items/fill
            (MCP `fill_review_queue`) tops the queue up.
        done:
          type: integer
          minimum: 0
          description: >-
            Settled items: answered (including later withdrawn), skipped (either
            reason) or expired.
        done_today:
          type: integer
          minimum: 0
          description: >-
            Settled items handled since 00:00 UTC today, by the time
            `handled.at` shows: withdrawn_at for a withdrawn answer, else when
            it was answered, skipped or expired.
        by_decision:
          type: array
          items:
            $ref: '#/components/schemas/ReviewDecisionCount'
          description: >-
            Every decision with an item in `open` or `done`, in `decision_index`
            order. Sums to the totals.
      required:
        - open
        - done
        - done_today
        - by_decision
      additionalProperties: true
      description: >-
        The reviewer's queue totals in this organization and environment, for
        counts and a decision filter. Only when asked for (`counts=true`) on a
        first page (no `cursor`), for either state. They ignore `decision_id`;
        items whose evaluation was deleted are not counted.
      x-moonbounce-sdk-known-fields: true
    ErrorType:
      type: string
      enum:
        - invalid_request
        - authentication
        - permission_denied
        - not_found
        - conflict
        - rate_limited
        - engine_failed
        - unavailable
        - internal
    ErrorIssue:
      type: object
      properties:
        param:
          type: string
        code:
          type: string
          pattern: ^[A-Z][A-Z0-9_]+$
          description: >-
            Stable, extensible issue code; unknown codes still have a parameter
            and human-readable message.
        message:
          type: string
      required:
        - param
        - code
        - message
      additionalProperties: true
      x-moonbounce-sdk-known-fields: true
    InbId:
      type: string
      pattern: >-
        ^inb_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
    DecisionIdOutput:
      type: string
      pattern: ^[a-z][a-z0-9_.-]{0,127}$
    EvlIdOutput:
      type: string
      pattern: >-
        ^evl_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
    StructureHashOutput:
      type: string
      pattern: ^sha256:[0-9a-f]{64}$
    ReviewLane:
      type: string
      enum:
        - active
        - random
    ReviewReasonTag:
      type: string
      enum:
        - uncertain
        - novel
        - spot_check
        - near_cut
    Timestamp:
      type: string
      format: date-time
    ReviewContent:
      type: object
      properties:
        state:
          description: The state the questions were asked about, as submitted.
        attribute_values:
          type: object
          additionalProperties:
            anyOf:
              - type: string
                maxLength: 200
              - type: number
              - type: boolean
          description: The attribute values the call used, defaults applied.
      required:
        - state
      additionalProperties: true
      x-moonbounce-sdk-known-fields: true
    OutcomeChoice:
      type: object
      properties:
        outcome:
          $ref: '#/components/schemas/Outcome'
      required:
        - outcome
      additionalProperties: true
      x-moonbounce-sdk-known-fields: true
    NameOutput:
      type: string
      pattern: ^[a-z][a-z0-9_]{0,63}$
    ReviewQuestion:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/NameOutput'
        question:
          type: string
          description: >-
            The question asked: `instructions.question`, or the instructions
            themselves when they are text.
        context:
          type: string
          description: >-
            Supporting instructions: context as text or JSON; all non-question
            fields as compact JSON when additional fields such as policy or
            examples are present.
        criteria:
          type: object
          properties:
            'true':
              type: string
            'false':
              type: string
          additionalProperties: true
          description: What counts as yes and as no, as authored.
          x-moonbounce-sdk-known-fields: true
        reads:
          type: array
          items:
            $ref: '#/components/schemas/StatePathOutput'
          description: >-
            The paths the question reads, as authored (`state.message`); absent
            when it reads the whole state.
      required:
        - name
        - question
      additionalProperties: true
      x-moonbounce-sdk-known-fields: true
    ReviewPrediction:
      oneOf:
        - type: object
          properties:
            via:
              type: string
              description: >-
                A zero-based rule index, `cases.<label>` for an exact matched
                case, or `else` for the fallback.
            answers:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/NoulAnswer'
              description: Each question's answer, as the evaluation stored it.
            aggregations:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/AggregationResult'
              description: Every aggregation's value, as on the evaluation.
            status:
              type: string
              enum:
                - computed
            value:
              type: number
            outcome:
              not: {}
              description: 'Must be absent: a computed result is a number, with no outcome.'
              x-moonbounce-absent: true
            missing:
              type: array
              items:
                $ref: '#/components/schemas/FeatureRefOutput'
              description: >-
                The questions the result depends on (through `result` and every
                aggregation on its path) that have no answer, abstained or
                failed, as `questions.x` paths in authored question order.
                Absent when none is missing; reported for every status. A caller
                who must not act on partial evidence checks that it is absent,
                for example `status === "decided" && !missing`.
          required:
            - answers
            - aggregations
            - status
            - value
          additionalProperties: true
          x-moonbounce-sdk-known-fields: true
        - type: object
          properties:
            via:
              type: string
              description: >-
                A zero-based rule index, `cases.<label>` for an exact matched
                case, or `else` for the fallback.
            answers:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/NoulAnswer'
              description: Each question's answer, as the evaluation stored it.
            aggregations:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/AggregationResult'
              description: Every aggregation's value, as on the evaluation.
            status:
              type: string
              enum:
                - decided
            value:
              type: number
            outcome:
              $ref: '#/components/schemas/Outcome'
            missing:
              type: array
              items:
                $ref: '#/components/schemas/FeatureRefOutput'
              description: >-
                The questions the result depends on (through `result` and every
                aggregation on its path) that have no answer, abstained or
                failed, as `questions.x` paths in authored question order.
                Absent when none is missing; reported for every status. A caller
                who must not act on partial evidence checks that it is absent,
                for example `status === "decided" && !missing`.
          required:
            - answers
            - aggregations
            - status
            - outcome
          additionalProperties: true
          x-moonbounce-sdk-known-fields: true
        - type: object
          properties:
            via:
              type: string
              description: >-
                A zero-based rule index, `cases.<label>` for an exact matched
                case, or `else` for the fallback.
            answers:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/NoulAnswer'
              description: Each question's answer, as the evaluation stored it.
            aggregations:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/AggregationResult'
              description: Every aggregation's value, as on the evaluation.
            status:
              type: string
              enum:
                - abstained
            value:
              not: {}
              description: 'Must be absent: an abstained result has no value.'
              x-moonbounce-absent: true
            outcome:
              $ref: '#/components/schemas/Outcome'
            missing:
              type: array
              items:
                $ref: '#/components/schemas/FeatureRefOutput'
              description: >-
                The questions the result depends on (through `result` and every
                aggregation on its path) that have no answer, abstained or
                failed, as `questions.x` paths in authored question order.
                Absent when none is missing; reported for every status. A caller
                who must not act on partial evidence checks that it is absent,
                for example `status === "decided" && !missing`.
          required:
            - answers
            - aggregations
            - status
          additionalProperties: true
          x-moonbounce-sdk-known-fields: true
    ReviewHandled:
      type: object
      properties:
        status:
          type: string
          enum:
            - confirmed
            - changed
            - answered
            - unsure
            - skipped
            - expired
            - withdrawn
        at:
          $ref: '#/components/schemas/Timestamp'
        feedback_id:
          $ref: '#/components/schemas/FbkIdOutput'
        changed_at:
          $ref: '#/components/schemas/Timestamp'
        outcome:
          $ref: '#/components/schemas/Outcome'
        matched:
          type: boolean
      required:
        - status
        - at
      additionalProperties: true
      x-moonbounce-sdk-known-fields: true
    ReviewDecisionCount:
      type: object
      properties:
        decision_id:
          $ref: '#/components/schemas/DecisionIdOutput'
        decision_index:
          type: integer
          minimum: 0
          description: >-
            The decision's organization-wide creation order (created_at,
            decision_id), zero-based, as on items.
        open:
          type: integer
          minimum: 0
          description: This reviewer's open items for the decision, counted as `open` is.
        done:
          type: integer
          minimum: 0
          description: >-
            This reviewer's settled items for the decision, counted as `done`
            is.
        newest_open_version:
          type: object
          properties:
            structure_hash:
              $ref: '#/components/schemas/StructureHashOutput'
          required:
            - structure_hash
          additionalProperties: true
          description: >-
            The evaluated structure hash of this reviewer's most recently queued
            open item for the decision (latest `queued_at`, then highest id), as
            an item's `version`. Omitted when nothing is open.
          x-moonbounce-sdk-known-fields: true
        open_versions:
          type: integer
          minimum: 0
          description: >-
            How many distinct structure versions this reviewer's open items for
            the decision carry.
      required:
        - decision_id
        - decision_index
        - open
        - done
        - open_versions
      additionalProperties: true
      x-moonbounce-sdk-known-fields: true
    Outcome:
      type: string
      minLength: 1
      maxLength: 200
      description: >-
        An outcome name, or the exact enum label when a string attribute is the
        result.
    StatePathOutput:
      type: string
      minLength: 1
      maxLength: 256
      description: >-
        `state.<key>` or a nested object path such as
        `state.order.customer.tier`: keys of an object `state`. A key has no
        `.`, `[` or `]`. Array indexes are not supported yet.
      examples:
        - state.message
        - state.order.order_total_usd
    NoulAnswer:
      anyOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - noul
            noul:
              type: number
              minimum: 0
              maximum: 1
          required:
            - type
            - noul
          additionalProperties: true
          x-moonbounce-sdk-known-fields: true
        - type: object
          properties:
            type:
              type: string
              enum:
                - noul
            abstained:
              type: boolean
              enum:
                - true
          required:
            - type
            - abstained
          additionalProperties: true
          x-moonbounce-sdk-known-fields: true
        - type: object
          properties:
            type:
              type: string
              enum:
                - noul
            failed:
              type: boolean
              enum:
                - true
          required:
            - type
            - failed
          additionalProperties: true
          x-moonbounce-sdk-known-fields: true
      description: P(true), or why there is no answer.
    AggregationResult:
      type: object
      properties:
        type:
          type: string
        value:
          type: number
        outcome:
          $ref: '#/components/schemas/Outcome'
        via:
          type: string
          description: >-
            A zero-based rule index, `cases.<label>` for an exact matched case,
            or `else` for the fallback.
        missing:
          type: array
          items:
            $ref: '#/components/schemas/FeatureRefOutput'
          description: >-
            weighted_mean only: the inputs dropped for having no answer, as
            written (`questions.x`).
        abstained:
          type: boolean
          enum:
            - true
      required:
        - type
      additionalProperties: true
      description: >-
        An aggregation's value. `value` for numbers (for bands, the input it
        cut); `outcome` for bands, rules and match; `via` is the zero-based rule
        index, `cases.<label>` for a matched case, or `else` for the fallback;
        `abstained` when unknown.
      x-moonbounce-sdk-known-fields: true
    FeatureRefOutput:
      type: string
      minLength: 1
      maxLength: 80
      description: >-
        A feature's path: `questions.<name>`, `attributes.<name>` or
        `aggregations.<name>`.
      examples:
        - questions.asks_for_refund
        - aggregations.band
    FbkIdOutput:
      type: string
      pattern: >-
        ^fbk_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key, sent as `Authorization: Bearer <key>`. Each operation lists
        the scope its key needs: `decisions:evaluate` (evaluate and read
        evaluations), `decisions:feedback` (your app's feedback) or
        `decisions:develop` (everything else, including owner feedback and the
        review queue). An operation listing no scope takes any scoped key. A key
        with no scope, or without the operation's, gets 403 INSUFFICIENT_SCOPE.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.