Spec → REST binding
/.well-known/uklsp.json on every conformant host.Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /v0/discover?service=&postcode_district= | Ranked providers with quotes for a service in a district. Full postcodes are normalised to districts. |
| GET | /v0/providers/{provider_id} | The full Provider manifest. |
| GET | /v0/providers/{provider_id}/slots?service= | Open AvailabilitySlots (booked and expired-hold slots are never returned). |
| POST | /v0/bookings | BookingRequest in, BookingConfirmation out. 201 on success. |
Canonical error codes
| HTTP | code | Meaning |
|---|---|---|
| 400 | BAD_QUERY / BAD_JSON | Malformed request. |
| 403 | DEMO_PROVIDER | Fictional listing — quoting allowed, booking forbidden. |
| 404 | UNKNOWN_PROVIDER / UNKNOWN_SLOT | Id not found. |
| 409 | SLOT_TAKEN / PRICE_MISMATCH | Re-fetch slots / re-read published price. |
| 422 | HUMAN_PRINCIPAL_REQUIRED, OUT_OF_COVERAGE, SERVICE_NOT_OFFERED, MISSING_FIELD | Valid JSON, invalid booking. |
Retail-protocol bridge (informative)
A UKLSP flow maps cleanly onto retail agent-checkout shapes: discover results play the role of a product offer (price, seller, fulfilment constraint = coverage + slot), and POST /v0/bookings plays checkout, returning a confirmation with a binding price and cancellation policy. Operators bridging into retail-style protocols SHOULD treat the UKLSP manifest as the source of truth and generate the retail-shaped offer from it — never the reverse. This keeps the local-services layer protocol-agnostic while remaining pluggable into whichever agent surfaces win.
Conformance
The reference implementation ships with a conformance suite covering discovery, normalisation, the demo fence, the human-principal rule, coverage rejection, price integrity, idempotency and slot removal. Passing it is required for Level 3 certification of an independent implementation.