{ "openapi": "3.0.3", "info": { "title": "AKIS Solutions CARFAX API", "version": "1.1.0", "description": "Private server-to-server CARFAX report API for carreport360.com, backed by the existing supplier and company prepaid account. Read /account for current prices and orderingEnabled; prices are integer USD cents and must never be guessed. FRESH creates supplier work; STORED uses a completed stored report. Importing the provided Node.js client performs no requests. Keep credentials on your server. Browser Origin and Sec-Fetch-Site headers are rejected for bearer-authenticated endpoints; a short-lived report ticket is the browser-access alternative. Report polling continues an existing operation and never implies a new purchase." }, "servers": [ { "url": "https://akis-solutions.com/api/v1/carfax", "description": "AKIS Solutions canonical company API" } ], "security": [ { "companyKey": [] } ], "paths": { "/account": { "get": { "operationId": "getCompanyAccount", "summary": "Read ordering status, prices and prepaid wallet", "responses": { "200": { "description": "Company account; monetary amounts are integer USD cents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "400": { "description": "Malformed JSON, invalid VIN/mode/price/UUID or invalid/duplicate/unknown parameters.", "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid company credential, or invalid/expired report ticket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "403": { "description": "Browser bearer request, disabled company account, or ordering is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "429": { "description": "Shared company request rate or pending/daily order quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } }, "Retry-After": { "description": "Suggested delay in seconds. Pending requests normally return 5. A 429 normally returns 60; daily/report quotas may take longer to clear.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "API configuration, gateway or report service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "504": { "description": "GATEWAY_TIMEOUT: the gateway deadline elapsed. A POST may already have been accepted upstream; recover deliberately using the same persisted Idempotency-Key and unchanged payload, never a new purchase key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } } }, "tags": [ "Company account" ], "description": "Read the authenticated company wallet, live quotes, ordering switch and configured limits. No query parameters are accepted. Account access does not create a report order. The wallet balance, held and available amounts are USD cents; held amounts reserve pending reports until completion or failure." } }, "/reports": { "post": { "operationId": "requestReport", "summary": "Request a report with an idempotency key", "description": "Submit one explicit business operation using a caller-generated UUID in Idempotency-Key. Persist that key and the exact VIN/mode/expectedPriceCents before sending. On network failure or an uncertain response, the operation may already exist: retry only deliberately with the SAME key and unchanged payload. Changing the payload under a bound key returns 409. The returned order id is separate from the idempotency key and must be used for polling/download. FRESH forces new supplier work. STORED requires a completed stored report; an already owned completed report is returned without another charge and retains its original mode/price metadata. Same-VIN pending requests coalesce only when mode and price match; otherwise 409. A new UUID can intentionally purchase a later FRESH report. No query parameters are accepted. New orders require orderingEnabled, a current price quote, available prepaid funds and remaining quotas.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Caller-generated UUID persisted for one business operation. Reuse it, with the exact same payload, after an unknown outcome; never generate a new key merely because a request timed out." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderInput" } } } }, "responses": { "200": { "description": "Completed or failed order, or idempotent replay of an existing pending order. Read the status field; HTTP 200 alone does not mean the report is ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRequest" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } }, "Retry-After": { "description": "Suggested delay in seconds. Pending requests normally return 5. A 429 normally returns 60; daily/report quotas may take longer to clear.", "schema": { "type": "integer", "minimum": 1 } } } }, "202": { "description": "Accepted pending order. Poll the returned id; do not create another order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRequest" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } }, "Retry-After": { "description": "Suggested delay in seconds. Pending requests normally return 5. A 429 normally returns 60; daily/report quotas may take longer to clear.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Malformed JSON, invalid VIN/mode/price/UUID or invalid/duplicate/unknown parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "401": { "description": "Missing or invalid company credential, or invalid/expired report ticket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "403": { "description": "Browser bearer request, disabled company account, or ordering is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "404": { "description": "No stored report is available, or the company-owned completed report/order cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "409": { "description": "Price changed, insufficient available balance, idempotency payload conflict, or pending same-VIN mode/price conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "413": { "description": "Request body exceeds 8192 UTF-8 bytes or the report exceeds supported storage size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "415": { "description": "Order body must use application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "429": { "description": "Shared company request rate or pending/daily order quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } }, "Retry-After": { "description": "Suggested delay in seconds. Pending requests normally return 5. A 429 normally returns 60; daily/report quotas may take longer to clear.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "API configuration, gateway or report service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "504": { "description": "GATEWAY_TIMEOUT: the gateway deadline elapsed. A POST may already have been accepted upstream; recover deliberately using the same persisted Idempotency-Key and unchanged payload, never a new purchase key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } } }, "tags": [ "Report requests" ] }, "get": { "operationId": "getReportRequest", "summary": "Poll a company-owned request", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Report request and current readiness", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRequest" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } }, "Retry-After": { "description": "Suggested delay in seconds. Pending requests normally return 5. A 429 normally returns 60; daily/report quotas may take longer to clear.", "schema": { "type": "integer", "minimum": 1 } } } }, "400": { "description": "Malformed JSON, invalid VIN/mode/price/UUID or invalid/duplicate/unknown parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "401": { "description": "Missing or invalid company credential, or invalid/expired report ticket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "403": { "description": "Browser bearer request, disabled company account, or ordering is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "404": { "description": "No stored report is available, or the company-owned completed report/order cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "429": { "description": "Shared company request rate or pending/daily order quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } }, "Retry-After": { "description": "Suggested delay in seconds. Pending requests normally return 5. A 429 normally returns 60; daily/report quotas may take longer to clear.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "API configuration, gateway or report service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "504": { "description": "GATEWAY_TIMEOUT: the gateway deadline elapsed. A POST may already have been accepted upstream; recover deliberately using the same persisted Idempotency-Key and unchanged payload, never a new purchase key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } } }, "tags": [ "Report requests" ], "description": "Read/poll one company-owned order by its returned id. HTTP 200 can represent queued, processing, ready or failed; only ready includes a downloadable validated report. No list endpoint is available. Unknown, unowned and cross-company ids return 404. Only the id query parameter is accepted." } }, "/report": { "get": { "operationId": "downloadReport", "summary": "Download a validated completed report", "description": "Download an owned validated READY report as application/pdf or text/html. Use the company bearer key with id from your server, or the exact short-lived signed URL from a ready order in a browser. Ticket authentication is used whenever ticket is present, even if an Authorization header is supplied; an invalid/expired ticket is not replaced by bearer authentication. Tickets expire in five minutes and are revoked by key rotation or account disablement. Only id and optional ticket query parameters are accepted. Unready/missing reports return a structured 404; no loading page is delivered as a ready file. Native format is determined by the actual report; PDF conversion is not promised. The supplier URL and private storage key are not exposed.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "ticket", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 }, "description": "Five-minute signed delivery ticket; supply the exact URL returned in report.url. This is not the API key." } ], "security": [ { "companyKey": [] }, { "reportTicket": [] } ], "responses": { "200": { "description": "Completed report in its available native format", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "text/html": { "schema": { "type": "string" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "400": { "description": "Malformed JSON, invalid VIN/mode/price/UUID or invalid/duplicate/unknown parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "401": { "description": "Missing or invalid company credential, or invalid/expired report ticket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "403": { "description": "Browser bearer request, disabled company account, or ordering is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "404": { "description": "No stored report is available, or the company-owned completed report/order cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "413": { "description": "Request body exceeds 8192 UTF-8 bytes or the report exceeds supported storage size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "429": { "description": "Shared company request rate or pending/daily order quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } }, "Retry-After": { "description": "Suggested delay in seconds. Pending requests normally return 5. A 429 normally returns 60; daily/report quotas may take longer to clear.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "API configuration, gateway or report service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } }, "504": { "description": "GATEWAY_TIMEOUT: the gateway deadline elapsed. A POST may already have been accepted upstream; recover deliberately using the same persisted Idempotency-Key and unchanged payload, never a new purchase key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "description": "Private responses are never cacheable.", "schema": { "type": "string", "example": "private, no-store, max-age=0" } } } } }, "tags": [ "Report delivery" ] } } }, "components": { "securitySchemes": { "companyKey": { "type": "http", "scheme": "bearer", "bearerFormat": "cr360_[a-f0-9]{64}", "description": "Company server credential: cr360_ followed by exactly 64 lowercase hexadecimal characters. Never include it in browser JavaScript, URLs, logs or shared files. Bearer requests must omit Origin and Sec-Fetch-Site headers." }, "reportTicket": { "type": "apiKey", "in": "query", "name": "ticket", "description": "Short-lived signed ticket from report.url; authorizes only its matching owned ready report id. Maximum lifetime is 300 seconds. It is revoked when the company key rotates or the account is disabled." } }, "schemas": { "OrderInput": { "type": "object", "additionalProperties": false, "required": [ "vin", "mode", "expectedPriceCents" ], "properties": { "vin": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$" }, "mode": { "type": "string", "enum": [ "STORED", "FRESH" ] }, "expectedPriceCents": { "type": "integer", "minimum": 1, "maximum": 100000000, "description": "The current account quote for this mode, in USD cents" } } }, "ReportRequest": { "type": "object", "required": [ "id", "vin", "mode", "status", "priceCents", "currency", "createdAt", "updatedAt", "error", "report" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Order identifier returned by the API. It need not match the UUID used as Idempotency-Key." }, "vin": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$" }, "mode": { "type": "string", "enum": [ "STORED", "FRESH" ] }, "status": { "type": "string", "enum": [ "queued", "processing", "ready", "failed" ], "description": "Only ready is downloadable. queued/processing reserve funds; failed releases the report reservation. A loading supplier page remains processing." }, "priceCents": { "type": "integer", "minimum": 1, "maximum": 100000000, "description": "Accepted purchase price in integer USD cents; reusing an already owned stored report retains its original purchase metadata." }, "currency": { "type": "string", "enum": [ "USD" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "report": { "type": "object", "nullable": true, "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" }, "mimeType": { "type": "string", "enum": [ "application/pdf", "text/html" ] }, "retrievedAt": { "type": "string", "format": "date-time" } }, "required": [ "url", "mimeType", "retrievedAt", "expiresAt" ], "description": "Present only for a validated ready order. URL contains a short-lived scoped ticket; treat it as private and refresh it by polling the same order." } } }, "Account": { "type": "object", "properties": { "company": { "type": "string", "enum": [ "carreport360.com" ] }, "currency": { "type": "string", "enum": [ "USD" ] }, "orderingEnabled": { "type": "boolean" }, "prices": { "type": "object", "properties": { "STORED": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 100000000, "description": "Current USD-cent quote; null if this rate is not configured." }, "FRESH": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 100000000, "description": "Current USD-cent quote; null if this rate is not configured." } }, "required": [ "STORED", "FRESH" ] }, "wallet": { "type": "object", "properties": { "balance": { "type": "integer" }, "held": { "type": "integer" }, "available": { "type": "integer" } }, "required": [ "balance", "held", "available" ], "description": "Integer USD cents. available = balance - held. Pending report prices are held; successful validated completion charges once; failure releases the reservation without a report charge." }, "limits": { "type": "object", "properties": { "requestsPerMinute": { "type": "integer" }, "pendingReports": { "type": "integer" }, "reportsPerDay": { "type": "integer" } }, "required": [ "requestsPerMinute", "pendingReports", "reportsPerDay" ], "description": "Shared company limits across clients and report-ticket downloads: currently 60 authenticated requests/minute, 5 pending orders and 100 new orders per UTC day. Existing order replays do not create additional daily purchases." } }, "required": [ "company", "currency", "orderingEnabled", "prices", "wallet", "limits" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } }, "tags": [ { "name": "Company account" }, { "name": "Report requests" }, { "name": "Report delivery" } ] }