{"openapi":"3.1.0","info":{"title":"RouteSurvey API","version":"1.0.0","summary":"Check surveyed routes against a cargo, find their limits, and build reports and ebooks.","description":"The REST counterpart of the RouteSurvey MCP tools (docs 05 §8). JSON in and out; times in ISO 8601 (UTC); units SI (metres, tonnes, kilovolts); errors as RFC 9457 problem details; Idempotency-Key on every POST; cursor pagination on lists. Authenticate with an API key from /keys (Authorization: Bearer rsk_…) or an OAuth access token from this server. Results support, and do not replace, the route engineer's sign-off; every result names its rule set and version."},"servers":[{"url":"https://rs-mcp.survys.com"}],"tags":[{"name":"Checks","description":"Verdicts and limits"},{"name":"Surveys","description":"Your routes"},{"name":"Documents","description":"Reports, ebooks and links to them"},{"name":"Meta"}],"paths":{"/v1/openapi.json":{"get":{"tags":["Meta"],"summary":"This document","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/rule-sets":{"get":{"tags":["Checks"],"summary":"Rule sets a check may name with rule_set_id","security":[{"bearer":[]},{"oauth2":["surveys:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RuleSetSummary"}}}}}}},"400":{"description":"The request is not valid (errors[] lists each field)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, invalid or ended credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key or connection lacks a scope (required_scope says which), or the account has no access","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found, or not yours","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The input cannot be used, e.g. a GeoJSON without a track, or an Idempotency-Key reused with another body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit reached; Retry-After says when to try again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/checks":{"post":{"tags":["Checks"],"summary":"Check a route against a cargo","description":"Verdict (\"Blocked at km 12.98\", \"Passable after 4 measures\", \"Incomplete survey\", \"Clear to move\"), every point with its status, the gaps, and optionally a chat image stored as a document (format other than none needs documents:write).","security":[{"bearer":[]},{"oauth2":["surveys:read"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes a retry safe: the same key with the same body within 24 hours replays the first answer (header Idempotent-Replayed: true); a build is never started twice. Reusing a key with another body gives 422; while the first request is still running, 409.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"400":{"description":"The request is not valid (errors[] lists each field)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, invalid or ended credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key or connection lacks a scope (required_scope says which), or the account has no access","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found, or not yours","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"A request with this Idempotency-Key is still running","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The input cannot be used, e.g. a GeoJSON without a track, or an Idempotency-Key reused with another body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit reached; Retry-After says when to try again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/surveys":{"get":{"tags":["Surveys"],"summary":"List your routes","description":"Newest first, or searched by name (query), by project (project_id), or near a place (lat, lon, radius_km together). Near compares the ends of each route (its first and last survey point) and scans up to 200 recently updated routes; scan.complete says whether that covered all of them. Pass next_cursor as cursor for the next page; with a cursor the other filters come from it.","security":[{"bearer":[]},{"oauth2":["surveys:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"query","in":"query","schema":{"type":"string","maxLength":100}},{"name":"project_id","in":"query","schema":{"type":"integer","minimum":1}},{"name":"archived","in":"query","schema":{"type":"boolean","default":false}},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","oldest","updated","title","distance"],"default":"newest"}},{"name":"lat","in":"query","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lon","in":"query","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"radius_km","in":"query","schema":{"type":"number","minimum":0.1,"maximum":1000}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyList"}}}},"400":{"description":"The request is not valid (errors[] lists each field)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, invalid or ended credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key or connection lacks a scope (required_scope says which), or the account has no access","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found, or not yours","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The input cannot be used, e.g. a GeoJSON without a track, or an Idempotency-Key reused with another body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit reached; Retry-After says when to try again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/surveys/{id}":{"get":{"tags":["Surveys"],"summary":"A route as RouteSurvey export v2 GeoJSON","security":[{"bearer":[]},{"oauth2":["surveys:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Route id (GET /v1/surveys)","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Export v2 (schema: routesurvey://schema/export-v2)","content":{"application/geo+json":{"schema":{"$ref":"#/components/schemas/FeatureCollection"}}}},"400":{"description":"The request is not valid (errors[] lists each field)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, invalid or ended credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key or connection lacks a scope (required_scope says which), or the account has no access","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found, or not yours","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The input cannot be used, e.g. a GeoJSON without a track, or an Idempotency-Key reused with another body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit reached; Retry-After says when to try again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/surveys/{id}/envelope":{"get":{"tags":["Checks"],"summary":"Largest load the route takes, per dimension","security":[{"bearer":[]},{"oauth2":["surveys:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Route id (GET /v1/surveys)","schema":{"type":"integer","minimum":1}},{"name":"rule_set_id","in":"query","schema":{"type":"string"}},{"name":"vehicle_weight_t","in":"query","description":"Trailer and prime movers in tonnes, or text with a unit (\"132,000 lb\")","schema":{"type":"string"}},{"name":"use_planned_cargo","in":"query","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"The request is not valid (errors[] lists each field)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, invalid or ended credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key or connection lacks a scope (required_scope says which), or the account has no access","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found, or not yours","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The input cannot be used, e.g. a GeoJSON without a track, or an Idempotency-Key reused with another body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit reached; Retry-After says when to try again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/surveys/{id}/reports":{"post":{"tags":["Documents"],"summary":"Build a photo report PDF","description":"A4 PDF: overview page (map, numbered index) and one card per survey point with every photo; unreachable photos become labelled slots. Runs as a job: poll the Location until status is succeeded, then open outputs[].url.","security":[{"bearer":[]},{"oauth2":["surveys:read","documents:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Route id (GET /v1/surveys)","schema":{"type":"integer","minimum":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes a retry safe: the same key with the same body within 24 hours replays the first answer (header Idempotent-Replayed: true); a build is never started twice. Reusing a key with another body gives 422; while the first request is still running, 409.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildRequest"}}}},"responses":{"202":{"description":"Job accepted","headers":{"Location":{"schema":{"type":"string"},"description":"/v1/jobs/{id}"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"The request is not valid (errors[] lists each field)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, invalid or ended credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key or connection lacks a scope (required_scope says which), or the account has no access","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found, or not yours","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"A request with this Idempotency-Key is still running","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The input cannot be used, e.g. a GeoJSON without a track, or an Idempotency-Key reused with another body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit reached; Retry-After says when to try again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Documents need the hosted server (MCP_PUBLIC_URL)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/surveys/{id}/ebooks":{"post":{"tags":["Documents"],"summary":"Build the interactive PDF ebook and the animated HTML ebook","description":"Interactive PDF (contents, map pins, GPS links, photo pages, bookmarks) and a single-file HTML ebook (page turn, search, lightbox, what-if page when a point is typed and measured). Runs as a job.","security":[{"bearer":[]},{"oauth2":["surveys:read","documents:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Route id (GET /v1/surveys)","schema":{"type":"integer","minimum":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes a retry safe: the same key with the same body within 24 hours replays the first answer (header Idempotent-Replayed: true); a build is never started twice. Reusing a key with another body gives 422; while the first request is still running, 409.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildRequest"}}}},"responses":{"202":{"description":"Job accepted","headers":{"Location":{"schema":{"type":"string"},"description":"/v1/jobs/{id}"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"The request is not valid (errors[] lists each field)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, invalid or ended credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key or connection lacks a scope (required_scope says which), or the account has no access","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found, or not yours","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"A request with this Idempotency-Key is still running","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The input cannot be used, e.g. a GeoJSON without a track, or an Idempotency-Key reused with another body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit reached; Retry-After says when to try again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Documents need the hosted server (MCP_PUBLIC_URL)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/reports":{"post":{"tags":["Documents"],"summary":"Build a photo report PDF from a route id or a GeoJSON export","description":"A4 PDF: overview page (map, numbered index) and one card per survey point with every photo; unreachable photos become labelled slots. Runs as a job: poll the Location until status is succeeded, then open outputs[].url.","security":[{"bearer":[]},{"oauth2":["surveys:read","documents:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes a retry safe: the same key with the same body within 24 hours replays the first answer (header Idempotent-Replayed: true); a build is never started twice. Reusing a key with another body gives 422; while the first request is still running, 409.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildWithSourceRequest"}}}},"responses":{"202":{"description":"Job accepted","headers":{"Location":{"schema":{"type":"string"},"description":"/v1/jobs/{id}"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"The request is not valid (errors[] lists each field)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, invalid or ended credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key or connection lacks a scope (required_scope says which), or the account has no access","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found, or not yours","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"A request with this Idempotency-Key is still running","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The input cannot be used, e.g. a GeoJSON without a track, or an Idempotency-Key reused with another body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit reached; Retry-After says when to try again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Documents need the hosted server (MCP_PUBLIC_URL)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/ebooks":{"post":{"tags":["Documents"],"summary":"Build the interactive PDF ebook and the animated HTML ebook from a route id or a GeoJSON export","description":"Interactive PDF (contents, map pins, GPS links, photo pages, bookmarks) and a single-file HTML ebook (page turn, search, lightbox, what-if page when a point is typed and measured). Runs as a job.","security":[{"bearer":[]},{"oauth2":["surveys:read","documents:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes a retry safe: the same key with the same body within 24 hours replays the first answer (header Idempotent-Replayed: true); a build is never started twice. Reusing a key with another body gives 422; while the first request is still running, 409.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildWithSourceRequest"}}}},"responses":{"202":{"description":"Job accepted","headers":{"Location":{"schema":{"type":"string"},"description":"/v1/jobs/{id}"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"The request is not valid (errors[] lists each field)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, invalid or ended credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key or connection lacks a scope (required_scope says which), or the account has no access","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found, or not yours","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"A request with this Idempotency-Key is still running","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The input cannot be used, e.g. a GeoJSON without a track, or an Idempotency-Key reused with another body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit reached; Retry-After says when to try again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Documents need the hosted server (MCP_PUBLIC_URL)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/jobs/{id}":{"get":{"tags":["Documents"],"summary":"Status and outputs of a build","security":[{"bearer":[]},{"oauth2":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"The request is not valid (errors[] lists each field)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, invalid or ended credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key or connection lacks a scope (required_scope says which), or the account has no access","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found, or not yours","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The input cannot be used, e.g. a GeoJSON without a track, or an Idempotency-Key reused with another body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit reached; Retry-After says when to try again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/outputs":{"get":{"tags":["Documents"],"summary":"Your documents and their links","security":[{"bearer":[]},{"oauth2":["surveys:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Output"}}}}}}},"400":{"description":"The request is not valid (errors[] lists each field)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, invalid or ended credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key or connection lacks a scope (required_scope says which), or the account has no access","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found, or not yours","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The input cannot be used, e.g. a GeoJSON without a track, or an Idempotency-Key reused with another body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit reached; Retry-After says when to try again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Documents need the hosted server","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/outputs/{id}/share":{"post":{"tags":["Documents"],"summary":"Make a new link to a document, or revoke all its links","description":"A new link lasts expires_in_days (1-90, default 7). revoke: true ends every link and deletes the document.","security":[{"bearer":[]},{"oauth2":["share:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^doc_"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes a retry safe: the same key with the same body within 24 hours replays the first answer (header Idempotent-Replayed: true); a build is never started twice. Reusing a key with another body gives 422; while the first request is still running, 409.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareRequest"}}}},"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"output_id":{"type":"string"},"revoked":{"type":"integer","description":"Live links ended"}}}}}},"201":{"description":"New link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"400":{"description":"The request is not valid (errors[] lists each field)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, invalid or ended credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key or connection lacks a scope (required_scope says which), or the account has no access","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found, or not yours","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The input cannot be used, e.g. a GeoJSON without a track, or an Idempotency-Key reused with another body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit reached; Retry-After says when to try again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Documents need the hosted server","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key from /keys (rsk_…), or an OAuth access token issued by this server."},"oauth2":{"type":"oauth2","description":"Authorization code with PKCE (S256). Clients register dynamically at /oauth/register.","flows":{"authorizationCode":{"authorizationUrl":"https://rs-mcp.survys.com/oauth/authorize","tokenUrl":"https://rs-mcp.survys.com/oauth/token","refreshUrl":"https://rs-mcp.survys.com/oauth/token","scopes":{"surveys:read":"Read your routes, projects and planned routes, and check them against a cargo","documents:write":"Build reports, ebooks, what-if pages and exports of your routes","share:write":"Create and revoke links: to those documents, and RouteSurvey Share Center links to your routes","surveys:write":"Make changes in your RouteSurvey account: record measurements, add, move or remove survey points, plan routes and no-go zones, manage projects and scenarios, sign off routes, open support tickets"}}}}},"schemas":{"Problem":{"type":"object","description":"RFC 9457 problem details","required":["type","title","status"],"properties":{"type":{"type":"string","description":"urn:routesurvey:problem:<kind>"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string","description":"What went wrong and what to do, in plain words"},"instance":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}},"required_scope":{"type":"string","enum":["surveys:read","documents:write","share:write","surveys:write"]},"retry_after":{"type":"integer","description":"Seconds"}}},"Cargo":{"type":"object","additionalProperties":false,"description":"Numbers are metres and tonnes; text may carry a unit (\"15 ft 6 in\", \"617,000 lb\").","properties":{"description":{"type":"string","maxLength":80},"weight_t":{"oneOf":[{"type":"number","exclusiveMinimum":0},{"type":"string"}],"description":"Cargo weight without the vehicle"},"height_m":{"oneOf":[{"type":"number","exclusiveMinimum":0},{"type":"string"}],"description":"Loaded height above the road"},"width_m":{"oneOf":[{"type":"number","exclusiveMinimum":0},{"type":"string"}]},"length_m":{"oneOf":[{"type":"number","exclusiveMinimum":0},{"type":"string"}]},"vehicle_weight_t":{"oneOf":[{"type":"number","exclusiveMinimum":0},{"type":"string"}],"description":"Trailer and prime movers, added for bridges (default 60 t)"},"ground_clearance_m":{"oneOf":[{"type":"number","exclusiveMinimum":0},{"type":"string"}],"description":"Lowest point of the loaded vehicle, for rail crossings (default 0.30 m)"}}},"Source":{"type":"object","description":"Exactly one of survey_id and geojson","properties":{"survey_id":{"type":"integer","minimum":1},"geojson":{"oneOf":[{"$ref":"#/components/schemas/FeatureCollection"},{"type":"string","description":"The export file as text"}]}}},"CheckRequest":{"allOf":[{"$ref":"#/components/schemas/Source"},{"type":"object","properties":{"cargo":{"$ref":"#/components/schemas/Cargo"},"use_planned_cargo":{"type":"boolean","default":true,"description":"Fill missing cargo values from the route's planned route"},"rule_set_id":{"type":"string"},"format":{"type":"string","enum":["none","strip","share","desktop","glance"],"default":"none","description":"strip: 800 px chat image; share: 1200x630; desktop: 1200x800 map; glance: 380 px phone card"},"expires_in_days":{"type":"integer","minimum":1,"maximum":90,"default":7}}}]},"BuildRequest":{"type":"object","additionalProperties":false,"properties":{"cargo":{"$ref":"#/components/schemas/Cargo"},"use_planned_cargo":{"type":"boolean","default":true},"rule_set_id":{"type":"string"},"max_photos":{"type":"integer","minimum":1,"maximum":200,"default":200},"expires_in_days":{"type":"integer","minimum":1,"maximum":90,"default":7}}},"BuildWithSourceRequest":{"allOf":[{"$ref":"#/components/schemas/Source"},{"$ref":"#/components/schemas/BuildRequest"}]},"ShareRequest":{"type":"object","additionalProperties":false,"properties":{"expires_in_days":{"type":"integer","minimum":1,"maximum":90,"default":7},"revoke":{"type":"boolean","default":false}}},"Link":{"type":"object","properties":{"output_id":{"type":"string"},"url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"}}},"DocumentRef":{"type":"object","properties":{"output_id":{"type":["string","null"]},"url":{"type":["string","null"],"format":"uri"},"expires_at":{"type":["string","null"],"format":"date-time"},"file_name":{"type":"string"},"mime":{"type":"string"},"bytes":{"type":"integer"}}},"Job":{"type":"object","required":["id","kind","status"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["report","ebook"]},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"survey":{"type":"object","properties":{"id":{"type":["integer","null"]},"name":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"queue_position":{"type":"integer"},"result":{"type":["object","null"],"description":"Report: title, length_km, points, photos, embedded, unavailable, left_out, pages, measured, verdict, survey_points[], rule_set. Ebook: pdf_pages, points, photos, embedded, unavailable, left_out, links, html_kb, whatif, verdict, rule_set."},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/DocumentRef"}},"error":{"oneOf":[{"$ref":"#/components/schemas/Problem"},{"type":"null"}]}}},"Output":{"type":"object","properties":{"output_id":{"type":"string"},"kind":{"type":"string"},"title":{"type":"string"},"file_name":{"type":"string"},"mime":{"type":"string"},"bytes":{"type":"integer"},"route_id":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"links":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"expires_at":{"type":"string"},"revoked_at":{"type":["string","null"]},"opens":{"type":"integer"},"last_opened_at":{"type":["string","null"]},"live":{"type":"boolean"}}}}}},"RouteSummary":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"start":{"type":["string","null"]},"end":{"type":["string","null"]},"distance_m":{"type":["number","null"]},"points":{"type":["integer","null"]},"project_id":{"type":["integer","null"]},"planned_route_id":{"type":["integer","null"]},"date_added":{"type":["string","null"],"format":"date-time"},"date_updated":{"type":["string","null"],"format":"date-time"},"archived":{"type":"boolean"},"lifecycle_state":{"type":["string","null"]},"version":{"type":["string","null"]},"distance_to_place_m":{"type":"integer","description":"near only: to the nearer route end"},"nearest_end":{"type":"string","enum":["start","end"]},"start_coordinates":{"type":["array","null"],"items":{"type":"number"},"description":"[lon, lat]"},"end_coordinates":{"type":["array","null"],"items":{"type":"number"}}}},"SurveyList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RouteSummary"}},"next_cursor":{"type":["string","null"]},"total":{"type":["integer","null"]},"near":{"type":"object","description":"near only","properties":{"compared":{"type":"string"},"complete":{"type":"boolean"},"scanned":{"type":"integer"},"unplaced":{"type":"integer"}}}}},"CheckResult":{"type":"object","description":"Same shape as routesurvey_check structuredContent (docs schema/check-output.schema.json), plus summary and image.","properties":{"route":{"type":"object"},"verdict":{"type":"object","properties":{"state":{"type":"string","enum":["clear","conditional","blocked","none"],"description":"none = incomplete: never call it clear"},"text":{"type":"string"}}},"counts":{"type":"object"},"cargo":{"type":["object","null"]},"length_m":{"type":"integer"},"points":{"type":"array","items":{"type":"object"}},"gaps":{"type":"array","items":{"type":"object"}},"assumptions":{"type":"array","items":{"type":"string"}},"rule_set":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"version":{"type":"string"}}},"summary":{"type":"string","description":"One paragraph in plain words"},"image":{"oneOf":[{"type":"null"},{"type":"object","properties":{"format":{"type":"string"},"output_id":{"type":"string"},"url":{"type":"string"},"expires_at":{"type":"string"},"mime":{"type":"string"},"bytes":{"type":"integer"},"data_base64":{"type":"string","description":"Only without hosted documents"}}}]}}},"Envelope":{"type":"object","properties":{"route":{"type":"object"},"complete":{"type":"boolean"},"vehicle_weight_t":{"type":"number"},"vehicle_weight_assumed":{"type":"boolean"},"dimensions":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string","enum":["height","width","weight","ground_clearance"]},"direction":{"type":"string","enum":["max","min"]},"unit":{"type":"string"},"clear_limit":{"type":["object","null"]},"passable_limit":{"type":["object","null"]}}}},"load_independent":{"type":"array","items":{"type":"object"}},"rule_set":{"type":"object"},"summary":{"type":"string"}}},"RuleSetSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"version":{"type":"string"},"jurisdiction":{"type":["string","null"]},"note":{"type":["string","null"]},"default":{"type":"boolean"}}},"FeatureCollection":{"type":"object","required":["type","features"],"properties":{"type":{"const":"FeatureCollection"},"features":{"type":"array","items":{"type":"object"}}}}}}}