Bield sits alongside the tools you already use — timing, entry, club software — and adds the race-day and community layer. Our data is built to be shared cleanly, so three audiences can build on it: aggregators & directories (the open feed), timing & entry partners (keep your events in sync, get change webhooks), and coach & performance tools (read a runner's results and training summary, only ever with their consent).
The open race feed is live now. The partner APIs are available to approved partners under a data-processing agreement — they exist and are documented here so you know exactly what you'd be building against before you get in touch.
Access level 01 · open
Public race feed
For aggregators, directories, and AI assistants · no account, no key
A stable, paginated feed of every race Bield indexes — over 1,800 endurance events, half-marathon distance and up. It's the canonical source cited in our llms.txt, meant to be read by machines. Facts only: no runner data, no personal information.
- Format — JSON by default, or
?format=schemafor JSON-LD (schema.orgEvent) you can drop straight into a rich-results pipeline. - Paging — 100 races per page via
?page=. - Fresh & cached — CDN-cached, safe to poll politely.
- Only published, public races are ever returned.
GET/api/races/public.json?page=1
{
"meta": {
"total": 1811, "page": 1,
"page_size": 100, "pages": 19
},
"races": [{
"name": "West Highland Way Race",
"date": "2026-06-20",
"distance_km": 161,
"country": "GB",
"location": "Fort William",
"terrain": "trail",
"entry_status": "open",
"pacers_allowed": true,
"url": "https://app.bield.run/race/…"
}]
}
Access level 02 · partner
Race sync
For timing & entry platforms · server-to-server, one API key
Keep the races you run in step with Bield from your own system. Create or update a race, list what you've synced, and get a signed webhook whenever a race's key facts change on our side — so the two never drift.
- Auth — one bearer key (
bield_prs_…). No token dance, no expiry; rotate if it ever leaks. - Idempotent — upserts key on your reference, so a retry never double-creates.
- Yours only — a key can only touch the races it owns.
- Signed webhooks — HMAC-SHA256, with a delivery id and timestamp so you can reject replays.
- Fair use — generous per-minute limits, clearly returned.
POST/functions/v1/partner-race-sync
Authorization: Bearer bield_prs_…
{
"action": "upsert_race",
"input": {
"external_ref": "YOURSYS-12345",
"name": "Glen Coe Skyline",
"date": "2026-08-15",
"distance_km": 52,
"entry_status": "open"
}
}
// → 200
{ "ok": true, "race_id": "rc_…",
"sync_status": "synced" }
Access level 03 · consent
Runner data — with consent
For coach, performance & federation tools · OAuth 2.0, the runner authorises
Read a runner's data only after they tap "Allow" in the Bield app — the standard OAuth 2.0 authorization-code flow with PKCE. You get back exactly the fields inside the scopes they granted, and nothing else. Revoke is instant: if a runner withdraws consent, they disappear from your next call.
- Scoped — request only what you need; the runner sees each scope in plain English before agreeing.
- Honest by construction — a field the runner didn't share is simply absent; we never invent a value.
- Auditable — every grant is logged; a withdrawal fires a deletion signal you're expected to honour within 30 days.
Approved partners register a client, are admin-reviewed, and sign a data-processing agreement before a single token can be minted.
Scopes & the exact fields they share
| Scope | Fields returned |
|---|---|
profile_basic | handle, first name, surname, country |
race_results | race, finish time, position, distance |
training_summary | weekly volume, recent average pace (no raw GPS) |
performance_index | performance index, calibration confidence |
health ▲ | medical notes, conditions |
emergency_contact ▲ | next-of-kin name & phone |
▲ Special-category data — requires a separate, explicit consent tap.
Across every endpoint
Formats & conventions
One set of rules everywhere, so there are no surprises between lanes.
JSON
UTF-8 JSON, snake_case keys. Requests and responses both. JSON-LD available on the open feed.
Dates
ISO-8601. Race dates as YYYY-MM-DD; timestamps in UTC with a Z.
Units
Distances in kilometres (distance_km). Entry prices in GBP.
Auth
Open feed: none. Race sync: a bearer API key. Runner data: OAuth 2.0 + PKCE bearer tokens.
Errors
Conventional HTTP status codes with a small JSON body — { "error": "…" }. Nothing sensitive is ever echoed back.
Rate limits
Per-key sliding window, returned on the response. Back off on 429 and retry.
Transport
HTTPS only. Secrets are shown once at creation and stored only as hashes — rotate, never recover.
Versioning
Additive by default. Breaking changes ship under a new path; we won't pull data out from under you.
Data protection
UK GDPR throughout. Partner lanes run under a signed DPA; consent is logged and revocable.
Building something with race data?
Start with the open feed right now. When you're ready for race sync or consent-based runner data, tell us what you're building and we'll set you up — approval and a short data-processing agreement, then keys.
Get in touch about API access →hello@bield.run · we read every one, usually same day