Derive Comments API

openapi: 3.2.0
info:
  title: Derive Comments 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: Comments
  description: Threaded, anchored comments with reactions, edits, and resolution.
paths:
  /v1/artifacts/{shortId}/comments:
    post:
      tags:
      - Comments
      summary: Post a comment (new thread) or a reply (with thread_id)
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      responses:
        '201':
          description: The created comment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
      operationId: postV1ArtifactsByShortIdComments
      x-operation-id-source: derived
    get:
      tags:
      - Comments
      summary: List an artifact's comments (authenticated readers only)
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      - schema:
          type: string
          enum:
          - open
          - resolved
          - outdated
        required: false
        name: state
        in: query
      responses:
        '200':
          description: The artifact's comments, each flagged whether its anchor still resolves.
          content:
            application/json:
              schema:
                type: object
                properties:
                  comments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Comment'
                required:
                - comments
      operationId: getV1ArtifactsByShortIdComments
      x-operation-id-source: derived
  /v1/artifacts/{shortId}/comments/{commentId}/resolve:
    post:
      tags:
      - Comments
      summary: Resolve or reopen the thread a comment belongs to
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      - schema:
          type: string
        required: true
        name: commentId
        in: path
      responses:
        '200':
          description: The thread's new state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  thread_id:
                    type: string
                  state:
                    type: string
                    enum:
                    - open
                    - resolved
                    description: 'The thread''s new state: resolved, or open when reopened.'
                  updated:
                    type: number
                    description: Number of comments in the thread whose state changed.
                required:
                - thread_id
                - state
                - updated
      operationId: postV1ArtifactsByShortIdCommentsByCommentIdResolve
      x-operation-id-source: derived
  /v1/artifacts/{shortId}/comments/{commentId}/react:
    post:
      tags:
      - Comments
      summary: Toggle a reaction on a comment
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      - schema:
          type: string
        required: true
        name: commentId
        in: path
      responses:
        '200':
          description: The updated comment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
      operationId: postV1ArtifactsByShortIdCommentsByCommentIdReact
      x-operation-id-source: derived
  /v1/artifacts/{shortId}/comments/{commentId}:
    patch:
      tags:
      - Comments
      summary: Edit a comment's body (author only)
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      - schema:
          type: string
        required: true
        name: commentId
        in: path
      responses:
        '200':
          description: The edited comment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
      operationId: patchV1ArtifactsByShortIdCommentsByCommentId
      x-operation-id-source: derived
    delete:
      tags:
      - Comments
      summary: Delete a comment (author only); tombstoned if replies remain, else removed
      parameters:
      - schema:
          type: string
        required: true
        name: shortId
        in: path
      - schema:
          type: string
        required: true
        name: commentId
        in: path
      responses:
        '200':
          description: The comment's final deleted state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
      operationId: deleteV1ArtifactsByShortIdCommentsByCommentId
      x-operation-id-source: derived
components:
  schemas:
    Comment:
      type: object
      properties:
        id:
          type: string
        artifact_id:
          type: string
          description: The artifact the comment is on.
        thread_id:
          type: string
          description: The thread this comment belongs to; equals id for the thread's root comment.
        base_version:
          type: number
          description: Artifact version this comment was anchored against.
        path:
          type:
          - string
          - 'null'
          description: File within a bundle the comment targets; null if not file-scoped.
        anchor:
          type:
          - string
          - 'null'
          description: Serialized text-quote or element anchor locating the comment; null if unanchored.
        body_md:
          type: string
          description: Comment body in Markdown; blanked when the comment is deleted.
        author:
          type: string
          description: Author's display name; "anonymous" for an anonymous poster.
        author_id:
          type:
          - string
          - 'null'
          description: 'Stable id of the author: a user id, an agent id, or "derive" for an @Derive reply; null for anonymous or legacy rows.'
        author_kind:
          type: string
          enum:
          - user
          - agent
          - anonymous
          description: What kind of principal wrote it, from the recorded id.
        options:
          type:
          - array
          - 'null'
          items:
            type: string
          description: 'On a question''s root comment: the choices it offers. A reply (a choice or other words) answers it.'
        resolution:
          type:
          - object
          - 'null'
          properties:
            at:
              type: string
            by:
              type:
              - string
              - 'null'
              description: The resolver's display name at the time.
            by_id:
              type:
              - string
              - 'null'
            by_kind:
              type:
              - string
              - 'null'
              enum:
              - user
              - agent
              - null
            version:
              type:
              - number
              - 'null'
              description: The version whose publish resolved the thread; null for a hand resolve.
          required:
          - at
          - by
          - by_id
          - by_kind
          - version
          description: 'On a resolved thread''s root: who settled it, when, and by which version.'
        state:
          type: string
          enum:
          - open
          - resolved
          - outdated
          description: 'Thread state: open, resolved, or outdated (the quoted text changed).'
        created_at:
          type: string
        anchored:
          type: boolean
          description: Whether the anchor still resolves against the current version (list only).
        reactions:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Emoji → list of reactor display names.
        edited:
          type: boolean
          description: True if the body was edited after posting.
        edited_at:
          type:
          - string
          - 'null'
          description: When the comment was last edited; null if never.
        deleted:
          type: boolean
          description: True if soft-deleted; the row stays but the body is blanked.
        mentions:
          type: array
          items:
            $ref: '#/components/schemas/Mention'
          description: Users or agents @mentioned in the comment body.
      required:
      - id
      - artifact_id
      - thread_id
      - base_version
      - path
      - anchor
      - body_md
      - author
      - author_kind
      - state
      - created_at
    Mention:
      type: object
      properties:
        id:
          type: string
          description: Id of the mentioned person or agent.
        name:
          type: string
      required:
      - id
      - name