Public interfaces

Public web API and discovery

These are the public HTTP interfaces used by the RunCouriers website. The API is unversioned and pre-launch. This documentation covers tracking, enquiry submission, and anonymous health; it does not publish internal dispatch operations as integrator access.

Read OpenAPI 3.1

Tracking a known reference

GET /api/track?ref=YOUR-KNOWN-REFERENCE

Supply a waybill reference you already have. References are trimmed and uppercased; do not enumerate them. The response is limited to the waybill, public status, route towns, last update, nullable delivery time, and a demonstration flag.

Missing references return 400. Malformed and unknown references share a generic 404. The per-client limit is 10 lookups per ten minutes; 429 includes a Retry-After delay in seconds. Demonstration records are not evidence of commercial transport activity.

Submitting an assessment enquiry

POST /api/inquiry

Send application/json with an inquiry object. It requires service (delivery or route), company, contactName, email, origin, consentContact: true, and consentTerms: true. Optional fields and their length limits are in OpenAPI. The two consent flags must reflect the person's affirmative choices. CONNECT is not accepted.

Check health before collecting or sending personal information. The server gate can refuse intake with 503. Invalid JSON returns 400, validation failures 422, and the per-client limit of 5 requests per ten minutes returns 429 with Retry-After. A recording failure returns 500 without a success receipt.

A successful response supplies an enquiry reference and pending_review status, not a booking or quote. Optional requestId is not an idempotency key. Avoid automatic resubmission after an uncertain connection failure; an enquiry may already have been stored even if its receipt was not delivered to the browser.

Readiness and intake state

GET /api/health

Health returns 200 when ready, or 503 when not ready. Anonymous output includes status, database reachability, observed schema version (current version 3), readiness flags, intake and retention checks, maintenance summaries, and response time. It excludes operational record counts and privileged diagnostics.

checks.intakeOpen reports the deployment switch. Require HTTP 200, that switch, and readiness.ready and readiness.intake before displaying an enquiry form. A failed or missing health response is unavailable, not permission to collect personal details.

Machine-readable public information

/site.jsonCanonical public profile, page registry, FAQ, planned models, and bounded provenance.
/site.jsonldJSON-LD for the same public entities and pages as the HTML site.
/index.mdReadable site summary and complete FAQ.
/llms.txtCurated content links following the llms.txt proposal.
/llms-full.txtExpanded public profile, FAQ, and proposed corridor catalogue.
/capabilities.jsonProject-convention public HTTP resources and gated actions.
/openapi.jsonOpenAPI 3.1 description of the three public web operations.
/schemas/capabilities.v1.jsonVersioned JSON Schema for capabilities.json.
/.well-known/security.txtRFC 9116 security-reporting contact and fixed expiry.

capabilities.json is a versioned project convention, validated by its published JSON Schema. It reports the environment intake switch, not live readiness. The implemented protocol is HTTP; MCP, WebMCP, OAuth, and A2A endpoints are not implemented. There is no public credential provisioning or API subscription programme.