API Reference

Base URL: https://api.colpero.com

Authentication

All endpoints except /health require an API key passed via the X-API-Key header.

curl -H "X-API-Key: your-api-key" \
  https://api.colpero.com/api/v1/domains/nearby?lat=37.77&lng=-122.41&radius_m=5000

In development mode, set API_KEYS=dev-key in your environment. The server accepts any key listed in the comma-separated API_KEYS env var.

Rate limiting

Default limit: 100 requests per minute per API key. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

Configure via the RATE_LIMIT_RPM environment variable.

Payments (x402)

Some endpoints require payment. The flow uses the x402 protocol:

  1. Client sends a request without payment.
  2. Server returns 402 Payment Required with pricing metadata in the response body.
  3. Client signs a USDC payment and retries with the X-Payment-Receipt header containing the signed receipt.
  4. Server verifies the receipt and returns the data.
POST /api/v1/domains/1/path
X-API-Key: your-api-key
X-Payment-Receipt: <signed-usdc-receipt>

{"start_lat": 37.77, "start_lng": -122.42, "end_lat": 37.78, "end_lng": -122.41}

ā†’ {"waypoints": [...], "distance_m": 142.5}

No tokens, no accounts, no onboarding. Stateless HTTP-native payments. Protocol by Coinbase.

System

GET/health
Auth: NoPayment: No

Health check. Returns 200 if the node is running.

Domains

POST/api/v1/domains/
Auth: YesPayment: No

Create a new spatial domain with coordinates, mesh, and model references.

Request body
{
  "name": "SF Financial District",
  "description": "Dense urban block",
  "lat": 37.7749,
  "lng": -122.4194
}
Response
{
  "id": 1,
  "name": "SF Financial District",
  "lat": 37.7749,
  "lng": -122.4194,
  "created_at": "2026-04-08T00:00:00Z"
}
GET/api/v1/domains/nearby
Auth: YesPayment: No

Find spatial domains within a radius of a coordinate.

Query parameters
?lat=37.77&lng=-122.41&radius_m=5000
Response
[
  {
    "id": 1,
    "name": "SF Financial District",
    "lat": 37.7749,
    "lng": -122.4194,
    "distance_m": 320.5
  }
]
GET/api/v1/domains/{id}
Auth: YesPayment: No

Get full domain details including mesh and model paths.

POST/api/v1/domains/{id}/path
Auth: YesPayment: Yes

Compute a navigable path between two coordinates within a domain.

Request body
{
  "start_lat": 37.77,
  "start_lng": -122.42,
  "end_lat": 37.78,
  "end_lng": -122.41
}
Response
{
  "waypoints": [[37.77, -122.42], [37.775, -122.415], [37.78, -122.41]],
  "distance_m": 142.5
}
GET/api/v1/domains/{id}/partitions
Auth: YesPayment: Yes

List spatial partitions (semantic regions) within a domain.

Providers

POST/api/v1/providers/
Auth: YesPayment: No

Register a new spatial provider with capabilities and endpoint.

Request body
{
  "name": "ScanBot-SF",
  "endpoint_url": "https://scanbot.example.com",
  "provider_type": "reconstruction",
  "capabilities": {"colmap": true, "gaussian_splatting": true}
}
Response
{
  "token_id": 1,
  "name": "ScanBot-SF",
  "endpoint_url": "https://scanbot.example.com",
  "provider_type": "reconstruction",
  "capabilities": ["colmap", "gaussian_splatting"]
}
GET/api/v1/providers/
Auth: YesPayment: No

List all registered spatial providers.

POST/api/v1/providers/{id}/request
Auth: YesPayment: No

Route a spatial data request to a specific provider.

PATCH/api/v1/providers/{id}/reputation
Auth: YesPayment: No

Update a provider's reputation score after a transaction.

SDK

# Install
npm install colpero-sdk
# Usage
import { ColperoClient } from "colpero-sdk";

const client = new ColperoClient({
  baseUrl: "https://api.colpero.com",
  apiKey: "your-api-key",
});

// Find nearby domains
const domains = await client.domains.nearby(37.77, -122.41, 5000);

// Compute a path (payment handled by SDK)
const path = await client.domains.computePath(1, {
  start: [37.77, -122.42],
  end: [37.78, -122.41],
});

console.log(path.waypoints, path.distance_m);