Derive Review API

openapi: 3.2.0
info:
  title: Derive Review API
  version: 1.0.0
  description: 'Derive''s HTTP API. Every response shape here is the single source of truth for the web client — generated from the same Zod schemas that back this reference, so the docs never drift from the running API.


    **Auth:** a session cookie (browser) or a bearer token (agents and the CLI). Most write routes are scoped to the caller''s active workspace. The `/v1` paths are the stable product surface; `/openapi.json` serves this spec and `/docs` renders it.'
tags:
- name: Review
  description: 'Review rounds on an artifact: request a review, or send it back with a note.'
paths:
  /v1/artifacts/{shortId}/review/send-back:
    post:
      tags:
      - Review
      summary: Send back a review with the human's answers
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                note:
                  type: string
                  maxLength: 10000
                  description: The human's note to the agent — answers, asks, or the go-signal ("good to go"). Carried on the round and surfaced in the agent's catch_up.
      responses:
        '200':
          description: The round, now sent_back.
          content:
            application/json:
              schema:
                type: object
                properties:
                  round:
                    $ref: '#/components/schemas/ReviewRound'
                required:
                - round
      operationId: postV1ArtifactsByShortIdReviewSendBack
      x-operation-id-source: derived
  /v1/artifacts/{shortId}/review:
    get:
      tags:
      - Review
      summary: List an artifact's review rounds and the pending one, if any
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      responses:
        '200':
          description: All rounds (newest first) and the current pending round or null.
          content:
            application/json:
              schema:
                type: object
                properties:
                  rounds:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReviewRound'
                    description: All review rounds, newest first.
                  pending:
                    allOf:
                    - $ref: '#/components/schemas/ReviewRound'
                    - description: The current unsettled round, or null if none is pending.
                required:
                - rounds
                - pending
      operationId: getV1ArtifactsByShortIdReview
      x-operation-id-source: derived
components:
  schemas:
    ReviewRound:
      type: object
      properties:
        id:
          type: string
        artifact_id:
          type: string
        version:
          type: number
          description: The artifact version this round is reviewing.
        requested_by:
          type: string
          description: Who asked for the review (usually the agent that published).
        requested_by_name:
          type:
          - string
          - 'null'
          description: The requester's name when the round opened (a row from before the name was kept is named from the directory, while the agent exists).
        requested_by_kind:
          type: string
          enum:
          - user
          - agent
          description: What kind of principal asked, from the recorded id.
        requested_for:
          type: string
          description: The person asked to answer this round.
        state:
          type: string
          enum:
          - pending
          - sent_back
          description: 'Round state: pending, or sent_back (the answers came back — a note saying go IS the go-signal).'
        note:
          type:
          - string
          - 'null'
          description: Free-text note attached to the round; null if none.
        resolved_by_name:
          type:
          - string
          - 'null'
          description: The human who settled the round; null while pending, or when the store has no name for the resolver.
        created_at:
          type: string
        resolved_at:
          type:
          - string
          - 'null'
          description: When it was sent back; null while pending.
      required:
      - id
      - artifact_id
      - version
      - requested_by
      - requested_by_name
      - requested_by_kind
      - requested_for
      - state
      - note
      - resolved_by_name
      - created_at
      - resolved_at