broadcastwell-com Index API

openapi: 3.2.0
info:
  title: Broadcastwell Index 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: Index
paths:
  /exclusive/check:
    get:
      operationId: checkCategoryExclusive
      x-example-query: category=dealership%20management%20systems
      summary: Category Exclusive
      description: Public read of a category lock for the Fix Sprint and the program. No client identity is returned. The Category Audit and Index services stay open to everyone.
      tags:
      - Index
      security: []
      parameters:
      - name: category
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 160
        example: dealership management systems
      responses:
        '200':
          description: Open or locked, with the category and month only
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - category_label
                - locked_until_month
                properties:
                  status:
                    enum:
                    - open
                    - locked
                  category_label:
                    type: string
                  locked_until_month:
                    type:
                    - string
                    - 'null'
                  suggested_index_category:
                    type: object
                    properties:
                      slug:
                        type: string
                      label:
                        type: string
        '400':
          description: A category of 2 to 160 characters is required
        '429':
          description: Public demo rate limit reached
        '503':
          description: The category check could not be read
  /index/lookup:
    get:
      operationId: lookupIndex
      summary: Find a company in the Absence Index
      description: 'Whether a company is in the public Absence Index release 2026-09, and for each category it is in: how often the five engines named it and cited it, the questions it was absent from, and who was named instead. Send its website or its name. No key needed: point ChatGPT or Claude at this address to ask the same question. Read only, 60 lookups a minute per address, cached for a day.'
      tags:
      - Index
      security: []
      x-example-query: domain=procore.com
      parameters:
      - name: domain
        in: query
        description: A website or address, for example procore.com. Send domain or name.
        schema:
          type: string
          maxLength: 253
          examples:
          - procore.com
      - name: name
        in: query
        description: A company name, for example Procore. A plain-word name matches only with a qualifier, such as Close CRM.
        schema:
          type: string
          maxLength: 120
          examples:
          - Procore
      responses:
        '200':
          description: Found, with one record per category, or not in this release, with the free check address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexLookup'
        '400':
          description: Neither domain nor name was sent, or the value is not usable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupError'
        '429':
          description: Too many lookups from this address. Retry-After says when to retry.
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupError'
components:
  schemas:
    LookupError:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
        message:
          type: string
    IndexLookup:
      type: object
      required:
      - found
      - query
      - release
      - framing
      - offers
      properties:
        found:
          type: boolean
        query:
          type: object
        release:
          type: object
          required:
          - release_id
          - release_date
          - doi
          - doi_url
          - license
          properties:
            release_id:
              type: string
            release_date:
              type: string
            doi:
              type: string
            doi_url:
              type: string
            license:
              type: string
            method_version:
              type: string
            source:
              type: string
        framing:
          type: string
        records:
          type: array
          items:
            $ref: '#/components/schemas/IndexRecord'
        message:
          type: string
        free_check_url:
          type: string
        offers:
          type: object
    IndexRecord:
      type: object
      required:
      - name
      - slug
      - canonical_domain
      - category
      - named
      - cited
      - questions_appeared
      - engines
      - named_instead
      - never_named_in_category
      - absent_questions
      - index_url
      - matched_by
      properties:
        name:
          type: string
        slug:
          type: string
        canonical_domain:
          type: string
        category:
          type: object
          required:
          - id
          - name
          - url
          properties:
            id:
              type: string
            name:
              type: string
            captured_on:
              type:
              - string
              - 'null'
            url:
              type: string
        named:
          $ref: '#/components/schemas/IndexCount'
        cited:
          $ref: '#/components/schemas/IndexCount'
        questions_appeared:
          type: object
          required:
          - count
          - of
          properties:
            count:
              type: integer
            of:
              type: integer
        engines:
          type: array
          items:
            type: object
            required:
            - engine
            - count
            - base
            properties:
              engine:
                type: string
              count:
                type:
                - integer
                - 'null'
              base:
                type:
                - integer
                - 'null'
        named_instead:
          type: array
          items:
            type: object
            required:
            - name
            - named
            - base
            properties:
              name:
                type: string
              named:
                type: integer
              base:
                type: integer
        never_named_in_category:
          type: integer
        absent_questions:
          type: array
          items:
            type: object
            required:
            - id
            - text
            properties:
              id:
                type: string
              text:
                type:
                - string
                - 'null'
        index_url:
          type: string
        matched_by:
          type: string
          enum:
          - domain
          - name
    IndexCount:
      type: object
      required:
      - count
      - base
      properties:
        count:
          type: integer
        base:
          type: integer
        rate:
          type: number
        lower:
          type: number
        upper:
          type: number
  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.