Getting started

Create a free account, create a key under Settings → API, and pull your first project records in about five minutes.

How to get started

1Create a free account.
2After you sign in, open Settings → API.
3Click Create new secret key, copy it once, and store it safely.
4Your free trial includes 50 record-export credits (search, CSV, MCP — mix and match) and 5 Find Contact Info lookups. Those two grants are separate. Trial credits do not reset monthly — they are a one-off evaluation budget.
5Send Authorization: Bearer … to https://api.boardwalkai.com/api/v1.

The rest of this page walks those calls. Locations, count, and search are free on County, State, and National. On a trial or API Only key, search costs 1 credit per new record — count first so you know the size of the set.

1. Get a key

Sign up for a free account, then create a key under Settings → API. You do not need a paid subscription to create a key; entitlement is checked when you call, not when you create it. A free trial includes 50 credits for evaluation over the API.

The key you create there begins with bwk_live_ and reads the production corpus against your trial balance. That is the right credential for getting started. Keys prefixed bwk_test_ are reserved for a separate sandbox environment that is not serving data yet — do not use one for these first calls. Prefix detail and rotation: Authentication.

2. Prove the key works, for free

Which states this key can search

bash

curl 'https://api.boardwalkai.com/api/v1/locations/states' \
  -H 'Authorization: Bearer bwk_live_YOUR_KEY'

Response · HTTP 200

json

{
  "data": [
    {
      "id": 54,
      "name": "Arizona",
      "abbreviation": "AZ",
      "latitude": 34.0489,
      "longitude": -111.0937,
      "entitled": false
    },
    {
      "id": 57,
      "name": "Colorado",
      "abbreviation": "CO",
      "latitude": 39.5501,
      "longitude": -105.7821,
      "entitled": false
    },
    {
      "id": 1,
      "name": "Utah",
      "abbreviation": "UT",
      "latitude": 39.321,
      "longitude": -111.0937,
      "entitled": true
    }
  ],
  "meta": {
    "geographyScope": "states",
    "entitledStateIds": [
      1
    ],
    "countyRestricted": false
  }
}

The response shape on this page is the one the endpoint builds — the keys, their nesting and their types are asserted against the shipping code by a test. The numbers inside it are the scenario being walked through, not a measurement of the corpus.

Credit costFree — 0 creditsFree. Resolve the ids you filter with.

A 200 here means your key is good. Read entitled on each state — that is the geography this key can search and export for free. If you get 401, the credential did not reach us — check that the header is Authorization: Bearer … and that you copied the whole key.

3. See how many projects match

Count a narrower query

bash

curl 'https://api.boardwalkai.com/api/v1/projects/count?states=UT&assetClasses=Apartment%20Building&meetingDateFrom=2026-05-01&totalUnitCountMin=50' \
  -H 'Authorization: Bearer bwk_live_YOUR_KEY'

Response · HTTP 200

json

{
  "data": {
    "matchCount": 250,
    "matchCountIsExact": true,
    "matchCountBasis": "enumerated",
    "countedAs": "distinct_projects",
    "collapseApplied": true,
    "duplicatesCollapsed": 0,
    "scanCeiling": 10000,
    "billable": {
      "records": 250,
      "credits": 0,
      "creditRate": 0,
      "isUpperBound": true,
      "nonBillable": {
        "alreadyDeliveredUnchanged": 0,
        "ledgerApplied": true
      }
    },
    "affordability": {
      "affordable": true,
      "blockReason": null,
      "shortfallCredits": 0,
      "maxAffordableRecords": 9223372036854776000,
      "boundBy": "period_balance",
      "unlimited": false
    },
    "ordering": {
      "sort": "meetingDate",
      "order": "desc",
      "tiebreak": null,
      "meaning": "Most recent meeting evidence first — the date of the meeting the record was extracted from, not when Boardwalk ingested it and not when the project was created."
    },
    "truncation": {
      "policy": "refuse",
      "wouldTruncate": false,
      "deliverableRecords": null,
      "explanation": "The whole match set fits inside the remaining balance: page through the metered route and every page will be delivered in full until the set is exhausted."
    }
  },
  "meta": {
    "schemaVersion": "2026-09-16",
    "representation": "standard",
    "deliveryMode": "all",
    "credits": {
      "limit": 500,
      "used": 0,
      "remaining": 500,
      "charged": 0,
      "periodStart": "2026-08-01",
      "periodEnd": "2026-08-31",
      "isTeamPool": true
    },
    "appliedFilters": {
      "states": [
        1
      ],
      "assetClasses": [
        "Apartment Building"
      ],
      "meetingDateFrom": "2026-05-01T00:00:00+00:00",
      "totalUnitCountMin": 50
    },
    "appliedDefaults": [
      "taxonomyMatchMode=primary_only",
      "includeGovernmentDecisions=false",
      "leadTypes=private",
      "sort=meetingDate",
      "order=desc"
    ],
    "resolvedFrom": {
      "states": [
        {
          "input": "UT",
          "id": 1
        }
      ]
    },
    "warnings": []
  },
  "links": {
    "self": "https://api.boardwalkai.com/api/v1/projects/count?states=UT&assetClasses=Apartment%20Building&meetingDateFrom=2026-05-01&totalUnitCountMin=50",
    "search": "https://api.boardwalkai.com/api/v1/projects/search?states=UT&assetClasses=Apartment%20Building&meetingDateFrom=2026-05-01&totalUnitCountMin=50",
    "docs": "https://boardwalkai.com/docs/api/budgets/"
  }
}

