broadcastwell-com Briefs API

openapi: 3.2.0
info:
  title: Broadcastwell Briefs 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: Briefs
paths:
  /briefs:
    get:
      operationId: listBriefs
      summary: Pre-Call Briefs
      description: Pre-Call Briefs are available to the account that owns them at GET /api/v1/briefs and GET /api/v1/briefs/ with an account API key, receipts included; the demo key returns the sample brief once it is published. Read only. Each brief holds what five named AI products answered about one deal on one date, captured by a person; counts are out of 25 answers, never rates.
      tags:
      - Briefs
      responses:
        '200':
          description: Delivered briefs, newest first
          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'
  /briefs/{brief}:
    get:
      operationId: getBrief
      summary: One Pre-Call Brief with its receipts
      description: The deal inputs, the five questions as sent, the verdict grid, the counts, the wrong facts with their pages, the talk track and all 25 receipts with their verbatim answers, share links, cited addresses and screenshot addresses.
      tags:
      - Briefs
      parameters:
      - name: brief
        in: path
        required: true
        schema:
          type: string
          pattern: ^pcb_[a-f0-9]{32}$
      responses:
        '200':
          description: The brief
          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'
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
  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.