Breakreach Comment Dm Rules API

openapi: 3.2.0
info:
  title: Breakreach Comment Dm Rules API
  version: 1.1.0
  description: 'Publish and schedule social media posts across Instagram, TikTok, X (Twitter), Reddit, LinkedIn, YouTube, Facebook, Threads, Bluesky, Pinterest, Telegram, Discord, Slack, Mastodon, WordPress, Ghost, Dev.to, Hashnode, Tumblr and Google Business Profile with one request shape.


    Authenticate with an API key (create one in the Breakreach dashboard under Settings → API & MCP) sent as a Bearer token. Errors answer with an HTTP status and a JSON body { "error": "" }.


    Every POST accepts an Idempotency-Key header: any unique string up to 255 characters, a UUID for instance. Retrying with the same key and the same body within 24 hours returns the first response, marked Idempotent-Replayed: true, instead of creating a second post. The same key with a different body answers 422, and 409 while the first request is still running. Errors are not kept, so a fixed request can reuse its key. Keys belong to the API key that sent them.


    AI agents can use the same capabilities through the hosted MCP server at https://api.breakreach.com/mcp (OAuth 2.1).'
servers:
- url: https://api.breakreach.com
security:
- bearerAuth: []
tags:
- name: Comment Dm Rules
paths:
  /v1/comment-dm-rules:
    get:
      summary: List Comment to DM rules
      description: 'Comment to DM automations: when someone comments a keyword on a post of an Instagram account or a Facebook Page (or any post of it), Breakreach sends them a DM through a private reply (Instagram Direct, or Messenger from the Page), and optionally a public reply under the comment. Both networks allow one private reply per comment within 7 days of it, and Breakreach sends each person one DM per rule. Available on the Pro, Agency and Developer plans.'
      operationId: listCommentDmRules
      parameters:
      - name: accountId
        in: query
        schema:
          type: string
      - name: mediaId
        in: query
        schema:
          type: string
      - name: workspace
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - rules
                properties:
                  rules:
                    type: array
                    items:
                      $ref: '#/components/schemas/CommentDmRule'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Workspace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Comment Dm Rules
    post:
      summary: Create a Comment to DM rule
      description: Starts watching the comments of the account (Breakreach subscribes it to Instagram's comment webhooks, or the Page's feed webhooks). Requires a Pro, Agency or Developer plan on the workspace.
      operationId: createCommentDmRule
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentDmRuleInput'
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                type: object
                required:
                - rule
                properties:
                  rule:
                    $ref: '#/components/schemas/CommentDmRule'
        '400':
          description: Invalid field, not an Instagram account or a Facebook Page, or the post isn't on this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Account, post or workspace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          $ref: '#/components/responses/IdempotencyRunning'
        '422':
          $ref: '#/components/responses/IdempotencyMismatch'
        '502':
          description: Instagram refused to read the account or to send its comments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Comment Dm Rules
  /v1/comment-dm-rules/media:
    get:
      summary: Latest posts of an Instagram account or a Facebook Page
      description: The account's latest posts with their ids, to pick the mediaId of a rule.
      operationId: listCommentDmMedia
      parameters:
      - name: accountId
        in: query
        required: true
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 24
      - name: workspace
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
        '400':
          description: Not an Instagram account or a Facebook Page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Workspace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: The network did not return the posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Comment Dm Rules
  /v1/comment-dm-rules/{id}:
    patch:
      summary: Update a Comment to DM rule
      description: Only the fields given change. active false pauses the rule; mediaId null makes it watch every post.
      operationId: updateCommentDmRule
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentDmRuleInput'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                required:
                - rule
                properties:
                  rule:
                    $ref: '#/components/schemas/CommentDmRule'
        '400':
          description: Invalid field
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Rule or workspace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Comment Dm Rules
    delete:
      summary: Delete a Comment to DM rule
      description: Deletes the rule with its activity.
      operationId: deleteCommentDmRule
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: workspace
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Rule or workspace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Comment Dm Rules
  /v1/comment-dm-rules/{id}/events:
    get:
      summary: Activity of a Comment to DM rule
      description: 'Comments that matched the rule, newest first, kept 90 days: sent, failed (with the reason) or skipped. The same outcomes are pushed to webhooks subscribed to comment_dm.sent and comment_dm.failed.'
      operationId: listCommentDmEvents
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      - name: workspace
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - events
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/CommentDmEvent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Rule or workspace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Comment Dm Rules
components:
  responses:
    Unauthorized:
      description: Missing, invalid or expired API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    IdempotencyRunning:
      description: 'A request with this Idempotency-Key is still running: retry after Retry-After seconds to get its response'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: No active Breakreach subscription or trial
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    IdempotencyMismatch:
      description: This Idempotency-Key was already used with a different request in the last 24 hours
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Not a member of the requested workspace
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CommentDmRule:
      type: object
      required:
      - id
      - accountId
      - platform
      - mediaId
      - media
      - keywords
      - match
      - dmText
      - publicReplies
      - active
      - stats
      - lastTriggeredAt
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
        accountId:
          type: string
        platform:
          type: string
          enum:
          - instagram
          - facebook
        account:
          type: object
          properties:
            displayName:
              type: string
            avatarUrl:
              type:
              - string
              - 'null'
        mediaId:
          type:
          - string
          - 'null'
          description: The Instagram or Facebook post the rule watches; null = every post of the account
        media:
          type:
          - object
          - 'null'
          properties:
            caption:
              type: string
            thumbnailUrl:
              type:
              - string
              - 'null'
            permalink:
              type:
              - string
              - 'null'
            timestamp:
              type:
              - string
              - 'null'
              format: date-time
        keywords:
          type: array
          items:
            type: string
          description: Empty = every comment triggers the rule
        match:
          type: string
          enum:
          - contains
          - exact
        dmText:
          type: string
        publicReplies:
          type: array
          items:
            type: string
        active:
          type: boolean
        stats:
          type: object
          properties:
            triggered:
              type: integer
            sent:
              type: integer
            failed:
              type: integer
        lastTriggeredAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable reason
    CommentDmEvent:
      type: object
      required:
      - id
      - ruleId
      - status
      - reason
      - error
      - commentId
      - commentText
      - commenterUsername
      - commenterName
      - mediaId
      - dmMessageId
      - publicReply
      - publicReplyError
      - createdAt
      - sentAt
      properties:
        id:
          type: string
        ruleId:
          type: string
        status:
          type: string
          enum:
          - pending
          - sent
          - failed
          - skipped
        reason:
          type:
          - string
          - 'null'
          description: 'Why it was skipped: duplicate (the person already got this rule''s DM), too_old (Instagram allows private replies within 7 days), plan (the workspace owner is not on Pro or Agency), paused, deleted'
        error:
          type:
          - string
          - 'null'
        commentId:
          type: string
        commentText:
          type: string
        commenterUsername:
          type:
          - string
          - 'null'
          description: Instagram handle
        commenterName:
          type:
          - string
          - 'null'
          description: Facebook name
        mediaId:
          type:
          - string
          - 'null'
        dmMessageId:
          type:
          - string
          - 'null'
        publicReply:
          type:
          - string
          - 'null'
          description: The public reply posted under the comment
        publicReplyError:
          type:
          - string
          - 'null'
        createdAt:
          type: string
          format: date-time
        sentAt:
          type:
          - string
          - 'null'
          format: date-time
    CommentDmRuleInput:
      type: object
      properties:
        accountId:
          type: string
          description: Instagram account or Facebook Page id from /v1/accounts (create only, a rule can't change account)
        mediaId:
          type:
          - string
          - 'null'
          description: Instagram or Facebook post id to watch (from /v1/comment-dm-rules/media or the postId of /v1/comments). Omit or null for every post
        postId:
          type: string
          description: 'Instead of mediaId: a Breakreach post id published on this account'
        keywords:
          type: array
          items:
            type: string
            maxLength: 60
          maxItems: 20
          description: Words or phrases that trigger the DM, case and accents ignored. Empty = every comment
        match:
          type: string
          enum:
          - contains
          - exact
          default: contains
          description: contains = the keyword appears as a whole word or phrase; exact = the comment is just the keyword (punctuation and emoji around it ignored)
        dmText:
          type: string
          maxLength: 1000
          description: The DM sent to the commenter, links allowed. {username} becomes their @handle on Instagram, their first name on Facebook. Required on create
        publicReplies:
          type: array
          items:
            type: string
            maxLength: 300
          maxItems: 5
          description: Optional public replies under the comment once the DM is sent, one picked at random. {username} becomes their @handle on Instagram, their first name on Facebook
        active:
          type: boolean
          default: true
        workspace:
          type: string
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 255
      description: 'A unique string for this request, e.g. a UUID. A retry with the same key and body within 24 hours returns the first response (with the header Idempotent-Replayed: true) instead of running again. Printable ASCII, no spaces.'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key from the Breakreach dashboard (br_...) or an OAuth access token (bro_...)