Credit costFree — 0 creditsFree, always, including when your balance is zero. How many projects match. On API Only and the trial it also prices the set; on County, State, and National, search is free.

Count is always free, even at a zero balance. It tells you how many distinct projects match. On County, State, and National, search is also free — use count to size the set. On a trial or API Only key, read affordability.affordable and billable.credits before you page: those plans charge 1 credit per new record, deliver a page whole or refuse it whole with a 402, and a trial key is the one case that truncates instead (meta.trialTruncation).

4. Pull the first page

Your first search

bash

curl 'https://api.boardwalkai.com/api/v1/projects/search?states=UT&assetClasses=Apartment%20Building&meetingDateFrom=2026-05-01&totalUnitCountMin=50&limit=1' \
  -H 'Authorization: Bearer bwk_live_YOUR_KEY'

Response · HTTP 200

json

{
  "data": [
    {
      "id": 184203,
      "recordType": "project",
      "projectName": "Alta Ridge Phase II",
      "projectHeadline": "Planning Commission approved 240 apartments with conditions",
      "boardwalkLink": "https://boardwalkai.com/map/#project=184203",
      "mergedFrom": [
        184203,
        184987
      ],
      "lastUpdated": "2026-06-18T09:22:41Z",
      "meetingDate": "2026-06-17",
      "delivery": {
        "alreadyExported": false,
        "updatedSinceExport": null,
        "lastExportedAt": null,
        "billed": true
      },
      "address": "3600 S Constitution Blvd, West Valley City, UT",
      "city": "West Valley City",
      "county": "Salt Lake",
      "state": "UT",
      "postalCode": "84119",
      "latitude": 40.6916,
      "longitude": -112.0011,
      "locationPrecision": "address",
      "locationPrecisionLabel": "Address",
      "isApproximate": false,
      "parcelApn": [
        "15-27-301-004"
      ],
      "inOpportunityZone": true,
      "inFemaFloodZone": false,
      "propertyType": "residential",
      "propertyTypeLabel": "Residential",
      "propertySubtype": "multifamily",
      "propertySubtypeLabel": "Multifamily",
      "assetClass": "Apartment Building",
      "assetClassLabel": "Apartment Building",
      "leadType": "private",
      "leadTypeLabel": "Private",
      "stage": "entitlement",
      "stageLabel": "Entitlement",
      "landUses": [
        {
          "type": "residential",
          "typeLabel": "Residential",
          "subtype": "multifamily",
          "subtypeLabel": "Multifamily",
          "assetClass": "Apartment Building",
          "assetClassLabel": "Apartment Building",
          "matchedOn": []
        }
      ],
      "status": "approved_with_conditions",
      "statusLabel": "Approved with Conditions",
      "statusSummary": "The commission approved the preliminary plat subject to eight conditions.",
      "requestType": "final_plat",
      "requestTypeLabel": "Final Plat",
      "decisionBody": "Planning Commission",
      "caseNumbers": [
        "PLAT-2026-0142"
      ],
      "acreage": 9.8,
      "squareFootage": null,
      "unitMix": [
        {
          "count": 240,
          "type": "apartment",
          "typeLabel": "Apartment"
        }
      ],
      "totalUnitCount": 240,
      "bedroomCount": null,
      "buildingStories": null,
      "floorCount": null,
      "buildingHeightFeet": null,
      "parkingSpaces": 372,
      "existingZoning": "A-1",
      "proposedZoning": "RM-16",
      "isRezone": true,
      "constructionType": "new_building",
      "constructionTypeLabel": "New Building",
      "projectSize": null,
      "projectSizeLabel": null,
      "developerCompany": "Alta Ridge Development LLC",
      "developerCompanyRole": "developer",
      "developerCompanyRoleLabel": "Developer",
      "contacts": [
        {
          "name": "Rachel Okafor",
          "title": "Director of Development",
          "role": "developer",
          "roleLabel": "Developer",
          "partyClass": "external",
          "partyClassLabel": "External Party",
          "entityType": "person",
          "company": "Alta Ridge Development LLC",
          "email": "r.okafor@example.com",
          "emailSource": "filing",
          "phone": "+1-555-0142",
          "phoneSource": "filing",
          "linkedinUrl": null,
          "linkedinSource": null,
          "contactProvenance": "filing",
          "enrichmentSource": null,
          "enrichedAt": null,
          "enrichmentStatus": "not_requested",
          "contactsWithheldReason": null
        }
      ],
      "contactEnrichment": {
        "status": "not_requested",
        "statusLabel": "Not Requested",
        "attemptedAt": null,
        "contactsFound": 0,
        "source": "registry"
      },
      "companyEnrichment": [],
      "publicOfficials": [
        {
          "name": "Dana Whitfield",
          "title": "Senior Planner",
          "role": "city_planner",
          "roleLabel": "City Planner",
          "partyClass": "government",
          "organization": "West Valley City"
        }
      ],
      "contactSummary": {
        "externalCount": 1,
        "governmentCount": 1,
        "unclassifiedCount": 0,
        "withEmail": 1,
        "withPhone": 1,
        "withLinkedin": 0,
        "enrichedCount": 0,
        "lowConfidenceWithheld": 0,
        "withheldCount": 0,
        "withheldReason": null
      },
      "keyFacts": [
        {
          "fact": "240 apartment units across six buildings",
          "category": "unit_mix",
          "categoryLabel": "Unit Mix"
        }
      ],
      "evidence": "Commissioner Reyes moved to approve subject to conditions 1-8.",
      "summary": "A 240-unit garden-style apartment community on 9.8 acres.",
      "voteSummary": {
        "yes": 2,
        "no": 1,
        "abstain": 0,
        "absent": 1,
        "total": 4,
        "isUnanimous": false,
        "meetingDate": "2026-06-17"
      },
      "sourceDocumentUrl": "https://www.example-city.gov/media/agendas/2026-06-17-planning-commission-packet.pdf"
    }
  ],
  "meta": {
    "schemaVersion": "2026-09-16",
    "representation": "standard",
    "total": 1,
    "pageCount": 1,
    "hasMore": true,
    "limit": 1,
    "offset": 0,
    "creditsUsed": 0,
    "creditsRemaining": 2500,
    "trialTruncation": null,
    "searchMethod": "redisearch",
    "appliedFilters": {
      "states": [
        1
      ],
      "assetClasses": [
        "Apartment Building"
      ],
      "meetingDateFrom": "2026-05-01T00:00:00+00:00",
      "totalUnitCountMin": 50
    },
    "appliedDefaults": [
      "taxonomyMatchMode=primary_only",
      "includeGovernmentDecisions=false",
      "leadTypes=private",
      "sort=meetingDate",
      "order=desc"
    ],
    "resolvedFrom": {
      "states": [
        {
          "input": "UT",
          "id": 1
        }
      ]
    },
    "warnings": [],
    "matchCount": null,
    "matchCountIsExact": false,
    "matchCountBasis": "not_computed",
    "duplicatesCollapsed": 0,
    "collapseApplied": true,
    "delivery": {
      "mode": "all",
      "notPreviouslyExported": 1,
      "previouslyExported": 0,
      "updatedSinceExport": 0,
      "billed": 0,
      "notRebilled": 1,
      "ledgerApplied": true
    }
  }
}

