API documentation

Create a key on your API keys page. A key is shown once, at the moment you create it, because we keep only a fingerprint of it afterwards. Store it the way you store any other secret and keep it out of code you publish. You can hold five keys at a time and you can revoke any of them from the same page, which takes effect on the next request.

Send the key as a bearer token on every request.

curl https://buildvue.co/api/v1/projects \
  -H "Authorization: Bearer bv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

A request with no key, or with a key that has been revoked, comes back as 401. A key belonging to an account on a smaller plan comes back as 403.

GET /api/v1/projects returns a page of projects with the filters, sorting and totals the web app uses. Every parameter is optional.

curl "https://buildvue.co/api/v1/projects?city=Seattle&status=construction&unitsMin=50&pageSize=2" \
  -H "Authorization: Bearer $BUILDVUE_API_KEY"

{
  "data": [
    {
      "id": "clx8f0k2p0001qk3h9m2v7c1a",
      "address": "1200 Stewart St",
      "city": "Seattle",
      "neighborhood": "Denny Triangle",
      "status": "construction",
      "projectType": "mixed_use",
      "projectSubTypes": ["multi_family", "retail"],
      "unitCount": 386,
      "stories": 44,
      "parkingSpaces": 120,
      "estimatedValue": "184000000",
      "latitude": 47.6183,
      "longitude": -122.3361
    }
  ],
  "meta": {
    "page": 1,
    "limit": 2,
    "total": 137,
    "totalPages": 69,
    "aggregates": { "count": 137, "units": 21044, "estValue": 8114000000 },
    "version": "v1"
  }
}

The example above is trimmed. A record carries every field the app holds for a project, and anything the source records leave blank comes back as null rather than being dropped.

GET /api/v1/projects/{id} returns the full record for one project, with its permits, parcels, sales history, contacts and press coverage. The id is the one the list endpoint gives you.

curl https://buildvue.co/api/v1/projects/clx8f0k2p0001qk3h9m2v7c1a \
  -H "Authorization: Bearer $BUILDVUE_API_KEY"

{
  "data": {
    "id": "clx8f0k2p0001qk3h9m2v7c1a",
    "address": "1200 Stewart St",
    "status": "construction",
    "developer": "Onni Group",
    "architect": "Weber Thompson",
    "unitCount": 386,
    "permits": [
      {
        "permitNumber": "6811234-CN",
        "type": "construction",
        "status": "issued",
        "jurisdiction": "seattle",
        "contractor": "Lease Crutcher Lewis",
        "contractorLicense": "LEASECL881QK",
        "applicationDate": "2024-03-11T00:00:00.000Z",
        "issueDate": "2025-01-22T00:00:00.000Z"
      }
    ],
    "contacts": [
      { "name": "Onni Group", "role": "developer", "company": "Onni Group" }
    ],
    "parcels": [
      { "pin": "0659000305", "sales": [{ "price": 42500000, "date": "2021-06-30T00:00:00.000Z" }] }
    ],
    "newsArticles": []
  },
  "meta": { "version": "v1" }
}

GET /api/v1/aggregates returns counts and sums for each phase of the pipeline, which is the quickest way to size a market without paging through every project. The filters work as they do on the project list.

curl "https://buildvue.co/api/v1/aggregates?type=residential" \
  -H "Authorization: Bearer $BUILDVUE_API_KEY"

{
  "data": {
    "design_review": { "count": 62, "units": 9184, "parking": 2410, "officeSqft": 0, "retailSqft": 41200, "estValue": 3120000000 },
    "land_use": { "count": 148, "units": 19022, "parking": 5104, "officeSqft": 122000, "retailSqft": 96400, "estValue": 6740000000 },
    "construction": { "count": 137, "units": 21044, "parking": 6890, "officeSqft": 210500, "retailSqft": 118300, "estValue": 8114000000 },
    "complete": { "count": 204, "units": 28110, "parking": 9033, "officeSqft": 318000, "retailSqft": 174900, "estValue": 10980000000 }
  },
  "meta": { "version": "v1" }
}

Every failure uses one envelope, so you can read the code without parsing the message. The message is meant for a person reading a log and may be reworded. The code will not change.

{
  "error": {
    "code": "UPGRADE_REQUIRED",
    "message": "The developer API is part of the Business plan. Upgrade to Business to use it."
  }
}

Each key may make 60 requests a minute. Calls for a single project also draw on an account wide budget of 600 an hour that is shared with the web app, so a busy afternoon inside the product counts toward it as well.

Going past a limit gives you a 429 carrying the RATE_LIMITED code. The response includes Retry-After in seconds, along with X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, so your client can back off without guessing.

Write to support@buildvue.co if you need a field the API does not return yet, or if you are planning something large enough that these limits get in your way.