broadcastwell-com Account API

openapi: 3.2.0
info:
  title: Broadcastwell Account API
  version: 1.0.0
  summary: Read the answers five AI engines gave to your buyers' questions, with every receipt.
  description: 'Read only. Every rate is a five field object: pct, low, high, interval and base, where low and high are the 95% Wilson interval and base states the count. Every headline figure counts scheduled runs only. Adaptive runs are labelled and never pooled. Errors are problem details with a next step. Version 1 changes only by addition.


    The public demo key bwp_demo_kalvenor_sample reads the fictional Kalvenor sample at /accounts/sample.


    The separate commercial Agent Test is run by ChatGPT Work with Cloud browser, two runs per task at least two hours apart. Its ten task results and 20 session receipts are delivered through the owning account after human review; they are not pooled with the five-engine measurements described by this API.'
  contact:
    name: Broadcastwell
    email: hello@broadcastwell.com
    url: https://broadcastwell.com
  termsOfService: https://broadcastwell.com/terms
servers:
- url: https://app.broadcastwell.com/api/v1
security:
- bearer: []
tags:
- name: Account
paths:
  /checklist:
    get:
      operationId: getChecklist
      summary: Your buyer's checklist
      description: Released Checklist Audit criteria, differentiator coverage with intervals, rival-favoured criteria and Fix List, with capture dates and engines. Account API key required. Receipts stay in the account. The demo key returns fictional Kalvenor SAMPLE DATA. Read only.
      tags:
      - Account
      responses:
        '200':
          description: Released Checklist Audits without receipt texts
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  sample:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
        '304':
          description: Not modified. The If-None-Match value matched the current ETag.
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '429':
          $ref: '#/components/responses/Problem429'
  /kpi:
    get:
      operationId: getKpi
      summary: The three numbers
      description: 'Existing KPI fields retain their meaning. An additive proof field contains the Proof Page. The authenticated account only: released organic evidence with interval, sponsored counts and permissioned AI referrals. Missing sources say not measured. The demo key returns fictional SAMPLE DATA. No write access.'
      tags:
      - Account
      responses:
        '200':
          description: The account KPI
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  sample:
                    type: boolean
                  data:
                    type: object
        '304':
          description: Not modified. The If-None-Match value matched the current ETag.
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '429':
          $ref: '#/components/responses/Problem429'
  /proof:
    get:
      operationId: getPipelineProof
      summary: The Proof Page
      description: Four labelled lines, released reporting periods and de-identified questions for the authenticated account. Read only. The demo key returns fictional Kalvenor SAMPLE DATA. Reporting permission revocation hides the affected source. No modelled revenue.
      tags:
      - Account
      responses:
        '200':
          description: The account Proof Page
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  sample:
                    type: boolean
                  data:
                    type: object
                    required:
                    - measured_presence
                    - ai_referred_demand
                    - ai_sourced_pipeline
                    - controlled_lift
                    - periods
                    - questions
                    properties:
                      measured_presence:
                        type: object
                      ai_referred_demand:
                        type: object
                      ai_sourced_pipeline:
                        type: object
                      controlled_lift:
                        type: object
                      periods:
                        type: array
                        items:
                          type: object
                      questions:
                        type: array
                        items:
                          type: object
                      sample:
                        type: boolean
                      label:
                        type: string
        '304':
          description: Not modified. The If-None-Match value matched the current ETag.
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '429':
          $ref: '#/components/responses/Problem429'
  /me:
    get:
      operationId: getMe
      summary: The key you are using
      description: Who the key belongs to and which accounts it reads.
      tags:
      - Account
      responses:
        '200':
          description: The key
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  sample:
                    type: boolean
                  data:
                    type: object
        '304':
          description: Not modified. The If-None-Match value matched the current ETag.
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '429':
          $ref: '#/components/responses/Problem429'
  /accounts/me/questions:
    post:
      operationId: askQuestion
      summary: Ask a live question
      description: 'One buyer question of your own, asked on ChatGPT, Claude, Perplexity, Google AI Overviews and Google AI Mode, three runs each, with a receipt on every answer. Send the question alone to preview it: the answer shows exactly what will be asked and spends nothing. Send it again with that preview_hash to ask: it uses one credit and answers 201. A retried ask with the same key and preview_hash is the same question. Needs a key created with live questions allowed; the question leaves out your own company and every brand. Answers within 1 hour of asking, usually much sooner.'
      tags:
      - Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - question
              additionalProperties: false
              properties:
                question:
                  type: string
                  minLength: 12
                  maxLength: 300
                preview_hash:
                  type: string
      responses:
        '200':
          description: 'The preview: the question, the five engines, three runs, 15 planned answers, the window, the price and your credits. Nothing is spent.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  sample:
                    type: boolean
                  data:
                    type: object
        '201':
          description: 'Asked: the question id, its order code and state, and your balance.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  sample:
                    type: boolean
                  data:
                    type: object
        '402':
          description: 'No credit: buy credits in your account.'
        '403':
          description: This key may not ask live questions.
        '409':
          description: The preview_hash does not match the question.
        '422':
          description: The question breaks a rule; the answer names the rule.
  /accounts/{account}:
    get:
      operationId: getAccount
      summary: One account
      tags:
      - Account
      parameters:
      - name: account
        in: path
        required: true
        description: me, your account id, or sample for the fictional Kalvenor sample. Any other id answers 404.
        schema:
          type: string
          maxLength: 200
          examples:
          - sample
          - me
      responses:
        '200':
          description: The account
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  sample:
                    type: boolean
                  data:
                    type: object
        '304':
          description: Not modified. The If-None-Match value matched the current ETag.
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '429':
          $ref: '#/components/responses/Problem429'
