Boardwalk Analytics API

openapi: 3.2.0
info:
  title: Boardwalkai Com Analytics API
  version: '2026-09-16'
  contact:
    name: Boardwalk Support
    email: support@boardwalkai.com
    url: https://boardwalkai.com
  description: 'Operations tagged Analytics across 2 of this provider''s published API definitions: boardwalkai-com-openapi.json, boardwalkai-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.boardwalkai.com/api/v1
  description: Production
- url: http://localhost:8000/api/v1
  description: Local development
security:
- bearerAuth: []
tags:
- name: Analytics
  description: Free counts, distributions and rankings. Returns aggregates and never record identity, so an analytical question costs nothing.
paths:
  /analytics/datasets:
    get:
      tags:
      - Analytics
      summary: Describe the analytics surface (free)
      description: '**Free.** What you can group by, what you can measure, what each metric''s denominator is, and, deliberately, **the questions this data cannot answer**, each with the measurement that rules it out.


        Read `notAnswerable` before designing an integration. It is not a disclaimer: denial rates, approval-rate rankings, time-to-decision and valuation are not thin here, they are absent, and building against them would produce confident wrong answers.


        Returns no project data of any kind.'
      responses:
        '200':
          description: 'The analytics catalog: datasets, groupable fields, metrics with their denominators, limits, excluded fields with reasons, unanswerable questions, and worked example requests.'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
      operationId: getAnalyticsDatasets
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
  /analytics/aggregate:
    post:
      tags:
      - Analytics
      summary: Group and measure matching projects (free, no record identity)
      description: '**Free: zero credits, and no balance row is created.** Answers "how many, of what kind, where, and when" without delivering a single billable record.


        `filters` takes **exactly** the vocabulary of `GET /projects/search`, so an aggregate row can be taken straight to `/projects/count` and then to `/projects/search` with the same filters. The numbers agree with those endpoints by construction: the same merge collapse and the same record gate run before anything is grouped.


        **Every metric carries a `coverage` fraction**: the share of the group that actually had the underlying field. Read it before quoting a sum: unit counts are populated on a minority of records, so a summed unit figure describes the records that have one, not the market.


        **Small groups are suppressed.** Any group with fewer than 5 projects is dropped and counted in `suppressed`, and a grand total below 5 is withheld as well. This is a privacy floor, not a bug: without it a narrow enough filter set would identify a single project.


        Unknown parameters, unknown fields and unknown metrics return `400` with the valid set attached. Nothing is silently ignored, because a silently coarser grouping is a plausible wrong answer.'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                dataset:
                  type: string
                  enum:
                  - projects
                  default: projects
                filters:
                  type: object
                  description: The same filter vocabulary as `GET /projects/search`.
                groupBy:
                  type: array
                  maxItems: 3
                  items:
                    type: string
                  description: Field names from `GET /analytics/datasets`. At most 3.
                metrics:
                  type: array
                  items:
                    type: string
                  default:
                  - count
                orderBy:
                  type: string
                  default: count
                  description: A metric name. Added to `metrics` if not already requested.
                direction:
                  type: string
                  enum:
                  - asc
                  - desc
                  default: desc
                limit:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 50
      responses:
        '200':
          description: Groups with their metrics and coverage fractions, grand totals, and what was suppressed. No record identity.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '400':
          description: Unknown parameter, field, or metric, or a limit exceeded. `details.problems[]` names each one and lists the valid values. Nothing is charged; this endpoint is free.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/GeographicAccessDenied'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '503':
          description: Project search is temporarily unavailable, so no aggregate could be produced. Never reported as a count of zero.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
      operationId: postAnalyticsAggregate
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
  /analytics/rankings:
    post:
      tags:
      - Analytics
      summary: Rank places by a metric, with a denominator (free)
      description: '**Free: zero credits, no record identity.** A leaderboard over a geographic grain, which is deliberately a separate endpoint from `/analytics/aggregate` rather than a sort on it.


        The difference is `minDenominator`. The most common way a ranking lies is a top row computed over one project, and a caller assembling a leaderboard out of a group-by gets no denominator floor and does not know it is missing one. Rows below the floor are **excluded and counted**, never silently absent.


        Every row carries its `denominator`, its `coverage`, and a `comparison.baseline` (the same metric over the whole filtered set), so a row can be read as a share of the market rather than as a bare number.


        `minDenominator` cannot be set below the suppression floor of 5.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - rankBy
              - over
              properties:
                dataset:
                  type: string
                  enum:
                  - projects
                  default: projects
                filters:
                  type: object
                  description: The same filter vocabulary as `GET /projects/search`.
                rankBy:
                  type: string
                  description: A rankable metric from `GET /analytics/datasets`.
                over:
                  type: string
                  enum:
                  - city
                  - county
                  - state
                direction:
                  type: string
                  enum:
                  - asc
                  - desc
                  default: desc
                limit:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 10
                minDenominator:
                  type: integer
                  minimum: 5
                  default: 10
      responses:
        '200':
          description: Ranked rows with denominators, coverage and a comparison baseline, plus what was excluded and why.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '400':
          description: Unknown or unrankable metric, a non-geographic `over`, or a `minDenominator` below the suppression floor. Nothing is charged.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/GeographicAccessDenied'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '503':
          description: Project search is temporarily unavailable. Never reported as an empty ranking.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
      operationId: postAnalyticsRankings
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
components:
  responses:
    PaymentRequired:
      description: 'Subscription missing, credits exhausted, or the page this request would deliver costs more than the balance has left.


        * `subscription_required`: no active paid plan or trial behind this key.

        * `credits_exhausted`: the balance cannot cover even one record and this response would have billed at least one. Re-reads of unchanged records you already own bill 0 and are still served at 0 balance. Paid balances refill on the 1st; trial credits never do.

        * `insufficient_credits`: the balance has credits left, but fewer than this page would cost. A page is delivered whole or refused whole, never trimmed, so **no records are returned and nothing is charged**. `details.quote` states the page''s cost, what remains, `affordableRecordCount` (the `limit` to retry with), and a free `countUrl` that re-prices the whole match set. Free-trial pages are truncated instead of refused here; see `meta.trialTruncation`.

        * `enrichment_requires_paid_plan`: `include=contacts` (Find Contact Info) needs a paid plan or a live trial. Record credits may still remain. Drop the parameter, start a trial, or upgrade.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: credits_exhausted
              message: You have used all your API credits for this billing period. Credits reset on the 1st of each month.
              param: null
              details:
                creditsUsed: 5000
                creditsLimit: 5000
                resetsAt: '2026-06-01T00:00:00Z'
              docsUrl: https://boardwalkai.com/docs/api/errors#credits_exhausted
              requestId: req_01K1QF3M0000EXAMPLE0001
      headers:
        X-Boardwalk-Schema-Version:
          $ref: '#/components/headers/BoardwalkSchemaVersion'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: missing_api_key
              message: 'API key is required. Include it as Authorization: Bearer bwk_live_... or X-API-Key: bwk_live_...'
              param: null
              details: {}
              docsUrl: https://boardwalkai.com/docs/api/errors#missing_api_key
              requestId: req_01K1QF3M0000EXAMPLE0001
      headers:
        X-Boardwalk-Schema-Version:
          $ref: '#/components/headers/BoardwalkSchemaVersion'
    RateLimitExceeded:
      description: 'Too many requests in the trailing 60 seconds. Limits are per API key: 60 requests per minute on any paid plan, 10 per minute on a free-trial key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 also carries Retry-After. Before authentication, a missing credential uses a 10-per-minute source-IP bucket and an unknown or unusable Boardwalk-shaped key uses its own 10-per-minute credential-digest bucket.'
      headers:
        X-Boardwalk-Schema-Version:
          $ref: '#/components/headers/BoardwalkSchemaVersion'
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Requests allowed per minute for the applicable key or pre-authentication bucket.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests left in the current window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix timestamp at which the window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: rate_limit_exceeded
              message: Rate limit of 60 requests per minute exceeded. Retry in 12 seconds.
              param: null
              details:
                retryAfterSeconds: 12
              docsUrl: https://boardwalkai.com/docs/api/errors#rate_limit_exceeded
              requestId: req_01K1QF3M0000EXAMPLE0001
    GeographicAccessDenied:
      description: Requested state filter falls outside the licensed geography of the calling subscription.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: geographic_access_denied
              message: Your subscription does not include access to one or more requested states.
              param: null
              details: {}
              docsUrl: https://boardwalkai.com/docs/api/errors#geographic_access_denied
              requestId: req_01K1QF3M0000EXAMPLE0001
      headers:
        X-Boardwalk-Schema-Version:
          $ref: '#/components/headers/BoardwalkSchemaVersion'
  schemas:
    ApiError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - param
          - details
          - docsUrl
          - requestId
          properties:
            code:
              type: string
              description: Stable machine-readable code. Branch on this value.
            message:
              type: string
              description: Human-readable explanation. Do not parse it.
            param:
              type:
              - string
              - 'null'
              description: The offending input parameter, when applicable.
            details:
              type: object
              description: Structured, camelCase context. Always an object, empty when there is no context.
              additionalProperties: true
            docsUrl:
              type: string
              format: uri
              description: Documentation for this exact error code.
            requestId:
              type: string
              description: Matches X-Request-Id and the server-side usage/log record.
          additionalProperties: false
      additionalProperties: false
  headers:
    BoardwalkSchemaVersion:
      description: The date-stamped response contract version. Present on every public v1 response.
      schema:
        type: string
        example: '2026-09-16'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Boardwalk API key. Keys you create under Settings → API are prefixed `bwk_live_` and read the production corpus against your plan or free-trial balance. `bwk_test_` is reserved for a separate sandbox environment that is not serving data yet. Pre-rename `csk_` keys are accepted indefinitely. Create and rotate keys at https://boardwalkai.com/profile/api.
x-refined-from:
- boardwalkai-com-openapi.json
- boardwalkai-com-openapi.yml