{"openapi":"3.1.0","info":{"title":"TrailSync Connector API","version":"1.0.0-gateA","description":"Public, read-only overland trip-planning actions: plan a route, scan it for wildfire/air/weather, and search campsites. Every response carries an evidence envelope (source, observation time, freshness, confidence). Gate A of the connector; account-linked telemetry, trip save, and Pro checkout arrive in later gates."},"servers":[{"url":"https://www.mytrailsync.com/api/v1"}],"paths":{"/routes":{"post":{"operationId":"plan_route","summary":"Plan a driving route between two points.","x-connector":{"action":"plan_route","scope":"public","approval":"none"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["origin","destination"],"properties":{"origin":{"oneOf":[{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[lng, lat] (GeoJSON order)"},{"type":"string","description":"A place name to geocode, e.g. \"Bishop, CA\""}]},"destination":{"oneOf":[{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[lng, lat] (GeoJSON order)"},{"type":"string","description":"A place name to geocode, e.g. \"Bishop, CA\""}]},"vias":{"type":"array","items":{"oneOf":[{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[lng, lat] (GeoJSON order)"},{"type":"string","description":"A place name to geocode, e.g. \"Bishop, CA\""}]},"maxItems":10},"dates":{"type":"object","properties":{"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"}}},"rig":{"type":"object","description":"Accepted; does not yet alter routing."},"preferences":{"type":"object","description":"Accepted; does not yet alter routing."}}}}}},"responses":{"200":{"description":"Route plan.","content":{"application/json":{"schema":{"type":"object","required":["request_id","generated_at","expires_at","data","sources","warnings","next_actions"],"properties":{"request_id":{"type":"string","description":"Trace id for support."},"generated_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time","description":"When volatile results go stale; null if stable."},"data":{"type":"object"},"sources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"observed_at":{"type":["string","null"]}},"required":["name"]}},"warnings":{"type":"array","items":{"type":"string"}},"next_actions":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","required":["request_id","generated_at","error"],"properties":{"request_id":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","SOURCE_UNAVAILABLE","RATE_LIMITED","NOT_FOUND","AUTH_REQUIRED","METHOD_NOT_ALLOWED","UPSTREAM_ERROR"]},"message":{"type":"string"}}}}}}}},"503":{"description":"Routing provider unavailable.","content":{"application/json":{"schema":{"type":"object","required":["request_id","generated_at","error"],"properties":{"request_id":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","SOURCE_UNAVAILABLE","RATE_LIMITED","NOT_FOUND","AUTH_REQUIRED","METHOD_NOT_ALLOWED","UPSTREAM_ERROR"]},"message":{"type":"string"}}}}}}}}}}},"/risk-scan":{"post":{"operationId":"scan_route_risks","summary":"Scan a route corridor for wildfire, air quality, and weather.","description":"A missing reading is reported as unknown, never as safe.","x-connector":{"action":"scan_route_risks","scope":"public","approval":"none"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Supply one of: route, route_id, or from + to.","properties":{"route":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}},"route_id":{"type":"string","description":"From a prior plan_route call (cache is best-effort)."},"from":{"oneOf":[{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[lng, lat] (GeoJSON order)"},{"type":"string","description":"A place name to geocode, e.g. \"Bishop, CA\""}]},"to":{"oneOf":[{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[lng, lat] (GeoJSON order)"},{"type":"string","description":"A place name to geocode, e.g. \"Bishop, CA\""}]},"corridor_mi":{"type":"number","minimum":5,"maximum":100,"default":30},"departure_window":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}}}}}}},"responses":{"200":{"description":"Per-condition risk read with evidence.","content":{"application/json":{"schema":{"type":"object","required":["request_id","generated_at","expires_at","data","sources","warnings","next_actions"],"properties":{"request_id":{"type":"string","description":"Trace id for support."},"generated_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time","description":"When volatile results go stale; null if stable."},"data":{"type":"object"},"sources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"observed_at":{"type":["string","null"]}},"required":["name"]}},"warnings":{"type":"array","items":{"type":"string"}},"next_actions":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","required":["request_id","generated_at","error"],"properties":{"request_id":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","SOURCE_UNAVAILABLE","RATE_LIMITED","NOT_FOUND","AUTH_REQUIRED","METHOD_NOT_ALLOWED","UPSTREAM_ERROR"]},"message":{"type":"string"}}}}}}}},"404":{"description":"route_id not in cache.","content":{"application/json":{"schema":{"type":"object","required":["request_id","generated_at","error"],"properties":{"request_id":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","SOURCE_UNAVAILABLE","RATE_LIMITED","NOT_FOUND","AUTH_REQUIRED","METHOD_NOT_ALLOWED","UPSTREAM_ERROR"]},"message":{"type":"string"}}}}}}}}}}},"/campsites":{"get":{"operationId":"search_campsites","summary":"Search campsites near a point or along a planned route.","x-connector":{"action":"search_campsites","scope":"public","approval":"none"},"parameters":[{"name":"lat","in":"query","schema":{"type":"number"},"description":"Point mode: latitude."},{"name":"lng","in":"query","schema":{"type":"number"},"description":"Point mode: longitude."},{"name":"radius_km","in":"query","schema":{"type":"number","minimum":5,"maximum":250,"default":80}},{"name":"from","in":"query","schema":{"type":"string"},"description":"Route mode: origin place name (with `to`)."},{"name":"to","in":"query","schema":{"type":"string"},"description":"Route mode: destination place name (with `from`)."},{"name":"route_id","in":"query","schema":{"type":"string"},"description":"Route mode: id from plan_route (session-scoped; prefer from+to)."},{"name":"corridor_km","in":"query","schema":{"type":"number","minimum":5,"maximum":80,"default":30}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string","enum":["all","osm","community"]}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"min_rig_length_ft","in":"query","schema":{"type":"number"}},{"name":"limit","in":"query","schema":{"type":"number","minimum":1,"maximum":200,"default":100}}],"responses":{"200":{"description":"Ranked campsites with source, confirmation, and confidence.","content":{"application/json":{"schema":{"type":"object","required":["request_id","generated_at","expires_at","data","sources","warnings","next_actions"],"properties":{"request_id":{"type":"string","description":"Trace id for support."},"generated_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time","description":"When volatile results go stale; null if stable."},"data":{"type":"object"},"sources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"observed_at":{"type":["string","null"]}},"required":["name"]}},"warnings":{"type":"array","items":{"type":"string"}},"next_actions":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","required":["request_id","generated_at","error"],"properties":{"request_id":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","SOURCE_UNAVAILABLE","RATE_LIMITED","NOT_FOUND","AUTH_REQUIRED","METHOD_NOT_ALLOWED","UPSTREAM_ERROR"]},"message":{"type":"string"}}}}}}}},"404":{"description":"route_id not in cache.","content":{"application/json":{"schema":{"type":"object","required":["request_id","generated_at","error"],"properties":{"request_id":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","SOURCE_UNAVAILABLE","RATE_LIMITED","NOT_FOUND","AUTH_REQUIRED","METHOD_NOT_ALLOWED","UPSTREAM_ERROR"]},"message":{"type":"string"}}}}}}}}}}}},"components":{"schemas":{"Envelope":{"type":"object","required":["request_id","generated_at","expires_at","data","sources","warnings","next_actions"],"properties":{"request_id":{"type":"string","description":"Trace id for support."},"generated_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time","description":"When volatile results go stale; null if stable."},"data":{"type":"object"},"sources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"observed_at":{"type":["string","null"]}},"required":["name"]}},"warnings":{"type":"array","items":{"type":"string"}},"next_actions":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","required":["request_id","generated_at","error"],"properties":{"request_id":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","SOURCE_UNAVAILABLE","RATE_LIMITED","NOT_FOUND","AUTH_REQUIRED","METHOD_NOT_ALLOWED","UPSTREAM_ERROR"]},"message":{"type":"string"}}}}}}},"x-connector-gates":{"A":"Public value (this manifest): plan_route, scan_route_risks, search_campsites.","B":"Linked value: OAuth 2.0 / OIDC, get_rig_telemetry, save_trip.","C":"Pro conversion: start_pro_trial, create_pro_checkout via Stripe Link.","D":"RREV commerce: model/spec lookup, configuration, governed deposit."}}