REST API

BXP REST API

The complete HTTP contract for a BXP v2.0 node. Every BXP node exposes this surface, so any client written against it can query any node.

Version 2.0 · 23 endpoints · OpenAPI 3.1.0 · generated from the running reference server

Machine-readable contract The authoritative definition is the OpenAPI 3.1 document at openapi.json. Import it into Postman, Insomnia, or any OpenAPI-aware tool. This page is generated from that same file, so it cannot describe an endpoint the server does not implement.

Using the API

Submit a reading:

curl -X POST http://localhost:5000/bxp/v2/readings \
  -H "Content-Type: application/json" \
  -d '{"readings":[{"latitude":5.6037,"longitude":-0.1870,
       "source":"native",
       "agents":[{"agentId":"PM2_5","value":47.2,"unit":"ug/m3"}]}]}'

Find relevant observations near a point:

curl "http://localhost:5000/bxp/v2/nearby?lat=5.60&lon=-0.18&radiusKm=25"

Replicate from a peer node:

curl "http://localhost:5000/bxp/v2/sync?since=0"

Authentication

Reads are unauthenticated. Writes require a device token obtained from POST /bxp/v2/devices/register, which is rate limited to 5 requests per minute per IP. Inter-node replication uses a shared secret. Both mechanisms are deliberately minimal — real node identity and trust are deferred to a future RFC rather than left implied.

Version negotiation

The major path segment is the protocol major version. MINOR additions are backward compatible: a server may add response fields, and clients must ignore-and-preserve fields they do not recognise. Breaking changes require a new major version with 18 months advance notice.

Readings

GET/bxp/v2/locations/{geohash}/aggregate

Get Location Aggregate

Privacy-safe aggregate (SPEC.md 9): only returned when >= 5 readings contribute.

GET/bxp/v2/locations/{geohash}/history

Get Location History

GET/bxp/v2/locations/{geohash}/latest

Get Location Latest

GET/bxp/v2/nearby

Get Nearby

Relevance-ranked "closest useful observation" lookup (SPEC.md 7 Stage 6, 8.2.1) for a caller with no sensor of their own. Ranking blends distance, freshness and quality; see database.get_nearby_readings.

GET/bxp/v2/readings

Get Readings

List stored readings (offset pagination). With no filters, returns live data for the default cities. format=binary returns one binary `.bxp` container (SPEC.md 5.4, fileType="aggregate") wrapping {"readings": [...]}.

POST/bxp/v2/readings

Submit Readings

Accept BXP readings as JSON (SPEC.md 2) or a binary `.bxp` container (SPEC.md 5.1/5.2, auto-detected by magic number). The batch is stored atomically; a reading whose ID already exists is reported, never overwritten.

DELETE/bxp/v2/readings/{reading_id}

Delete Reading Endpoint

Delete a reading with cryptographic proof (SPEC.md 9). The authenticated device must be the one that submitted it. The reading's content is erased; only a tombstone remains so the deletion replicates to peers.

GET/bxp/v2/readings/{reading_id}

Get Reading By Id

format=binary returns the reading as a binary `.bxp` container (fileType="reading").

GET/bxp/v2/readings/{reading_id}/verify

Verify Reading Endpoint

GET/bxp/v2/search

Search

Search by city name (live AQICN data) and/or coordinates (stored readings in that cell).

GET/compare

Compare View

Devices

POST/bxp/v2/devices/register

Register Device Endpoint

GET/bxp/v2/devices/{device_uuid}

Get Device Endpoint

Community

GET/bxp/v2/community/reports

Get Reports

POST/bxp/v2/community/reports

Submit Report

Federation

GET/bxp/v2/nodes

List Nodes

POST/bxp/v2/nodes/announce

Announce Node

Register a peer node so it appears in GET /nodes. This is a directory entry only - this server never fetches the announced URL - and a node_id cannot be re-pointed at a different baseUrl (see database.upsert_node).

GET/bxp/v2/sync

Sync Pull

Federation pull (SPEC.md 7 Stage 7, 8.2.2). Returns every change after the opaque cursor `since` (default 0 = from the beginning), oldest first, plus `nextCursor` to resume from. Deleted readings arrive as tombstones ({"readingId", "deleted": true, "deletionProof"}) that a replica must apply.

Operations

GET/

Root

GET/bxp/v2/city/{city}

Get City

GET/bxp/v2/health

Health

GET/dashboard

Dashboard Home

GET/dashboard/{city}

Dashboard

GET/map

Map View

GET/metrics

Metrics

Prometheus-compatible metrics.

GET/widget/{city}

Widget

Embeddable iframe widget.

23 paths · 26 operations · generated from the reference server's OpenAPI document. See also the prose API documentation.