{ "openapi": "3.1.1", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "RunCouriers public web API", "version": "0.1.0-prelaunch", "summary": "Current public web contracts for tracking, consent-based enquiry, and anonymous readiness.", "description": "Unversioned, pre-launch HTTP API for Run Couriers, LLC. This document covers the three public web operations only; it is not a complete specification of permission-protected internal dispatch APIs. The business is in validation. An enquiry is not a booking, quote, payment, or contract. Examples are synthetic.", "termsOfService": "https://runcouriers.com/terms", "contact": { "name": "Privacy and reported site concerns", "email": "Privacy@RunCouriers.com", "url": "https://runcouriers.com/contact" } }, "servers": [ { "url": "https://runcouriers.com", "description": "Configured canonical site; consult the current deployment health before submitting an enquiry." } ], "security": [], "tags": [ { "name": "Public web", "description": "Anonymous website operations; no public credential provisioning." } ], "externalDocs": { "description": "Human-readable public interface documentation", "url": "https://runcouriers.com/developers" }, "x-last-reviewed": "2026-10-11", "x-document-scope": "public-web-only", "paths": { "/api/track": { "get": { "operationId": "trackShipment", "tags": [ "Public web" ], "summary": "Look up a shipment using a reference already known to the requester.", "description": "The reference is trimmed and uppercased. Malformed, unknown, draft and unaccepted quoted references have the same generic 404 body. The result contains no cargo, driver, vehicle, seal, rate, shipper, or contact details. Demonstration records are explicitly labelled. Do not enumerate references.", "x-rate-limit": { "requests": 10, "windowSeconds": 600, "scope": "client" }, "parameters": [ { "name": "ref", "in": "query", "required": true, "description": "Known waybill reference. Missing or whitespace-only input returns 400; malformed or unknown input returns generic 404.", "schema": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[A-Za-z0-9-]+$" } } ], "responses": { "200": { "description": "Minimal public shipment state. A demonstration flag does not establish real operating activity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingResult" } } } }, "400": { "description": "A waybill reference is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Malformed or unknown waybill; no distinction is disclosed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingNotFound" } } } }, "429": { "description": "Per-client request limit reached. Wait for the Retry-After interval before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Delay in seconds.", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/inquiry": { "post": { "operationId": "submitInquiry", "tags": [ "Public web" ], "summary": "Record a consent-based route assessment enquiry.", "description": "The server checks the intake gate before accepting personal information. Required company, contact name, email, and origin strings are trimmed; field length limits apply to the supplied strings. Both consent flags must be exactly true. CONNECT is not accepted. requestId is optional client context and does not provide idempotency or duplicate suppression. Receiving a reference records an enquiry only.", "x-rate-limit": { "requests": 5, "windowSeconds": 600, "scope": "client" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InquiryRequest" }, "examples": { "synthetic": { "summary": "Synthetic shape example; do not submit it.", "value": { "requestId": "synthetic-documentation-example", "inquiry": { "service": "delivery", "company": "Example Manufacturer", "contactName": "Example Contact", "email": "contact@example.com", "origin": "Waterbury", "destination": "Hartford", "cargoCategory": "Packaged nonregulated parts", "details": "Synthetic example only; do not submit this sample.", "consentContact": true, "consentTerms": true } } } } } } }, "responses": { "200": { "description": "Enquiry stored with a reference and pending-review status. No movement has been accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InquiryReceipt" } } } }, "400": { "description": "Request body is not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Payload, required fields, field limits, service, email/phone, or affirmative consent validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Per-client request limit reached. Wait for the Retry-After interval before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Delay in seconds.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The server could not confirm recording the request. No success receipt is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Online intake is disabled or unavailable; the request is not accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeUnavailable" } } } } } } }, "/api/health": { "get": { "operationId": "getPublicHealth", "tags": [ "Public web" ], "summary": "Read anonymous site readiness and maintenance status.", "description": "Anonymous responses share the same readiness decision as operator responses but omit record counts, database integrity diagnostics, paths, and credentials. schemaVersion is the observed version (expected 3), or null if unavailable. checks.intakeOpen reports the environment switch; it is not sufficient by itself. Show enquiry intake only after HTTP 200 plus readiness.ready and readiness.intake are true.", "responses": { "200": { "description": "Deployment ready. Optional maintenance may report degraded status when it is not a readiness requirement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicHealth" } } } }, "503": { "description": "Deployment not ready. Inspect public readiness flags; do not solicit personal information through an unavailable form.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicHealth" } } } } } } } }, "components": { "schemas": { "ApiError": { "type": "object", "additionalProperties": false, "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } }, "TrackingNotFound": { "type": "object", "additionalProperties": false, "required": [ "ok", "found" ], "properties": { "ok": { "type": "boolean", "const": false }, "found": { "type": "boolean", "const": false } } }, "TrackingResult": { "type": "object", "additionalProperties": false, "required": [ "ok", "found", "waybill", "status", "route", "lastUpdated", "deliveredAt", "demonstration" ], "properties": { "ok": { "type": "boolean", "const": true }, "found": { "type": "boolean", "const": true }, "waybill": { "type": "string" }, "status": { "type": "string" }, "route": { "type": "string" }, "lastUpdated": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "demonstration": { "type": "boolean" } } }, "InquiryRequest": { "type": "object", "required": [ "inquiry" ], "properties": { "requestId": { "type": "string", "description": "Optional client context; not an idempotency key." }, "inquiry": { "type": "object", "required": [ "service", "company", "contactName", "email", "origin", "consentContact", "consentTerms" ], "properties": { "service": { "type": "string", "enum": [ "delivery", "route" ] }, "company": { "type": "string", "minLength": 1, "pattern": "\\S", "maxLength": 150 }, "contactName": { "type": "string", "minLength": 1, "pattern": "\\S", "maxLength": 120 }, "email": { "type": "string", "maxLength": 254, "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$" }, "phone": { "type": "string", "maxLength": 40, "pattern": "^$|^[0-9+()\\-.\\s]{7,}$" }, "origin": { "type": "string", "minLength": 1, "pattern": "\\S", "maxLength": 160 }, "destination": { "type": "string", "maxLength": 160 }, "frequency": { "type": "string", "maxLength": 120 }, "cargoCategory": { "type": "string", "maxLength": 120 }, "specialHandling": { "type": "string", "maxLength": 200 }, "details": { "type": "string", "maxLength": 4000 }, "consentContact": { "type": "boolean", "const": true }, "consentTerms": { "type": "boolean", "const": true } } } } }, "InquiryReceipt": { "type": "object", "additionalProperties": false, "required": [ "ok", "reference", "status", "message", "retentionNotice" ], "properties": { "ok": { "type": "boolean", "const": true }, "reference": { "type": "string" }, "status": { "type": "string", "const": "pending_review" }, "message": { "type": "string" }, "retentionNotice": { "type": "string" } } }, "IntakeUnavailable": { "type": "object", "additionalProperties": false, "required": [ "ok", "intakeOpen", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "intakeOpen": { "type": "boolean", "const": false }, "error": { "type": "string" } } }, "PublicHealth": { "type": "object", "additionalProperties": false, "required": [ "status", "database", "schemaVersion", "readiness", "checks", "maintenance", "responseMs" ], "properties": { "status": { "type": "string", "enum": [ "ok", "degraded", "unhealthy" ] }, "database": { "type": "string", "enum": [ "reachable", "unreachable" ] }, "schemaVersion": { "type": [ "integer", "null" ], "minimum": 0, "description": "Observed schema version; expected current version is 3." }, "readiness": { "type": "object", "additionalProperties": false, "required": [ "ready", "configuration", "database", "intake", "retention", "maintenance" ], "properties": { "ready": { "type": "boolean" }, "configuration": { "type": "boolean" }, "database": { "type": "boolean" }, "intake": { "type": "boolean" }, "retention": { "type": "boolean" }, "maintenance": { "type": "boolean" } } }, "checks": { "type": "object", "additionalProperties": false, "required": [ "retentionJobOverdue", "intakeOpen", "maintenanceRequired" ], "properties": { "retentionJobOverdue": { "type": "boolean" }, "intakeOpen": { "type": "boolean" }, "maintenanceRequired": { "type": "boolean" } } }, "maintenance": { "type": "object", "additionalProperties": false, "required": [ "status", "scheduler", "backup", "purge" ], "properties": { "status": { "type": "string", "enum": [ "starting", "ok", "degraded" ] }, "scheduler": { "type": "object", "additionalProperties": false, "required": [ "status", "lastSuccessAt" ], "properties": { "status": { "type": "string", "enum": [ "starting", "running", "success", "failure", "stopped", "stale", "missing", "invalid" ] }, "lastSuccessAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "backup": { "type": "object", "additionalProperties": false, "required": [ "status", "lastRunAt", "lastSuccessAt" ], "properties": { "status": { "type": "string", "enum": [ "success", "failure", "stale", "missing", "invalid" ] }, "lastRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastSuccessAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "purge": { "type": "object", "additionalProperties": false, "required": [ "status", "lastRunAt", "lastSuccessAt" ], "properties": { "status": { "type": "string", "enum": [ "success", "failure", "stale", "missing", "invalid" ] }, "lastRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastSuccessAt": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "responseMs": { "type": "integer", "minimum": 0 } } } } } }