{ "openapi": "3.1.0", "info": { "title": "Daymark Verify and Watchlist API", "version": "1.0.0", "description": "Public-record carrier diligence with bounded, evidence-linked relationships. Missing records mean unknown coverage. See /pricing for current pricing." }, "servers": [ { "url": "/" } ], "paths": { "/v1/verify/{usdot}": { "get": { "operationId": "verifyCarrier", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verify" }, "examples": { "worked": { "summary": "Illustrative fixture, not live account data", "value": { "api_version": "v1", "request_id": "example-request", "mode": "live_evaluation", "profile": { "usdot": { "value": "123" }, "found": false, "sections": {}, "limitations": [ "Illustrative response; missing records mean unknown." ] }, "followups": { "history": "/v1/carriers/123/history", "relationships": "/v1/carriers/123/relationships" } } } } }, "text/csv": { "schema": { "type": "string" }, "example": "usdot,section,field,value,raw_value,record_date,dataset,source_published_at,source_url,fetched_at\n" } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "description": "Watchlist limit or expired evaluation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "409": { "description": "Already watched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid USDOT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "description": "Monthly allowance exhausted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "503": { "description": "Capacity or source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "parameters": [ { "name": "usdot", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{1,9}$" }, "description": "Positive USDOT number, normalized to remove leading zeros." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "csv" ] }, "description": "CSV rendering of the same result." } ], "description": "Core profile first; follow History and relationships links independently. Each admitted request consumes one allowance call." } }, "/v1/sandbox/verify/{usdot}": { "get": { "operationId": "sandboxVerifyCarrier", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verify" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "description": "Watchlist limit or expired evaluation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "409": { "description": "Already watched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid USDOT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "description": "Monthly allowance exhausted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "503": { "description": "Capacity or source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "parameters": [ { "name": "usdot", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{1,9}$" }, "description": "Positive USDOT number, normalized to remove leading zeros." } ], "description": "Synthetic fixture only; no live queries or allowance usage." } }, "/v1/watchlist": { "get": { "operationId": "listWatchlist", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watchlist" } }, "text/csv": { "schema": { "type": "string" }, "example": "usdot,added_at,last_viewed_at,unseen_changes\n" } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "description": "Watchlist limit or expired evaluation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "409": { "description": "Already watched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid USDOT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "description": "Monthly allowance exhausted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "503": { "description": "Capacity or source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "csv" ] }, "description": "CSV rendering of the same result. Watchlist CSV exports the full list and ignores limit and offset." } ], "description": "Paginated list. Explicit pagination on changes uses membership time and does not advance the viewed cursor. See docs/api/ANALYTICS.md." }, "post": { "operationId": "addWatchCarrier", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchCarrier" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "description": "Watchlist limit or expired evaluation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "409": { "description": "Already watched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid USDOT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "description": "Monthly allowance exhausted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "503": { "description": "Capacity or source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "usdot": { "type": "string", "pattern": "^[0-9]{1,9}$" } }, "required": [ "usdot" ] } } } } } }, "/v1/watchlist/changes": { "get": { "operationId": "readWatchChanges", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changes" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "description": "Watchlist limit or expired evaluation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "409": { "description": "Already watched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid USDOT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "description": "Monthly allowance exhausted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "503": { "description": "Capacity or source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "description": "Paginated list. Explicit pagination on changes uses membership time and does not advance the viewed cursor. See docs/api/ANALYTICS.md.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ] } }, "/v1/watchlist/{usdot}": { "delete": { "operationId": "removeWatchCarrier", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Removed; no response body", "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "description": "Watchlist limit or expired evaluation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "409": { "description": "Already watched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "422": { "description": "Invalid USDOT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "description": "Monthly allowance exhausted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "503": { "description": "Capacity or source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "parameters": [ { "name": "usdot", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{1,9}$" }, "description": "Positive USDOT number, normalized to remove leading zeros." } ] } }, "/v1/analytics/usage": { "get": { "operationId": "analytics_usage", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Account-scoped usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" }, "examples": { "worked": { "summary": "Illustrative fixture, not live account data", "value": { "api_version": "v1", "request_id": "example-request", "period": "2026-10-01", "used": 1, "cap": 50, "remaining": 49, "by_endpoint": { "verify": 1, "sandbox": null, "history": null, "watchlist": null }, "daily_counts": [ { "date": "2026-10-21", "endpoint": "verify", "count": 1 } ], "limitations": [ "Illustrative fixture only; telemetry is incomplete." ] } } } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "503": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "description": "Account-scoped read; no allowance consumed. Unknown counts are null. See docs/api/ANALYTICS.md for field and coverage details." } }, "/v1/analytics/lookups": { "get": { "operationId": "analytics_lookups", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "Account-scoped lookups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupAnalytics" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "503": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "description": "Account-scoped read; no allowance consumed. Unknown counts are null. See docs/api/ANALYTICS.md for field and coverage details." } }, "/v1/analytics/watchlist": { "get": { "operationId": "analytics_watchlist", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "Account-scoped watchlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistAnalytics" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "503": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "description": "Account-scoped read; no allowance consumed. Unknown counts are null. See docs/api/ANALYTICS.md for field and coverage details." } }, "/v1/carriers/{usdot}/history": { "get": { "operationId": "carrierHistory", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "usdot", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{1,9}$" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "csv" ] }, "description": "CSV rendering of the same result." } ], "responses": { "200": { "description": "Paginated evidence events; no events means unknown history.", "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "examples": { "worked": { "summary": "Illustrative fixture, not live account data", "value": { "api_version": "v1", "request_id": "example-request", "usdot": "123", "events": [], "total": 0, "limit": 100, "offset": 0, "coverage": "unknown" } } }, "schema": { "$ref": "#/components/schemas/History" } }, "text/csv": { "schema": { "type": "string" }, "example": "usdot,date,type,label,details,dataset,as_of,evidence_url\n" } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "503": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } } } }, "/v1/carriers/{usdot}/relationships": { "get": { "operationId": "carrierRelationships", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "usdot", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{1,9}$" } } ], "responses": { "200": { "description": "Bounded evidence-linked relationships including VIN linkage; absence of matches does not establish absence of relationships.", "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "graph": { "$ref": "#/components/schemas/Graph" }, "usage": { "type": "object" }, "api_version": { "const": "v1" }, "request_id": { "type": "string" } }, "required": [ "graph", "api_version", "request_id" ] }, "examples": { "worked": { "summary": "Illustrative fixture, not live carrier evidence", "value": { "api_version": "v1", "request_id": "example-request", "graph": { "edges": [], "suppressed": [], "complete": false } } } } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "503": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Daymark-Request": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } } } }, "/v1/carriers/{usdot}/evidence-pack": { "get": { "summary": "Download a dated, content-hashed diligence evidence pack (trial or paid)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "usdot", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "html" ] } } ], "responses": { "200": { "description": "Unsigned on-demand JSON pack or printable HTML with the same facts. See docs/api/FUTURE_APIS.md for hash scope.", "content": { "application/json": { "schema": { "type": "object" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Invalid key" }, "403": { "description": "Trial or paid entitlement required; standard profile remains available" }, "429": { "description": "Monthly allowance exhausted" }, "503": { "description": "Source or database unavailable" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "A valid evaluation bearer key is required.", "request_id": "example-request" } } }, "Evidence": { "type": "object", "properties": { "dataset": { "type": "string" }, "url": { "type": "string" }, "source_updated_at": { "type": [ "string", "null" ] }, "fetched_at": { "type": "string" }, "sha256": { "type": [ "string", "null" ] } }, "required": [ "dataset", "url" ] }, "Fact": { "type": "object", "properties": { "value": {}, "field": { "type": "string" }, "record_date": { "type": [ "string", "null" ] }, "evidence": { "$ref": "#/components/schemas/Evidence" } }, "required": [ "value", "evidence" ] }, "Section": { "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Fact" } } }, "evidence": { "$ref": "#/components/schemas/Evidence" } }, "required": [ "records", "evidence" ] }, "Profile": { "type": "object", "properties": { "schema_version": { "type": "integer" }, "found": { "type": "boolean" }, "usdot": { "type": "object", "properties": { "value": { "type": "string" } } }, "sections": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Section" } }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "usdot", "sections", "limitations" ] }, "Graph": { "type": "object", "properties": { "complete": { "const": false }, "edges": { "type": "array", "items": { "type": "object", "properties": { "from_usdot": { "type": "string" }, "to_usdot": { "type": "string" }, "kind": { "type": "string" }, "value": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/Fact" } } } } } }, "suppressed": { "type": "array", "items": { "type": "object" } }, "searches": { "type": "array", "items": { "type": "object" } }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "edges", "suppressed", "complete" ] }, "Verify": { "type": "object", "properties": { "api_version": { "const": "v1" }, "mode": { "enum": [ "live_evaluation", "synthetic_sandbox" ] }, "profile": { "$ref": "#/components/schemas/Profile" }, "graph": { "$ref": "#/components/schemas/Graph", "description": "Present in sandbox fixtures; live relationships are fetched separately." }, "cache": { "type": "string" }, "fetched_at": { "type": "string" }, "expires_at": { "type": "string" }, "usage": { "type": [ "object", "null" ] }, "request_id": { "type": "string" }, "followups": { "type": "object", "properties": { "history": { "type": "string" }, "relationships": { "type": "string" } }, "required": [ "history", "relationships" ] } }, "required": [ "api_version", "mode", "profile" ] }, "WatchCarrier": { "type": "object", "properties": { "usdot": { "type": "string" }, "added_at": { "type": "string", "format": "date-time" }, "last_viewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "unseen_changes": { "type": "integer" } }, "required": [ "usdot", "added_at" ] }, "Watchlist": { "type": "object", "properties": { "carriers": { "type": "array", "items": { "$ref": "#/components/schemas/WatchCarrier" } }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "cap": { "enum": [ 5, 200 ] }, "total": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 } }, "required": [ "carriers", "limit" ] }, "Changes": { "type": "object", "properties": { "changes": { "type": "array", "items": { "type": "object", "properties": { "usdot": { "type": "string" }, "dataset": { "type": "string" }, "matched_at": { "type": "string", "format": "date-time" }, "version": { "type": "string" }, "source_after": { "type": "object" }, "sha256": { "type": "string" }, "raw": { "type": "object", "additionalProperties": true } } } }, "limitations": { "type": "array", "items": { "type": "string" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "offset": { "type": "integer", "minimum": 0 } }, "required": [ "changes", "limitations" ] }, "UsageSummary": { "type": "object", "properties": { "api_version": { "const": "v1" }, "request_id": { "type": "string" }, "period": { "type": "string", "format": "date" }, "used": { "type": "integer", "minimum": 0 }, "cap": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "by_endpoint": { "type": "object", "properties": { "verify": { "type": [ "integer", "null" ], "minimum": 0 }, "sandbox": { "type": [ "integer", "null" ], "minimum": 0 }, "history": { "type": [ "integer", "null" ], "minimum": 0 }, "watchlist": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "verify", "sandbox", "history", "watchlist" ] }, "daily_counts": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "endpoint": { "enum": [ "verify", "sandbox", "history", "unknown" ] }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "date", "endpoint", "count" ] } }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "api_version", "request_id", "period", "used", "cap", "remaining", "by_endpoint", "daily_counts", "limitations" ] }, "LookupAnalytics": { "type": "object", "properties": { "api_version": { "const": "v1" }, "request_id": { "type": "string" }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "offset": { "type": "integer", "minimum": 0 }, "lookups": { "type": "array", "items": { "type": "object", "properties": { "usdot": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "outcome": { "enum": [ "served", "unknown", "suppressed" ] }, "reason_classes": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "usdot", "timestamp", "outcome", "reason_classes" ] } } }, "required": [ "api_version", "request_id", "total", "limit", "offset", "lookups" ] }, "WatchlistAnalytics": { "type": "object", "properties": { "api_version": { "const": "v1" }, "request_id": { "type": "string" }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "offset": { "type": "integer", "minimum": 0 }, "carriers": { "type": "array", "items": { "type": "object", "properties": { "usdot": { "type": "string" }, "added_at": { "type": "string", "format": "date-time" }, "last_change": { "type": [ "string", "null" ], "format": "date-time" }, "change_counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "required": [ "usdot", "added_at", "last_change", "change_counts" ] } }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "api_version", "request_id", "total", "limit", "offset", "carriers", "limitations" ] }, "History": { "type": "object", "properties": { "api_version": { "const": "v1" }, "request_id": { "type": "string" }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "offset": { "type": "integer", "minimum": 0 }, "usdot": { "type": "string" }, "events": { "type": "array", "items": { "type": "object" } }, "coverage": { "type": "string" } }, "required": [ "api_version", "request_id", "usdot", "events", "total", "limit", "offset" ] } }, "parameters": { "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, "Offset": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } } } }