Deliverd Comments API

openapi: 3.2.0
info:
  title: Deliverd Dev Comments API
  version: 1.0.0
  x-refined-note:
  - x-source differs across the merged source definitions and was not carried
  description: 'Operations tagged Comments across 2 of this provider''s published API definitions: deliverd-dev-openapi.json, deliverd-dev-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://deliverd.dev
  description: 'Deliverd REST API (paths carry the /api/v1 prefix; https://deliverd.dev/llms.txt: "REST API: https://deliverd.dev/api/v1")'
tags:
- name: Comments
paths:
  /api/v1/comments/{threadId}/resolve:
    post:
      summary: Resolve or reopen a comment thread
      description: Marks a thread resolved, or reopens it with `reopen`. The note is for the reader who raised it, so say what changed rather than that it was handled — resolving without a new version is allowed and is worth explaining when you do it.
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: threadId
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                note:
                  type: string
                  maxLength: 10000
                reopen:
                  type: boolean
      responses:
        '200':
          description: Thread status after the change
      tags:
      - Comments
      operationId: postApiV1CommentsByThreadIdResolve
      x-operation-id-source: derived
  /api/v1/comments:
    get:
      summary: Every open comment thread in the organisation
      description: '"Is anything waiting on me?", without naming a report first. `GET /reports/{idOrSlug}/comments` answers it one report at a time, which means walking every report to find the two with feedback on them.


        Newest activity first, with the quoted passage and who wrote it — fetch the thread itself from the report''s own endpoint once you know where to look. Threads on archived reports are left out: the URL does not serve, so nothing can be done about them until it is unarchived.'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 200
          description: Rows per page. Above the maximum you get the maximum, not an error.
        required: false
        description: Rows per page. Above the maximum you get the maximum, not an error.
        name: limit
        in: query
      - schema:
          type: string
          description: nextCursor from a previous response. One we did not issue is refused.
        required: false
        description: nextCursor from a previous response. One we did not issue is refused.
        name: cursor
        in: query
      responses:
        '200':
          description: Open threads, newest activity first
          content:
            application/json:
              schema:
                type: object
                properties:
                  threads:
                    type: array
                    items:
                      type: object
                      properties:
                        threadId:
                          type: string
                        reportId:
                          type: string
                        reportTitle:
                          type: string
                        reportSlug:
                          type: string
                        reportOwnerId:
                          type:
                          - string
                          - 'null'
                          description: Who owns the report — filter on it to find your own
                        quote:
                          type:
                          - string
                          - 'null'
                        author:
                          type: string
                        authorType:
                          type: string
                        messages:
                          type: number
                        lastActivityAt:
                          type: string
                      required:
                      - threadId
                      - reportId
                      - reportTitle
                      - reportSlug
                      - reportOwnerId
                      - quote
                      - author
                      - authorType
                      - messages
                      - lastActivityAt
                  nextCursor:
                    type:
                    - string
                    - 'null'
                    description: Pass back as ?cursor= for the next page. Null means this is the end.
                required:
                - threads
                - nextCursor
      tags:
      - Comments
      operationId: getApiV1Comments
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key (dlv_…) created in Settings → API tokens, or an OAuth access token (dlvo_…). Every route below can answer `401 auth_error` — the credential was not accepted — or `403 insufficient_scope`, which is a different thing: the credential is fine and was not issued with the scope this route needs. Reissue it with that scope rather than replacing it with another of the same ones. Older clients may still branch on `auth_error` for both.'
x-refined-from:
- deliverd-dev-openapi.json
- deliverd-dev-openapi.yml