Boardwalk Exports API

openapi: 3.2.0
info:
  title: Boardwalkai Com Exports API
  version: '2026-09-16'
  contact:
    name: Boardwalk Support
    email: support@boardwalkai.com
    url: https://boardwalkai.com
  description: 'Operations tagged Exports 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: Exports
  description: CSV export jobs queued from the product, from POST /exports, or from search format=csv.
paths:
  /exports:
    get:
      tags:
      - Exports
      summary: List export jobs (free)
      description: Team export history, including jobs queued via `POST /exports` or `GET /projects/search?format=csv`. **Free to list.** Credits were reserved when each job was created.
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: Recent export jobs for your team scope.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: getExports
      x-operation-id-source: derived
    post:
      tags:
      - Exports
      summary: Queue a CSV export
      description: 'Queues the same product CSV as the map Export button. **Rows are free.** Find Contact Info on those rows is 1 credit per project the first time this account receives email or phone.


        Pass **exactly one** of `alertId`, `listId`, or `projectIds` to export a saved set. Extra map filters (`acreageMin`, `propertyTypes`, …) apply only inside those ids. Omit all three and the body is a new search, with the same match as `GET /projects/search?format=csv`.


        A filter or polygon list has no saved records: pass `projectIds` you already pulled, or search filters without `listId`.


        Returns a receipt (HTTP 202). Poll `pollUrl` / download via `downloadUrl`. The file also appears on the product `/exports` page. Never streams CSV bytes on this route.'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                alertId:
                  type: string
                  description: Export every match on this alert except dismissed (pending review stays in).
                listId:
                  type: string
                  description: Export a membership list, or the same curated set as its companion alert.
                projectIds:
                  type: array
                  items:
                    type: integer
                  maxItems: 25000
                  description: 'The ids you already have after pull or further filtering. Alias: `ids`.'
                ids:
                  type: array
                  items:
                    type: integer
                  maxItems: 25000
                include:
                  type: string
                  enum:
                  - contacts
                  description: Run Find Contact Info on the file (paid plans).
                maxCredits:
                  type: integer
                  minimum: 1
                  description: Refuse (400) if new-or-changed rows would reserve more than this many credits.
              additionalProperties: true
      responses:
        '202':
          description: Export job accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CsvExportJobAccepted'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '200':
          description: '`status: no_matching_rows`: nothing matched, and no job was queued.'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '400':
          description: Two sources sent, a filter/polygon list, unknown filters, or maxCredits too low.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: No alert or list with that id in your membership.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
      operationId: postExports
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
  /exports/{id}:
    get:
      tags:
      - Exports
      summary: Poll an export job (free)
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Job status and download URLs when ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CsvExportJobAccepted'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No such export job in your team scope.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
      operationId: getExportsById
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
  /exports/{id}/download:
    get:
      tags:
      - Exports
      summary: Download a ready CSV (free)
      description: 'Streams the product-core CSV artifact when status is ready. **Free re-download**: no credit check, so a file stays downloadable at a zero balance.


        A job that is not ready, has expired, or whose artifact cannot be read is a `409`, not a `404`. Write the poller against `409`.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: CSV file body.
          content:
            text/csv:
              schema:
                type: string
                format: binary
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: '`subscription_required`: the bytes need a live subscription (owner ruling 2026-08-21). Polling the job metadata on `GET /exports/{id}` does not.'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '404':
          description: No export job with this id in your team scope.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '409':
          description: 'The job exists but cannot be downloaded right now. `error.code` says which:


            * `export_not_ready`: still building. Poll `GET /exports/{id}` until `status` is `ready`.

            * `export_expired`: the file is no longer stored. Re-run the search with `format=csv`.

            * `export_unavailable`: built, but its artifact could not be read back, so it was never delivered. `error.details.creditsRefunded` states what was returned to the pool.'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
      operationId: getExportsByIdDownload
      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'
  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
    CsvExportJobAccepted:
      type: object
      description: HTTP 202 body for `POST /exports` and `GET /projects/search?format=csv`, and the same shape from `GET /exports/{id}`.
      properties:
        exportJobId:
          type: integer
        status:
          type: string
          enum:
          - queued
          - running
          - ready
          - failed
          - expired
          - no_matching_rows
          - no_billable_rows
        format:
          type: string
          enum:
          - csv
        pollUrl:
          type: string
        downloadUrl:
          type: string
        webExportsUrl:
          type: string
          description: Product UI export history for the same team scope.
        job:
          type: object
          additionalProperties: true
          properties:
            contactBilling:
              $ref: '#/components/schemas/ContactBillingReceipt'
        meta:
          type: object
          properties:
            projectCount:
              type: integer
            creditsReserved:
              type: integer
            columnGroups:
              type: array
              items:
                type: string
            csvFields:
              type: string
              example: product_core
            enrichmentRequested:
              type: boolean
              description: True when this job will run Find Contact Info for the exported project IDs.
            creditsUsed:
              type: integer
            downloadable:
              type: boolean
    ContactBillingReceipt:
      type:
      - object
      - 'null'
      description: Cumulative job billing. meta.creditsUsed on polling remains zero. Only a newly unlocked project delivering an external person email, phone, or personal LinkedIn qualifies. Company links and names alone are free.
      properties:
        attemptKey:
          type: string
        reserved:
          type: integer
        charged:
          type: integer
        released:
          type: integer
        refunded:
          type: integer
        qualifyingProjects:
          type: integer
        newlyUnlockedProjects:
          type: integer
        alreadyUnlockedProjects:
          type: integer
        recordReserved:
          type: integer
        recordCharged:
          type: integer
        recordReleased:
          type: integer
        settled:
          type: boolean
  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