{ "openapi": "3.1.0", "info": { "title": "Vetted Cases Public Agent API", "version": "1.0.0", "summary": "Public discovery interface for Vetted Cases", "description": "Find public Vetted Cases guides, tools, data and human-facing starting points. This API does not accept claimant facts, decide whether someone has a case or expose private claimant or reviewer data.", "termsOfService": "https://vettedcases.com/legal/terms/", "contact": { "name": "Vetted Cases", "url": "https://vettedcases.com/developers/" } }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://vettedcases.com", "description": "Vetted Cases production" } ], "externalDocs": { "description": "Vetted Cases developer and agent guide", "url": "https://vettedcases.com/developers/" }, "tags": [ { "name": "Public discovery", "description": "Unauthenticated public information with no claimant or reviewer data." } ], "paths": { "/api/public/capabilities": { "get": { "operationId": "getVettedCasesCapabilities", "summary": "Get Vetted Cases agent-use guidance", "description": "Returns the jobs this public interface supports, its limits, human handoff options and links to machine-readable discovery files. Use this before choosing another operation.", "tags": [ "Public discovery" ], "security": [], "responses": { "200": { "description": "Current public capability and safety guidance.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesResponse" } } } }, "500": { "$ref": "#/components/responses/ApiError" } } } }, "/api/public/resources": { "get": { "operationId": "listVettedCasesResources", "summary": "List useful Vetted Cases public destinations", "description": "Returns a short, task-oriented list of public guides, tools, data, help and case-check destinations in English or Spanish. Use sitemap.xml for the complete page inventory.", "tags": [ "Public discovery" ], "security": [], "parameters": [ { "name": "language", "in": "query", "required": false, "description": "Language for resource names and descriptions.", "schema": { "type": "string", "enum": [ "en", "es" ], "default": "en" } } ], "responses": { "200": { "description": "Task-oriented public resources in the requested language.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourcesResponse" } } } }, "400": { "$ref": "#/components/responses/ApiError" }, "500": { "$ref": "#/components/responses/ApiError" } } } }, "/api/public/crash-corridors": { "get": { "operationId": "listVettedCasesCrashCorridors", "summary": "List published fatal-crash corridor aggregates", "description": "Returns the published named road-within-county aggregates derived from final NHTSA FARS files, with definitions, limits, source dates and methodology links. These are fatal-crash counts, not all crashes, injury estimates, claims, lawsuits, danger rankings or fault findings.", "tags": [ "Public discovery" ], "security": [], "parameters": [ { "name": "state", "in": "query", "required": false, "description": "Optional two-letter United States postal code. Omit it to return every published corridor.", "schema": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "examples": [ "CA", "NY", "TX" ] } } ], "responses": { "200": { "description": "Published corridor aggregates and dataset context.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrashCorridorsResponse" } } } }, "400": { "$ref": "#/components/responses/ApiError" }, "500": { "$ref": "#/components/responses/ApiError" } } } } }, "components": { "headers": { "CacheControl": { "description": "Shared-cache policy for public, non-personal data.", "schema": { "type": "string" } } }, "responses": { "ApiError": { "description": "A structured error with a stable code and recovery guidance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "schemas": { "PublicOperation": { "type": "object", "additionalProperties": false, "required": [ "operationId", "method", "path" ], "properties": { "operationId": { "type": "string", "description": "Unique function-call operation name." }, "method": { "type": "string", "enum": [ "GET" ] }, "path": { "type": "string", "pattern": "^/api/public/" } } }, "DiscoveryLinks": { "type": "object", "additionalProperties": false, "required": [ "developerGuide", "openapi", "sitemap", "conciseIndex", "fullAnswerIndex" ], "properties": { "developerGuide": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "sitemap": { "type": "string", "format": "uri" }, "conciseIndex": { "type": "string", "format": "uri" }, "fullAnswerIndex": { "type": "string", "format": "uri" } } }, "HumanHandoff": { "type": "object", "additionalProperties": false, "required": [ "caseCheck", "callOrText", "help" ], "properties": { "caseCheck": { "type": "string", "format": "uri" }, "callOrText": { "type": "string", "description": "Public number displayed for calls and texts." }, "help": { "type": "string", "format": "uri" } } }, "CapabilitiesResponse": { "type": "object", "additionalProperties": false, "required": [ "service", "canonicalUrl", "purpose", "availableLanguages", "safeAgentUses", "notSupported", "publicOperations", "discovery", "humanHandoff" ], "properties": { "service": { "type": "string", "const": "Vetted Cases" }, "canonicalUrl": { "type": "string", "format": "uri" }, "purpose": { "type": "string" }, "availableLanguages": { "type": "array", "items": { "type": "string", "enum": [ "en-US", "es-US" ] }, "minItems": 2, "maxItems": 2 }, "safeAgentUses": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "notSupported": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "publicOperations": { "type": "array", "items": { "$ref": "#/components/schemas/PublicOperation" } }, "discovery": { "$ref": "#/components/schemas/DiscoveryLinks" }, "humanHandoff": { "$ref": "#/components/schemas/HumanHandoff" } } }, "Resource": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "name", "description", "url", "alternateLanguageUrl" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "kind": { "type": "string", "enum": [ "case_check", "guide", "tool", "directory", "data", "help" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "alternateLanguageUrl": { "type": "string", "format": "uri" } } }, "ResourcesResponse": { "type": "object", "additionalProperties": false, "required": [ "service", "language", "count", "items", "fullInventory" ], "properties": { "service": { "type": "string", "const": "Vetted Cases" }, "language": { "type": "string", "enum": [ "en", "es" ] }, "count": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } }, "fullInventory": { "type": "string", "format": "uri" } } }, "CorridorCounts": { "type": "object", "additionalProperties": false, "required": [ "fatal_crashes", "fatalities", "pedestrian_involved_fatal_crashes", "large_truck_involved_fatal_crashes", "county_fatal_crashes", "corridor_share_of_county_fatal_crashes_percent" ], "properties": { "fatal_crashes": { "type": "integer", "minimum": 0 }, "fatalities": { "type": "integer", "minimum": 0 }, "pedestrian_involved_fatal_crashes": { "type": "integer", "minimum": 0 }, "large_truck_involved_fatal_crashes": { "type": "integer", "minimum": 0 }, "county_fatal_crashes": { "type": "integer", "minimum": 0 }, "corridor_share_of_county_fatal_crashes_percent": { "type": "number", "minimum": 0, "maximum": 100 } } }, "Corridor": { "type": "object", "additionalProperties": false, "required": [ "id", "route", "county", "state", "stateCode", "cityContext", "coverageStart", "coverageEnd", "definition", "years", "totals", "page" ], "properties": { "id": { "type": "string" }, "route": { "type": "string" }, "county": { "type": "string" }, "state": { "type": "string" }, "stateCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "cityContext": { "type": "array", "items": { "type": "string" } }, "coverageStart": { "type": "string", "format": "date" }, "coverageEnd": { "type": "string", "format": "date" }, "definition": { "type": "string" }, "years": { "type": "object", "additionalProperties": false, "required": [ "2022", "2023", "2024" ], "properties": { "2022": { "$ref": "#/components/schemas/CorridorCounts" }, "2023": { "$ref": "#/components/schemas/CorridorCounts" }, "2024": { "$ref": "#/components/schemas/CorridorCounts" } } }, "totals": { "$ref": "#/components/schemas/CorridorCounts" }, "page": { "type": "string", "format": "uri" } } }, "CrashDataset": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "methodVersion", "publishedAt", "retrievedAt", "coverageStart", "coverageEnd", "definition", "limitations", "methodology", "downloads" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "methodVersion": { "type": "string" }, "publishedAt": { "type": "string", "format": "date" }, "retrievedAt": { "type": "string", "format": "date" }, "coverageStart": { "type": "string", "format": "date" }, "coverageEnd": { "type": "string", "format": "date" }, "definition": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } }, "methodology": { "type": "string", "format": "uri" }, "downloads": { "type": "object", "additionalProperties": false, "required": [ "csv", "json", "dataDictionary" ], "properties": { "csv": { "type": "string", "format": "uri" }, "json": { "type": "string", "format": "uri" }, "dataDictionary": { "type": "string", "format": "uri" } } } } }, "CrashCorridorsResponse": { "type": "object", "additionalProperties": false, "required": [ "service", "dataset", "filters", "count", "corridors" ], "properties": { "service": { "type": "string", "const": "Vetted Cases" }, "dataset": { "$ref": "#/components/schemas/CrashDataset" }, "filters": { "type": "object", "additionalProperties": false, "required": [ "state" ], "properties": { "state": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$" } } }, "count": { "type": "integer", "minimum": 0 }, "corridors": { "type": "array", "items": { "$ref": "#/components/schemas/Corridor" } } } }, "ApiError": { "type": "object", "additionalProperties": false, "required": [ "status", "error", "message", "resolution", "documentation" ], "properties": { "status": { "type": "string", "const": "error" }, "error": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Plain-language explanation." }, "resolution": { "type": "string", "description": "A safe next step for the caller." }, "documentation": { "type": "string", "format": "uri" } } } } } }