Boardwalk Lists API

openapi: 3.2.0
info:
  title: Boardwalkai Com Lists API
  version: '2026-09-16'
  contact:
    name: Boardwalk Support
    email: support@boardwalkai.com
    url: https://boardwalkai.com
  description: 'Operations tagged Lists 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: Lists
  description: 'Saved lists of projects, shared with you or with your team. Reading a list''s configuration is free. Pulling its records uses the same record meter as search: free on County, State, and National; 1 credit per new or changed record on Standalone API Only and the free trial. Find Contact Info is billed separately when email or phone is delivered.'
paths:
  /lists:
    get:
      tags:
      - Lists
      summary: List the saved lists you can see (free)
      description: 'Every saved list your **membership** resolves: your own (including the system **Saved** list, marked `isDefault: true`), plus the ones shared with you. Lists created from an alert delegate their sharing to that alert. System Saved stays unshareable. **Free.**


        Each entry carries its `lst_…` id, `source` (`manual`, `alert`, `filter`, `polygon`, `system`), `isDefault`, `share` block (`{mode, userIds, optOutUserIds}`, where `userIds` is the live membership), and `alreadyOnThis` / `projectCount`. For an alert companion those counts are the parent alert''s matches minus dismissed (pending review included), the same set as `GET /alerts/{alertId}/matches`. `pendingReview` is how many of those matches are not yet saved. `null` for `filter`/`polygon` lists, which store a query, not records.'
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      - name: offset
        in: query
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: Your lists. `meta.creditsUsed` is 0.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      operationId: getLists
      x-operation-id-source: derived
    post:
      tags:
      - Lists
      summary: Create a named list (free)
      description: Create a membership-backed list (`source=manual`) to save projects onto. **Free.** This is the "new list" option on the save chooser. Adding records is a separate `POST /lists/{listId}/projects`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  maxLength: 255
                description:
                  type: string
      responses:
        '201':
          description: The new list. `meta.creditsUsed` is 0.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '400':
          description: Missing name.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: postLists
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
  /lists/{listId}/projects:
    post:
      tags:
      - Lists
      summary: Add projects to a list (free)
      description: Add up to 100 project ids to a membership-backed list (Saved, alert companions, or a named `manual` list). **Free.** Idempotent per id. Filter and polygon lists refuse because they store criteria, not rows.
      parameters:
      - name: listId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - projectIds
              properties:
                projectIds:
                  type: array
                  items:
                    type: integer
                  maxItems: 100
      responses:
        '201':
          description: At least one id was added.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '200':
          description: Every id was already on the list.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '404':
          description: No list your membership resolves, or an unknown project id.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
      operationId: postListsByListIdProjects
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
  /lists/{listId}/projects/{projectId}:
    delete:
      tags:
      - Lists
      summary: Remove a project from a list (free)
      description: Removes the project and its merge family from a membership-backed list. **Free.**
      parameters:
      - name: listId
        in: path
        required: true
        schema:
          type: string
      - name: projectId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: '`removed` is true when a row was deleted.'
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '404':
          description: No list your membership resolves has this id.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
      operationId: deleteListsByListIdProjectsByProjectId
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
  /lists/{listId}:
    get:
      tags:
      - Lists
      summary: Read one list, and price its records (free)
      description: 'One list''s configuration and share state, plus `results.billable`: **the free preflight for `/results`**. For an alert companion, `alreadyOnThis` is every match except dismissed (pending review stays in) and `/results` is free. For a manual or Saved list, `results.resultCount` is how many records the list holds and `results.billable.credits` is what a full pull would charge right now, with records your account already holds unchanged priced at zero. `links.results` is the pull URL.


        For a `filter`/`polygon` list the payload instead carries the stored `criteria` and `links.search`, because those lists store a query, not records, and their results are priced where searches are priced.'
      parameters:
      - name: listId
        in: path
        required: true
        schema:
          type: string
        example: lst_01JQ8Z6X9F3K2M7T
      responses:
        '200':
          description: The list. `meta.creditsUsed` is 0.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: No list your membership resolves has this id. A list that exists but is not shared with you answers 404, never 403, because this surface never confirms an id exists.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
      operationId: getListsByListId
      x-operation-id-source: derived
    servers:
    - url: https://api.boardwalkai.com/api/v1
      description: Production
    - url: http://localhost:8000/api/v1
      description: Local development
  /lists/{listId}/results:
    get:
      tags:
      - Lists
      summary: The list's records (free)
      description: 'The saved records themselves, hydrated and shaped **now** through the same pipeline as `GET /projects/search`: the serving gate, party shaping and contact suppression apply at read time, so a record that has become unservable is dropped from the page rather than served because someone once saved it.


        **Alert companions** return the parent alert''s matches minus dismissed (pending review included) and are **free**: the same set as `GET /alerts/{alertId}/matches` without `deliveryId`.


        **Manual and Saved lists** are also free to read. Find Contact Info on those records is 1 credit per project the first time this account receives email or phone. Extra search filters (`acreageMin`, `propertyTypes`, `projectSizes`, …) apply only inside the ids already on this list. `meta.alreadyOnThis` is the unfiltered set; `meta.total` is the subset.


        For a `filter`/`polygon` list this returns the stored `criteria` plus `links.search`, free. Running the search happens on the search route.'
      parameters:
      - name: listId
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Records per page. Capped at 25 when `representation=full`, which carries the raw source text.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      - name: offset
        in: query
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/Representation'
      responses:
        '200':
          description: The delivered records, each with a `delivery` block (`alreadyExported`, `updatedSinceExport`, `billed`). `meta.creditsUsed` is what this page actually charged; `meta.total` is the whole list.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '400':
          description: An unknown representation, or `limit` above 25 with `representation=full`.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: No list your membership resolves has this id.
          headers:
            X-Boardwalk-Schema-Version:
              $ref: '#/components/headers/BoardwalkSchemaVersion'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      operationId: getListsByListIdResults
      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'
    IdempotencyConflict:
      description: 'The `Idempotency-Key` on this request conflicts with an earlier one. `error.code` says which:


        * `idempotency_key_reuse`: this key was already used for a **different** request. `details.originalEndpoint` and `details.originalCreatedAt` name the request it belongs to. Mint a new key per distinct request; reuse a key only to retry the request it was minted for.

        * `idempotency_in_flight`: the original request with this key is still running. Retry in a moment to receive its result; you will not be charged twice. Carries a `Retry-After` header, echoed as `details.retryAfterSeconds`.


        Both name `Idempotency-Key` in `error.param`. Nothing is delivered and nothing is charged.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: idempotency_key_reuse
              message: This Idempotency-Key was already used for a different request. Generate a new key for each distinct request; reuse a key only to retry the request it was minted for.
              param: Idempotency-Key
              details:
                originalEndpoint: api_v1_projects_search
                originalCreatedAt: '2026-08-27T14:02:11+00:00'
              docsUrl: https://boardwalkai.com/docs/api/errors#idempotency_key_reuse
              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
  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'
  parameters:
    Representation:
      name: representation
      in: query
      required: false
      description: 'How much of each record to return: `compact`, `standard`, `full`. Each nests inside the next. Representation does not change the record price. County, State, and National search, detail, and sync are free; Standalone API Only and the free trial are 1 credit per new or changed record. Find Contact Info is billed separately. An unrecognised value returns `400` rather than being coerced to the default.'
      schema:
        type: string
        enum:
        - compact
        - standard
        - full
        default: standard
  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