Buzz Dealer AI Find Publications API

openapi: 3.2.0
info:
  title: Buzzdealer Ai Find Publications API
  version: '1'
  contact:
    name: Buzz Dealer AI support
    email: support@buzzdealer.ai
    url: https://buzzdealer.ai/contact
  x-deprecation-policy: https://buzzdealer.ai/docs/api/deprecation
  description: 'Operations tagged find_publications across 2 of this provider''s published API definitions: openapi.json, buzzdealer-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.buzzdealer.ai
security:
- bearerAuth: []
tags:
- name: find_publications
paths:
  /v1/publications:
    get:
      operationId: get_publications
      summary: Search published catalog items
      description: Same behavior as the MCP tool find_publications.
      tags:
      - find_publications
      security:
      - bearerAuth: []
      - oauth2:
        - read
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    total:
                      type: integer
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/Publication'
                - $ref: '#/components/schemas/PageInfo'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Not signed in (no or a bad API key or token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Not enough credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not allowed (scope, role or budget frame)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Refused by a check
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Too many requests: wait Retry-After seconds'
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Unavailable for a moment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: product_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - site
          - pr_package
          - bundle
          - program
          - service
        description: site (an article on one site), pr_package (wire distribution), bundle, program (monthly), service
      - name: category
        in: query
        required: false
        schema:
          type: string
          maxLength: 100
        description: Exact category, for example Finance
      - name: region
        in: query
        required: false
        schema:
          type: string
          maxLength: 100
        description: For example UK, US, LATAM
      - name: language
        in: query
        required: false
        schema:
          type: string
          maxLength: 40
        description: Language as an ISO 639-1 code (en, es, pt) or its English name (English); any case
      - name: max_price_cents
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        description: Highest price per item, in US cents
      - name: dofollow
        in: query
        required: false
        schema:
          type: boolean
        description: 'Sites only: true for dofollow links'
      - name: min_dr
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 100
        description: 'Sites only: lowest DR (Ahrefs), 0 to 100. Items without a DR never match'
      - name: query
        in: query
        required: false
        schema:
          type: string
          maxLength: 100
        description: Words to look for in name, domain, category or description
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 50
        description: At most this many results (default 10, at most 50)
      - name: goal
        in: query
        required: false
        schema:
          type: string
          enum:
          - reputation
          - seo
          - ai_visibility
          - mentions
        description: 'Optional: rank the results for one goal (reputation, seo, ai_visibility or mentions) instead of by AI score'
      - name: goal_weights
        in: query
        required: false
        schema:
          type: string
          pattern: ^[a-z_]+:\d+(\.\d+)?(,[a-z_]+:\d+(\.\d+)?)*$
        description: 'A goal mix instead of goal, as goal:weight pairs, for example ai_visibility:60,seo:40. Goals: reputation, seo, ai_visibility, mentions; each 0 to 100; scaled to 100 when they do not add up; all zero is refused'
      - name: offset
        in: query
        required: false
        description: Skip this many results (offset paging)
        schema:
          type: integer
          minimum: 0
      - name: cursor
        in: query
        required: false
        description: The next_cursor of the previous page (cursor paging); wins over offset
        schema:
          type: string
    servers:
    - url: https://api.buzzdealer.ai
components:
  headers:
    Retry-After:
      description: Seconds to wait before asking again
      schema:
        type: integer
    RateLimit-Policy:
      description: The quota policy, for example "default";q=60;w=60 (60 requests per 60 seconds)
      schema:
        type: string
    RateLimit:
      description: 'IETF RateLimit header fields (draft-ietf-httpapi-ratelimit-headers): the quota left and when it resets, for example "default";r=58;t=42'
      schema:
        type: string
  schemas:
    Publication:
      type: object
      additionalProperties: true
      required:
      - id
      - product_type
      - name
      - price_cents
      - currency
      properties:
        id:
          type: string
          format: uuid
        product_type:
          type: string
          enum:
          - site
          - pr_package
          - bundle
          - program
          - service
        name:
          type: string
        domain:
          type:
          - string
          - 'null'
        category:
          type:
          - string
          - 'null'
        region:
          type:
          - string
          - 'null'
        languages:
          type: array
          items:
            type: string
        price_cents:
          type:
          - integer
          - 'null'
          description: Price in US cents
        price:
          type:
          - string
          - 'null'
          description: Price in US dollars, for display
        currency:
          const: USD
        ai_score:
          type:
          - integer
          - 'null'
          description: AI score (beta), 0 to 100
        tier:
          type:
          - string
          - 'null'
        dr:
          type: integer
          minimum: 0
          maximum: 100
          description: DR (Ahrefs) of the site's domain. Single sites only; absent when we have no DR
        dr_label:
          const: DR (Ahrefs)
        dofollow:
          type:
          - boolean
          - 'null'
        min_word_count:
          type:
          - integer
          - 'null'
          description: 'Sites: the fewest words the site takes (fit check); null when none is recorded'
        max_word_count:
          type:
          - integer
          - 'null'
          description: 'Sites: the most words the site takes (fit check). Release on livepublicator.com: 800'
        max_links:
          type:
          - integer
          - 'null'
          description: 'Sites: the most links the site takes (fit check). Release on livepublicator.com: 3'
        service_notes:
          type:
          - string
          - 'null'
          description: 'Release on livepublicator.com only: what happens to the release. The text is kept and lightly edited for style; a short summary, key facts and an FAQ are added; a person may review it first (usually within 24 hours); English only, 300 to 20,000 characters with the headline, at most 800 words and 3 https links; cover image (image_url) an https JPEG, PNG or WebP of at most 5 MB; no AI-generated images. No writing add-on. Contact details come from the order, else the brand''s press contact'
        add_ons:
          type: object
          properties:
            writing:
              type:
              - integer
              - 'null'
              description: Writing add-on price in US cents, or null when not offered
            logo:
              type:
              - integer
              - 'null'
              description: Logo add-on price in US cents for this PR package, or null when it has no logo option
    PageInfo:
      type: object
      description: 'Paging: send next_cursor as cursor (or next_offset as offset) for the next page; both are null on the last page.'
      properties:
        next_cursor:
          type:
          - string
          - 'null'
        next_offset:
          type:
          - integer
          - 'null'
    Error:
      type: object
      description: Every error has these three fields. next_step tells the caller exactly what to do.
      properties:
        error:
          type: string
          description: Machine-readable code, for example insufficient_credits
        message:
          type: string
          description: What happened, in plain words
        next_step:
          type: string
          description: What to do next
      required:
      - error
      - message
      - next_step
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key from the dashboard (Connections)
    oauth2:
      type: oauth2
      description: OAuth 2.1, authorization code with PKCE (S256). Ask for resource=https://api.buzzdealer.ai/v1 for this API (https://mcp.buzzdealer.ai/mcp is the MCP server). With no scope, all three are asked for; the person can untick write and spend on the consent screen.
      flows:
        authorizationCode:
          authorizationUrl: https://app.buzzdealer.ai/oauth/authorize
          tokenUrl: https://app.buzzdealer.ai/oauth/token
          refreshUrl: https://app.buzzdealer.ai/oauth/token
          scopes:
            read: 'Read: See your balance, budget frame, the catalog, quotes, orders, reports and Reputation Agent results. Changes nothing.'
            write: 'Make changes that spend nothing: Save quotes, answer the Reputation Agent''s questions, set preferences, start a scan, and start, mark and rate fixes. Spends no credits.'
            spend: 'Spend credits: Place orders and order audits, reports and paid rescans within your budget frame, using credits you already added. It can never pay or add credits.'
externalDocs:
  description: Connect your agent (every AI client, API keys)
  url: https://buzzdealer.ai/connect?client=api
x-refined-from:
- openapi.json
- buzzdealer-ai-openapi.json
x-connect:
  page: https://buzzdealer.ai/connect
  mcp_server: https://mcp.buzzdealer.ai/mcp
  docs: https://buzzdealer.ai/docs
  llms_txt: https://buzzdealer.ai/llms.txt
x-mcp-tools:
- name: find_publications
  title: Find press release distribution and sponsored article placements
  read_only: true
  spends_credits: false
- name: get_publication
  title: Get a publication
  read_only: true
  spends_credits: false
- name: plan_campaign
  title: Plan a press release or digital PR campaign
  read_only: true
  spends_credits: false
- name: get_ai_visibility_score
  title: Get AI Visibility Score
  read_only: true
  spends_credits: false
- name: check_company_presence
  title: Quick reputation check of a company
  read_only: true
  spends_credits: false
- name: check_originality_and_fit
  title: Check originality and fit
  read_only: true
  spends_credits: false
- name: quote_order
  title: Quote an order
  read_only: false
  spends_credits: false
- name: place_order
  title: Place an order
  read_only: false
  spends_credits: true
- name: get_order_status
  title: Get order status
  read_only: true
  spends_credits: false
- name: respond_to_replacement
  title: Respond to a replacement offer
  read_only: false
  spends_credits: true
- name: get_report
  title: Get a report
  read_only: true
  spends_credits: false
- name: order_audit
  title: Order an audit
  read_only: false
  spends_credits: true
- name: get_account_status
  title: Get account status
  read_only: true
  spends_credits: false
- name: get_linked_account
  title: Which account is linked
  read_only: true
  spends_credits: false
- name: start_radar
  title: Start the scan
  read_only: false
  spends_credits: false
- name: get_radar_status
  title: Read the scan as it lands
  read_only: true
  spends_credits: false
- name: get_questions
  title: Get the next question
  read_only: true
  spends_credits: false
- name: answer_question
  title: Answer a question
  read_only: false
  spends_credits: false
- name: set_preferences
  title: Set the preferences
  read_only: false
  spends_credits: false
- name: get_gaps
  title: Get the gaps
  read_only: true
  spends_credits: false
- name: start_fix
  title: Start a fix
  read_only: false
  spends_credits: false
- name: mark_fix_done
  title: Mark a fix done and verify it
  read_only: false
  spends_credits: false
- name: get_progress
  title: Get the progress
  read_only: true
  spends_credits: false
- name: what_changed
  title: What changed
  read_only: true
  spends_credits: false
- name: get_playbook
  title: Get the Reputation Agent playbook
  read_only: true
  spends_credits: false
- name: check_request
  title: Check a request about reviews, testimonials, a ban or legal trouble
  read_only: true
  spends_credits: false
- name: rate_fix
  title: Record whether a fix worked
  read_only: false
  spends_credits: false
- name: get_reputation_profile
  title: Get the reputation profile
  read_only: true
  spends_credits: false
- name: update_reputation_profile
  title: Update the reputation profile
  read_only: false
  spends_credits: false