Record bodies on this page were produced by running Boardwalk's production response mapper over a documented sample project, so the field set, the labels and the empty fields are exactly what the API emits. The project itself is a sample, not a real filing.

Credit costFree — 0 creditsCounty, State, and National: free. Standalone API Only and the free trial: 1 credit per delivered record that is new to this pool or changed since last delivery; unchanged owned records are free. `format=csv` queues the full filter match and returns HTTP 202 with poll/download URLs. Find Contact Info is billed separately on County/State/National, and included on API Only records already purchased.

This call reuses the filters from links.search in step 3 and adds limit=1. On County, State, and National it costs nothing, including representation=full. On a trial or API Only key, a new record costs 1 credit; an unchanged record you already pulled is free. The record carries a delivery block so you can tell those two cases apart. Email and phone stay off the record until you run Find Contact Info.

Rate limits before you loop

Paid keys are limited to 60 requests per minute. Watch X-RateLimit-Remaining and back off before you hit 429 — a well-behaved client rarely needs the error path. Full headers, Retry-After, and cookbook: Rate limits.

What you just spent

Step	Endpoint	Trial or API Only
1	Create a key	0
2	`GET /locations/states`	0
3	`GET /projects/count`	0
4	`GET links.search` with `limit=1`	1 if the record is new
	Total	0 or 1

Where to go next

The free sandbox Recipes for your use case Every filter you can send Every field you can receive Interactive reference

Ready to make a call?

A free Boardwalk trial includes API access, 50 record-export credits (search, CSV, MCP), and 5 Find Contact Info lookups. Counting, taxonomy, location lookups and the analytics plane cost nothing, so you can evaluate the data before you spend a credit.

Create a free account Settings → API Connect your AI Plans and pricing