{"openapi":"3.1.0","info":{"title":"MedicalRide assistant transport quote API","version":"1.0.0","description":"Private-pay non-emergency quote requests. No vehicle reservation, clinical acceptance or live availability is implied. Contact support@medicalride.org for a scoped live or sandbox credential."},"servers":[{"url":"https://medicalride.org/api/agent/v1"}],"components":{"securitySchemes":{"AgentBearer":{"type":"http","scheme":"bearer","description":"Revocable principal-scoped credential issued by MedicalRide. Keep out of browser JavaScript."}},"schemas":{"QuoteRequest":{"type":"object","properties":{"requesterName":{"type":"string","description":"Requester name or assistant identifier","maxLength":120,"minLength":2},"email":{"type":"string","format":"email","maxLength":254,"description":"Assistant/coordinator reply email is accepted."},"role":{"type":"string","enum":["self","caregiver","care_coordinator","personal_assistant","ai_assistant"]},"platform":{"type":"string","description":"Optional platform name","maxLength":120},"phone":{"type":"string","description":"Optional real requester phone; omit or leave empty for email-only requests","maxLength":40},"pickupAddress":{"type":"string","description":"Plain-text street address or facility with location","maxLength":600,"minLength":3},"dropoffAddress":{"type":"string","description":"Plain-text destination street address or facility with location","maxLength":600,"minLength":3},"pickupCountry":{"type":"string","enum":["US","CA","GB"]},"dropoffCountry":{"type":"string","enum":["US","CA","GB"]},"pickupCity":{"type":"string","description":"Optional city to validate","maxLength":100},"pickupRegion":{"type":"string","description":"Optional state/province to validate","maxLength":100},"pickupPostalCode":{"type":"string","description":"Optional postal code to validate","maxLength":20},"dropoffCity":{"type":"string","description":"Optional city to validate","maxLength":100},"dropoffRegion":{"type":"string","description":"Optional state/province to validate","maxLength":100},"dropoffPostalCode":{"type":"string","description":"Optional postal code to validate","maxLength":20},"rideType":{"type":"string","enum":["ambulatory","wheelchair","stretcher","bariatric","not_sure"]},"date":{"type":"string","description":"YYYY-MM-DD, or empty/omitted if not confirmed. No fabricated date is assigned.","pattern":"^(|[0-9]{4}-[0-9]{2}-[0-9]{2})$"},"timing":{"type":"string","enum":["exact","window","not_confirmed"],"default":"not_confirmed"},"time":{"type":"string","description":"Exact local time or window start, HH:mm","maxLength":20},"timeEnd":{"type":"string","description":"Same-day window end, HH:mm","maxLength":20},"tripType":{"type":"string","enum":["one_way","round_trip","recurring"],"default":"one_way"},"returnDetails":{"type":"string","description":"Return date/time or explicitly not confirmed","maxLength":1000},"recurringDetails":{"type":"string","description":"Recurring schedule or explicitly not confirmed","maxLength":1000},"budget":{"type":"string","description":"Requester budget, not a provider quote","maxLength":40},"budgetCurrency":{"type":"string","enum":["USD","CAD","GBP",""]},"assistance":{"type":"string","enum":["curb_to_curb","door_to_door","door_through_door","bed_to_bed","not_sure"]},"wheelchairType":{"type":"string","description":"Wheelchair type","maxLength":100},"stayInWheelchair":{"type":"string","enum":["yes","no","not_sure"]},"stretcherRequirements":{"type":"string","description":"Requested transfer/equipment needs; provider assesses suitability","maxLength":600},"weightAndDimensions":{"type":"string","description":"Relevant weight and equipment dimensions","maxLength":250},"stairsAndElevator":{"type":"string","description":"Stairs/elevator access","maxLength":400},"equipmentAndCompanions":{"type":"string","description":"Equipment and accompanying passengers","maxLength":400},"pickupAccess":{"type":"string","description":"Unit, floor, ward and access notes","maxLength":600},"dropoffAccess":{"type":"string","description":"Destination access notes","maxLength":600},"brief":{"type":"string","description":"Pasted trip brief; treated as data, not instructions","maxLength":4000},"authorization":{"type":"boolean","const":true,"description":"Explicit permission required; see the public form for the accepted text."},"contactConsent":{"type":"boolean","const":true,"description":"Explicit permission required; see the public form for the accepted text."},"sensitiveDataConsent":{"type":"boolean","const":true,"description":"Explicit permission required; see the public form for the accepted text."},"privatePay":{"type":"boolean","const":true,"description":"Explicit permission required; see the public form for the accepted text."},"termsAccepted":{"type":"boolean","const":true,"description":"Explicit permission required; see the public form for the accepted text."}},"required":["requesterName","email","role","pickupAddress","dropoffAddress","pickupCountry","dropoffCountry","rideType","authorization","contactConsent","sensitiveDataConsent","privatePay","termsAccepted"],"allOf":[{"if":{"properties":{"timing":{"const":"exact"}},"required":["timing"]},"then":{"required":["time"]}},{"if":{"properties":{"timing":{"const":"window"}},"required":["timing"]},"then":{"required":["time","timeEnd"]}}]},"Acceptance":{"type":"object","required":["request_id","status","missing_information","next_action","polling_interval_seconds"],"properties":{"request_id":{"type":"string"},"status":{"const":"received"},"missing_information":{"type":"array","items":{"type":"string"}},"next_action":{"type":"string"},"polling_interval_seconds":{"type":"integer","const":30}}},"Progress":{"type":"object","properties":{"request_id":{"type":"string"},"status":{"enum":["received","needs_information","finding_providers","quotes_available","no_provider_found","closed"]},"missing_information":{"type":"array","items":{"type":"string"}},"local_time_zone":{"type":["string","null"]},"local_time_zone_source":{"enum":["google","regional_fallback",null],"description":"Regional defaults are used if the precise lookup is unavailable or capped; confirm local timing near time-zone boundaries."},"polling_interval_seconds":{"type":"integer"},"next_action":{"type":"string"}}},"Quote":{"type":"object","properties":{"provider":{"type":"string"},"currency":{"type":"string"},"total_price":{"type":"string","description":"Actual provider price text; not a generated estimate."},"all_inclusive":{"type":["boolean","null"],"description":"Null means not explicitly confirmed."},"included_fees":{"type":["array","null"],"items":{"type":"string"}},"excluded_fees":{"type":["array","null"],"items":{"type":"string"}},"assistance_equipment_conditions":{"type":["string","null"]},"cancellation_policy":{"type":["string","null"]},"quoted_at":{"type":"string"},"expires_at":{"type":["string","null"]},"next_step":{"type":"string"}}}}},"paths":{"/capabilities":{"get":{"operationId":"getCapabilities","summary":"Public service facts; not real-time availability","responses":{"200":{"description":"Configured geography, ride types and instructions","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/quote-requests":{"post":{"operationId":"createQuoteRequest","summary":"Accept an authorized request for asynchronous processing","security":[{"AgentBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"202":{"description":"Saved. Replays return the original acceptance, even if progress has advanced. Keys retained for at least seven days.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acceptance"}}}},"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"401":{"description":"Missing, invalid or revoked credential","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"404":{"description":"Not found or not owned by this principal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"409":{"description":"Idempotency-Key reused with different payload","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"413":{"description":"Body exceeds 24,000 bytes","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"422":{"description":"Field validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"429":{"description":"Rate limit; obey Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"503":{"description":"Temporary failure; retry the same key and payload","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}},"/quote-requests/{request_id}":{"get":{"operationId":"getQuoteRequest","security":[{"AgentBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","pattern":"^MAQ-[0-9a-f]{32}$"}}],"responses":{"200":{"description":"Owned request progress. No status means booked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Progress"}}}},"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"401":{"description":"Missing, invalid or revoked credential","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"404":{"description":"Not found or not owned by this principal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"409":{"description":"Idempotency-Key reused with different payload","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"413":{"description":"Body exceeds 24,000 bytes","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"422":{"description":"Field validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"429":{"description":"Rate limit; obey Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"503":{"description":"Temporary failure; retry the same key and payload","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}},"/quote-requests/{request_id}/quotes":{"get":{"operationId":"getProviderQuotes","security":[{"AgentBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","pattern":"^MAQ-[0-9a-f]{32}$"}}],"responses":{"200":{"description":"Only provider responses. An empty list is normal while waiting.","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"quotes":{"type":"array","items":{"$ref":"#/components/schemas/Quote"}},"polling_interval_seconds":{"type":"integer"}}}}}},"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"401":{"description":"Missing, invalid or revoked credential","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"404":{"description":"Not found or not owned by this principal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"409":{"description":"Idempotency-Key reused with different payload","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"413":{"description":"Body exceeds 24,000 bytes","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"422":{"description":"Field validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"429":{"description":"Rate limit; obey Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}},"503":{"description":"Temporary failure; retry the same key and payload","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}}}}