{ "openapi": "3.1.0", "info": { "title": "DriveRevu Public Metadata API", "version": "1.0.0", "description": "Catalog metadata only. No text syndication, verified retail status, numerical ratings, private research, inventory or media rights. Best-effort per-instance120/minute and4concurrent; not a distributed quota. Live pages may shift; see /developers." }, "servers": [ { "url": "https://driverevu.com" } ], "paths": { "/api/v1/catalog": { "get": { "operationId": "searchCatalog", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 80, "description": "At most five words; letters/digits/spaces/periods/apostrophes/hyphens" } }, { "name": "make", "in": "query", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" } }, { "name": "year", "in": "query", "schema": { "type": "integer", "minimum": 2000, "maximum": 2099 } }, { "name": "kind", "in": "query", "schema": { "enum": [ "production", "concept" ], "default": "production" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 20 } }, { "name": "If-None-Match", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public metadata; no private research or verified ratings", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogEntry" }, "maxItems": 25 }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 20 }, "limit": { "type": "integer", "minimum": 1, "maximum": 25 }, "nextPage": { "type": [ "integer", "null" ] }, "windowLimitReached": { "type": "boolean" }, "maxPage": { "const": 20 } }, "required": [ "page", "limit", "nextPage", "windowLimitReached", "maxPage" ] }, "freshness": { "type": "object", "properties": { "policy": { "const": "fresh_publication_check_each_request" }, "consistency": { "const": "live_pages_may_shift_during_updates" } }, "required": [ "policy" ] } }, "required": [ "schemaVersion", "items", "pagination", "freshness" ] } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" }, "description": "private, no-cache, max-age=0, must-revalidate" } } }, "304": { "description": "Unchanged after fresh publication check" }, "400": { "description": "Error with no internal details", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "schemaVersion", "error" ] } } } }, "404": { "description": "Error with no internal details", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "schemaVersion", "error" ] } } } }, "405": { "description": "Method unsupported" }, "429": { "description": "Error with no internal details", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "schemaVersion", "error" ] } } }, "headers": { "Retry-After": { "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Error with no internal details", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "schemaVersion", "error" ] } } } } } } }, "/api/v1/reviews/{slug}": { "get": { "operationId": "getPublishedReview", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,120}$" } }, { "name": "If-None-Match", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public metadata; no private research or verified ratings", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "item": { "$ref": "#/components/schemas/CatalogEntry" }, "provenance": { "type": "object", "properties": { "state": { "const": "publisher_listed_unverified" }, "references": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "origin": { "type": "string", "format": "uri" }, "verification": { "const": "not_independently_verified" }, "retrievedAt": { "type": "null" }, "contentHash": { "type": "null" } }, "required": [ "url", "origin", "verification", "retrievedAt", "contentHash" ] }, "maxItems": 10 }, "limit": { "const": 10 }, "omittedOrTruncated": { "type": "boolean" } }, "required": [ "state", "references", "limit", "omittedOrTruncated" ] }, "content": { "type": "object", "properties": { "state": { "const": "catalog_only" }, "body": { "type": "null" }, "reason": { "type": "string" } }, "required": [ "state", "body", "reason" ] }, "freshness": { "type": "object", "properties": { "policy": { "const": "fresh_publication_check_each_request" }, "consistency": { "const": "live_pages_may_shift_during_updates" } }, "required": [ "policy" ] } }, "required": [ "schemaVersion", "item", "provenance", "content", "freshness" ] } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" }, "description": "private, no-cache, max-age=0, must-revalidate" } } }, "304": { "description": "Unchanged after fresh publication check" }, "400": { "description": "Error with no internal details", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "schemaVersion", "error" ] } } } }, "404": { "description": "Error with no internal details", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "schemaVersion", "error" ] } } } }, "405": { "description": "Method unsupported" }, "429": { "description": "Error with no internal details", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "schemaVersion", "error" ] } } }, "headers": { "Retry-After": { "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Error with no internal details", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "schemaVersion", "error" ] } } } } } } }, "/api/v1/inventory": { "get": { "operationId": "inventoryConnectionState", "parameters": [ { "name": "If-None-Match", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public metadata; no private research or verified ratings", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "state": { "const": "provider_not_connected" }, "vehicles": { "type": "array", "items": {}, "maxItems": 0 }, "liveAvailability": { "const": false }, "checkedAt": { "type": "null" }, "message": { "type": "string" } }, "required": [ "schemaVersion", "state", "vehicles", "liveAvailability", "checkedAt", "message" ] } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" }, "description": "private, no-cache, max-age=0, must-revalidate" } } }, "304": { "description": "Unchanged after fresh publication check" }, "400": { "description": "Error with no internal details", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "schemaVersion", "error" ] } } } }, "404": { "description": "Error with no internal details", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "schemaVersion", "error" ] } } } }, "405": { "description": "Method unsupported" }, "429": { "description": "Error with no internal details", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "schemaVersion", "error" ] } } }, "headers": { "Retry-After": { "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Error with no internal details", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "driverevu.api.v1" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "schemaVersion", "error" ] } } } } } } } }, "components": { "schemas": { "CatalogEntry": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "canonicalUrl": { "type": "string", "format": "uri" }, "make": { "type": "string" }, "model": { "type": "string" }, "catalogYear": { "type": "integer" }, "vehicleKind": { "enum": [ "production", "concept" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "market": { "type": "object", "properties": { "catalogScope": { "const": "US" }, "modelYearVerification": { "const": "unverified" }, "retailStatus": { "const": "unverified" } }, "required": [ "catalogScope", "modelYearVerification", "retailStatus" ] }, "publication": { "type": "object", "properties": { "state": { "const": "published_catalog" }, "contentScope": { "const": "catalog_only" }, "updatedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "state", "contentScope", "updatedAt", "publishedAt" ] }, "evidence": { "type": "object", "properties": { "state": { "const": "not_verified_for_api" }, "reason": { "type": "string" } }, "required": [ "state", "reason" ] }, "score": { "type": "object", "properties": { "state": { "const": "withheld_unverified" }, "value": { "type": "null" } }, "required": [ "state", "value" ] }, "inventory": { "type": "object", "properties": { "state": { "const": "provider_not_connected" } }, "required": [ "state" ] }, "rights": { "type": "object", "properties": { "scope": { "const": "metadata_only" }, "mediaRedistribution": { "const": "not_granted" } }, "required": [ "scope", "mediaRedistribution" ] } }, "required": [ "id", "slug", "canonicalUrl", "make", "model", "catalogYear", "vehicleKind", "categories", "market", "publication", "evidence", "score", "inventory", "rights" ] } } } }