Debriefing Battlecards API

openapi: 3.2.0
info:
  title: Debriefing Read Battlecards 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: Battlecards
  description: Generated battlecards for this workspace.
paths:
  /api/v1/battlecards:
    get:
      tags:
      - Battlecards
      operationId: listBattlecards
      summary: List generated battlecards
      description: Returns generated battlecards for this workspace, ordered by competitor id. Not paginated.
      responses:
        '200':
          description: The battlecards for this workspace.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Battlecard'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/battlecards/{id}:
    get:
      tags:
      - Battlecards
      operationId: getBattlecard
      summary: Get one battlecard
      description: Looks up a generated battlecard by battlecard id first, then by competitor id.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Battlecard id or competitor id.
      responses:
        '200':
          description: One battlecard.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Battlecard'
        '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:
    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'
    Battlecard:
      type: object
      required:
      - id
      - competitor_id
      - status
      - url
      properties:
        id:
          type: integer
        competitor_id:
          type: integer
        competitor_name:
          type: string
        status:
          type: string
          example: generated
        generated_at:
          type: string
          format: date-time
        sections:
          type: object
          additionalProperties: true
        evidence:
          type: object
          additionalProperties: true
        url:
          type: string
          format: uri
          description: Link to the battlecard page in the app.
  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.