Debriefing Digests API

openapi: 3.2.0
info:
  title: Debriefing Read Digests API
  version: 1.0.0
  summary: Read competitors, signals, digests, and battlecards for one workspace.
  description: 'A JSON API for one organization. Create an API key in Settings → Integrations.

    The same key authenticates the MCP endpoint at `POST /mcp`.


    Every key reads. A key writes only through a scope ticked when the key is made. The one

    scope today is `watchlist:add`, which lets `POST /api/v1/competitors` add a competitor and

    nothing else. Existing keys have no scopes and stay read-only.


    Clients may name themselves in the `X-Debriefing-Source` header, a short lowercase slug

    such as `google-sheets-addon`. A competitor added through the API records it.


    Every request is scoped to the organization that owns the key. The free week that unlocks

    the dashboard does not unlock this API. A paid subscription is required.


    Blank fields are omitted from response objects. Empty summary domains are omitted from a

    competitor dossier.


    Every error is RFC 9457 problem details, sent as `application/problem+json`, with a

    machine-readable `code` and a `hint`. See the `Problem` schema and

    https://debriefing.io/developers#errors.


    This file is also served as JSON at `/openapi.json`.'
  contact:
    name: Debriefing
    url: https://debriefing.io
servers:
- url: https://debriefing.io
  description: Production
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Digests
  description: Generated digests for this workspace.
paths:
  /api/v1/digests:
    get:
      tags:
      - Digests
      operationId: listDigests
      summary: List generated digests
      description: 'Returns digests with status `generated`, newest coverage period first. Default page

        size is 50. Maximum page size is 50.'
      parameters:
      - name: type
        in: query
        schema:
          type: string
        description: Limit to one debrief type, for example `daily_digest` or `weekly_tldr`.
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A page of digests.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - page
                - per_page
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Digest'
                  page:
                    type: integer
                    minimum: 1
                  per_page:
                    type: integer
                    minimum: 1
                    maximum: 50
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/digests/{id}:
    get:
      tags:
      - Digests
      operationId: getDigest
      summary: Get one digest
      description: Looks up a generated digest by slug first, then by id.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Digest slug or numeric id.
      responses:
        '200':
          description: One digest.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Digest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    InternalError:
      description: An error occurred on the server. The body holds no internal detail.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://debriefing.io/developers#errors-internal_error
            title: Internal error
            status: 500
            detail: An error occurred on the server.
            code: internal_error
            hint: Send the request again later. If the error continues, email team@debriefing.io with the request_id.
            instance: /api/v1/signals
            request_id: 5f1c2b7e-9a41-4c1e-8d0e-2b1f3a6c7d80
            error: An error occurred on the server.
    NotFound:
      description: No matching record in this workspace.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://debriefing.io/developers#errors-not_found
            title: Not found
            status: 404
            detail: No such competitor.
            code: not_found
            hint: Check the path and the id. The list routes, such as /api/v1/competitors, give the ids that this key can read.
            instance: /api/v1/competitors/999
            request_id: 5f1c2b7e-9a41-4c1e-8d0e-2b1f3a6c7d80
            error: No such competitor.
    Unauthorized:
      description: Missing, wrong, or revoked API key.
      headers:
        WWW-Authenticate:
          schema:
            type: string
          example: Bearer realm="Debriefing API"
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://debriefing.io/developers#errors-invalid_api_key
            title: API key missing or not valid
            status: 401
            detail: A valid API key is required.
            code: invalid_api_key
            hint: 'Send a valid key as Authorization: Bearer dbk_… or as X-API-Key. A workspace admin creates keys in Organization settings, under Integrations.'
            instance: /api/v1/competitors
            request_id: 5f1c2b7e-9a41-4c1e-8d0e-2b1f3a6c7d80
            error: A valid API key is required.
    PaymentRequired:
      description: The key's organization does not have a paid subscription.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://debriefing.io/developers#errors-paid_plan_required
            title: Paid plan required
            status: 402
            detail: Choose a paid plan to use this feature.
            code: paid_plan_required
            hint: Choose a paid plan for this workspace on /pricing. The free week does not include the API.
            instance: /api/v1/competitors
            request_id: 5f1c2b7e-9a41-4c1e-8d0e-2b1f3a6c7d80
            error: Choose a paid plan to use this feature.
    TooManyRequests:
      description: This address sent more than 600 requests in one minute.
      headers:
        Retry-After:
          description: Seconds to wait before the next request.
          schema:
            type: integer
          example: 60
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://debriefing.io/developers#errors-rate_limited
            title: Too many requests
            status: 429
            detail: This address sent more than 600 requests in one minute.
            code: rate_limited
            hint: Wait for the number of seconds in the Retry-After header. Then send the request again.
            instance: /api/v1/signals
            request_id: 5f1c2b7e-9a41-4c1e-8d0e-2b1f3a6c7d80
            error: This address sent more than 600 requests in one minute.
  schemas:
    Digest:
      type: object
      required:
      - id
      - type
      - status
      - url
      properties:
        id:
          type: integer
        slug:
          type: string
        type:
          type: string
          description: Debrief type, for example `daily_digest` or `weekly_tldr`.
        status:
          type: string
          example: generated
        title:
          type: string
        headline:
          type: string
        tldr:
          type: string
        what_to_watch:
          type: string
        coverage_period_start:
          type: string
          format: date-time
        coverage_period_end:
          type: string
          format: date-time
        generated_at:
          type: string
          format: date-time
        items:
          type: array
          items:
            type: object
            additionalProperties: true
        signal_ids:
          type: array
          items:
            type: integer
        markdown:
          type: string
        url:
          type: string
          format: uri
          description: Link to the digest page in the app.
    CompetitorSlots:
      type: object
      required:
      - limit
      - used
      - remaining
      properties:
        limit:
          type: integer
        used:
          type: integer
        remaining:
          type: integer
    Problem:
      type: object
      description: 'RFC 9457 problem details, sent as `application/problem+json`. Every 4xx and 5xx

        response of the read API has this shape. Branch on `code`, not on `detail` or `title`.

        The `type` URL points at the row for the code on /developers.

        '
      required:
      - type
      - title
      - status
      - detail
      - code
      - hint
      properties:
        type:
          type: string
          format: uri
          description: Documentation URL for this code, `https://debriefing.io/developers#errors-<code>`.
        title:
          type: string
          description: Short summary of the code. The same for every problem with this code.
        status:
          type: integer
          description: The HTTP status code.
        detail:
          type: string
          description: What went wrong with this request.
        code:
          type: string
          description: Machine-readable error code. Stable.
          enum:
          - invalid_request
          - invalid_api_key
          - paid_plan_required
          - plan_limit_reached
          - forbidden
          - insufficient_scope
          - not_found
          - unprocessable_content
          - rate_limited
          - internal_error
        hint:
          type: string
          description: What the client can do next.
        instance:
          type: string
          description: The request path.
        request_id:
          type: string
          description: The request id. Send it to support when you report an error.
        error:
          type: string
          deprecated: true
          description: The same text as `detail`. Kept for clients that read the old `{ "error" }` body.
        upgrade_url:
          type: string
          format: uri
          description: With `plan_limit_reached`. Where an admin chooses a larger plan.
        competitor_slots:
          $ref: '#/components/schemas/CompetitorSlots'
  parameters:
    Page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
    PerPage:
      name: per_page
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 50
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: dbk_
      description: 'Send `Authorization: Bearer dbk_…`. The plain token is shown once when the key is

        created. Only a SHA-256 digest is stored.

        '
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternative to Bearer. Send the same `dbk_…` token.