Buzz Dealer AI Start Radar API

openapi: 3.2.0
info:
  title: Buzzdealer Ai Start Radar 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 start_radar 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: start_radar
paths:
  /v1/reputation/radar:
    post:
      operationId: post_reputation_radar
      summary: Start the scan of you, your company, or both
      description: Same behavior as the MCP tool start_radar.
      tags:
      - start_radar
      security:
      - bearerAuth: []
      - oauth2:
        - write
      responses:
        '200':
          description: Nothing to wait for (for example a question to ask the person first)
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '202':
          description: 'Accepted: the job runs in the background. Follow Location (also status_url in the body), /v1/reputation/radar?run_id={run_id}, after Retry-After seconds (30), until it is done.'
          headers:
            Location:
              $ref: '#/components/headers/Location'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  additionalProperties: true
                - $ref: '#/components/schemas/JobAccepted'
        '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'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                for:
                  description: 'Who the Agent is for: person (me), brand (my company) or founder (both). Asked once; leave out after that'
                  type: string
                  enum:
                  - person
                  - brand
                  - founder
                name:
                  description: 'Me: the account holder''s full name. The Agent scans only the account holder and the account''s own company'
                  type: string
                  minLength: 2
                  maxLength: 120
                role:
                  description: 'Me: role or profession'
                  type: string
                  maxLength: 80
                organization:
                  description: 'Me: company or organization'
                  type: string
                  maxLength: 120
                place:
                  description: 'Me: city or country'
                  type: string
                  maxLength: 80
                link:
                  description: 'Me: one link that is mine (my site or a profile)'
                  type: string
                  maxLength: 500
                company:
                  description: 'My company: name and domain, plus category, best known for and up to 3 competitors'
                  type: object
                  properties:
                    name:
                      type: string
                      minLength: 2
                      maxLength: 120
                      description: The company's name
                    domain:
                      type: string
                      minLength: 3
                      maxLength: 200
                      description: The company's website domain, for example example.com
                    category:
                      description: The category in a few words, for example "logistics software"
                      type: string
                      maxLength: 80
                    best_known_for:
                      description: What it is best known for, for example "boutique hotels in Lisbon"
                      type: string
                      maxLength: 120
                    competitors:
                      description: Up to 3 competitors, name and domain
                      maxItems: 3
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                            minLength: 2
                            maxLength: 120
                          domain:
                            type: string
                            minLength: 3
                            maxLength: 200
                        required:
                        - name
                        - domain
                  required:
                  - name
                  - domain
                paid:
                  description: 'The included rescan of this period is used and the person said yes, in this conversation, to a fresh scan now at the price start_radar showed: buys the paid rescan (with too little balance it waits until a person adds credits in their dashboard). Never without the person''s yes, and never set on your own'
                  type: boolean
                idempotency_key:
                  description: 'With paid: a unique key, reused only to retry the same purchase'
                  type: string
                  minLength: 8
                  maxLength: 120
    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
    Location:
      description: Where to follow the job
      schema:
        type: string
        format: uri
    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:
    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
    JobAccepted:
      type: object
      properties:
        status_url:
          type: string
          format: uri
          description: Where to follow the job (the same as Location)
        retry_after_seconds:
          type: integer
          description: How long to wait before asking (the same as Retry-After)
      required:
      - status_url
      - retry_after_seconds
  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