webhooks:
  run.completed:
    post:
      operationId: webhook_run_completed
      summary: run.completed event
      description: 'Signed with HMAC SHA-256 over the timestamp, a full stop and the raw body. Header Broadcastwell-Signature: t=timestamp,v1=hex. Reject a timestamp more than 300 seconds from your clock. Delivery is at least once: every event carries a durable id, in the body and in the Broadcastwell-Event-Id header, the same on every attempt, so deduplicate on it.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: Any 2xx acknowledges the event. Anything else is retried with backoff.
      tags:
      - Account
  alert.fired:
    post:
      operationId: webhook_alert_fired
      summary: alert.fired event
      description: 'Signed with HMAC SHA-256 over the timestamp, a full stop and the raw body. Header Broadcastwell-Signature: t=timestamp,v1=hex. Reject a timestamp more than 300 seconds from your clock. Delivery is at least once: every event carries a durable id, in the body and in the Broadcastwell-Event-Id header, the same on every attempt, so deduplicate on it.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: Any 2xx acknowledges the event. Anything else is retried with backoff.
      tags:
      - Account
  fix.updated:
    post:
      operationId: webhook_fix_updated
      summary: fix.updated event
      description: 'Signed with HMAC SHA-256 over the timestamp, a full stop and the raw body. Header Broadcastwell-Signature: t=timestamp,v1=hex. Reject a timestamp more than 300 seconds from your clock. Delivery is at least once: every event carries a durable id, in the body and in the Broadcastwell-Event-Id header, the same on every attempt, so deduplicate on it.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: Any 2xx acknowledges the event. Anything else is retried with backoff.
      tags:
      - Account
  proof.updated:
    post:
      operationId: webhook_proof_updated
      summary: proof.updated event
      description: 'Signed with HMAC SHA-256 over the timestamp, a full stop and the raw body. Header Broadcastwell-Signature: t=timestamp,v1=hex. Reject a timestamp more than 300 seconds from your clock. Delivery is at least once: every event carries a durable id, in the body and in the Broadcastwell-Event-Id header, the same on every attempt, so deduplicate on it.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: Any 2xx acknowledges the event. Anything else is retried with backoff.
      tags:
      - Account
components:
  headers:
    RateLimitReset:
      description: Seconds until the window resets.
      schema:
        type: integer
    RateLimitLimit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
    ETag:
      description: Strong entity tag. Send it back as If-None-Match.
      schema:
        type: string
  responses:
    Problem429:
      description: Rate limit reached. Retry-After says when to retry.
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem401:
      description: The key is missing, invalid or revoked.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem404:
      description: Nothing with that id is available to this key.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem400:
      description: A parameter is invalid.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  schemas:
    Problem:
      type: object
      required:
      - type
      - title
      - status
      - code
      - detail
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        code:
          type: string
        detail:
          type: string
    Event:
      type: object
      required:
      - id
      - type
      - api_version
      - created_at
      - account_id
      - data
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - run.completed
          - alert.fired
          - fix.updated
          - proof.updated
        api_version:
          type: string
        created_at:
          type: string
        account_id:
          type: string
        data:
          type: object
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: An account API key, or the public demo key.
x-changelog:
- date: '2026-10-15'
  version: 1.1.0
  change: 'Added POST /accounts/me/questions: a live question, by a key whose account allowed live questions when creating it. Without preview_hash it previews and spends nothing; with it, it asks and uses one credit.'
- date: '2026-10-14'
  version: 1.0.0
  change: 'Added the public tier, no key needed: GET /index/categories, GET /index/categories/{category} and GET /public-fix, GET /public-fix/{slug}, the same reads as the public connector at /mcp/public. 60 requests a minute and 1,000 a day per address.'
- date: '2026-10-07'
  version: 1.0.0
  change: 'Added read-only GET /kpi: organic evidence, sponsored presence and permissioned AI referrals with sources and dates. The demo key returns fictional SAMPLE DATA.'
- date: '2026-10-06'
  version: 1.0.0
  change: 'Agent Test: ten tasks run by ChatGPT Work with Cloud browser, two runs per task at least two hours apart. Account findings require all 20 receipts and human review. The separate Agent Gap study uses one primary run per task with a repeat sample.'
- date: '2026-09-21'
  version: 1.0.0
  change: 'Version 1 published: runs, run summary, questions, receipts, displacement, sources, fixes, history, alerts, proof and method. Account API keys, the public demo key and webhooks.'
- date: '2026-09-28'
  version: 1.0.0
  change: Added GET /index/lookup, the public Absence Index lookup by website or name. No key needed.
x-rate-limits:
  key_per_minute: 60
  key_per_day: 5000
  demo_per_address_minute: 30
  note: Defaults. The live values are returned on every response in the RateLimit headers.