Skip to content

Integration — REST API

Public · Status: 🔄 in progress

1. Purpose

Pull measurements over HTTPS/JSON — for apps, dashboards, or webhooks. Best when you want data on demand in a familiar request/response shape.

2. When to use it

  • You're building an app or report and want to query convoys/cars for your organization.
  • You want near-real-time pulls (poll; webhooks on convoy completion are 🔄 proposed — see §7).

3. Authentication & base URL

  • Base URL — https://bsp.ita.builders/api/v1.
  • Credential — your per-organization API key, sent as X-API-KEY: bsp_live_xxx (or Authorization: Bearer bsp_live_xxx). The key scopes every response to your organization.
  • Transport — HTTPS only. See Getting started.

4. Endpoints (read surface — 🔄 proposed)

The public client surface is the read subset below. (The internal node→server and admin routes are not part of it.)

Method · Path Returns
GET /segments the segments your org can see
GET /segments/{id}/convoys convoys at a segment — paged (limit, cursor), filtered (from, to, direction)
GET /convoys/{id} one convoy + its cars (volume, length, RFID, confidence)
GET /segments/{id}/car-history per-car loaded−empty net volume (reconstructed)
GET /convoys/{id}/report.pdf the per-convoy PDF report
GET /convoys/{id}/artifacts presigned S3 URLs for the convoy bundle → S3 export

Paths are relative to the base URL, so a full call is https://bsp.ita.builders/api/v1/segments/{id}/convoys.

Pagination — list endpoints return { "data": [...], "next_cursor": "..." | null }; pass cursor= to fetch the next page. Dates — ISO 8601 (from=2026-06-01T00:00:00Z).

5. Example

# Latest convoy at a segment, with its cars
curl -H "X-API-KEY: bsp_live_xxx" \
  "https://bsp.ita.builders/api/v1/segments/seg_42/convoys?limit=1"

# Then drill into one convoy
curl -H "X-API-KEY: bsp_live_xxx" \
  "https://bsp.ita.builders/api/v1/convoys/cvy_8f3a"
Response shape → Data model.

6. Errors

JSON bodies: { "error": { "code": "...", "message": "..." } }. Common codes: 401 invalid/missing key, 403 key not entitled to that resource, 404 unknown id (or not in your org), 429 rate limited (honor Retry-After).

7. Reference & roadmap

  • OpenAPI — the public read subset is published as a versioned OpenAPI document (🔄 to be linked here when the surface ships); the internal API also generates a spec at the server's /docs.
  • Webhooks — push on convoy completion (POST to your URL, HMAC-signed) is 🔄 proposed.

🔄 Endpoints, parameters, and field names above are the proposed public contract and may change until the surface is published.