Bike Lookup API

Authentication

Every request must include your API key as a Bearer token in the Authorization header. Create and manage keys from your dashboard.

Authorization: Bearer bdb_live_xxx

Lookup endpoint

Look up a single frame serial number. Matching is normalized, so case, spacing, and common look-alike characters are handled automatically.

GET /api/v1/bikes/lookup?serial=<serial>

Query parameters: serial (required) — the bike frame serial number to check.

Result statuses

• verified_stolenA verified stolen report matches this serial.
• reported_unverifiedAn unverified report matches this serial — treat with caution.
• no_reportNo active stolen report matches this serial.

Example: verified stolen

{
  "serial": "WTU123ABC",
  "status": "verified_stolen",
  "report": {
    "brand": "Trek",
    "model": "Marlin 7",
    "description": "Red Trek hardtail, black saddle",
    "theftDate": "2026-01-15",
    "theftCircumstances": "Lock cut outside the central market",
    "approximateLocation": { "lat": 20.6597, "lng": -103.3496 },
    "contactPhone": "+523312345678",
    "photoUrl": "https://.../bike.jpg",
    "verifiedAt": "2026-01-20T10:00:00.000Z"
  },
  "disclaimer": "This information comes from a user-submitted report in the registry."
}

Example: no report

{
  "serial": "WTU123ABC",
  "status": "no_report",
  "report": null,
  "disclaimer": "No active stolen report matches this serial. This does not guarantee the bike is not stolen."
}

Errors

• 400 — The serial parameter is missing or invalid.
• 401 — The API key is missing, invalid, or revoked.
• 429 — You have exceeded your rate limit; retry after the indicated time.

{ "error": { "code": "invalid_serial", "message": "…" } }

Rate limits

Requests are rate limited per key. Every response includes your current limit state in headers; a 429 response includes Retry-After.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1749470400
Retry-After: 42

Examples

cURL

curl -H "Authorization: Bearer bdb_live_xxx" \
  "https://your-domain.example/api/v1/bikes/lookup?serial=WTU123ABC"

JavaScript

const res = await fetch(
  "https://your-domain.example/api/v1/bikes/lookup?serial=WTU123ABC",
  { headers: { Authorization: `Bearer ${process.env.BIKE_DB_KEY}` } }
);
const data = await res.json();
if (data.status === "verified_stolen") {
  // bike is reported and verified stolen — handle accordingly
}