{ "openapi": "3.1.0", "info": { "title": "CredCheck API", "version": "1.0.0", "description": "Product authenticity verification. Consumer verification is public; the manufacturer API uses scoped API keys (`X-Api-Key`). All errors share one envelope; 429 and 503 include Retry-After." }, "servers": [ { "url": "https://api.credcheck.app", "description": "Production (cc_live_ keys)" }, { "url": "https://api.sandbox.credcheck.app", "description": "Sandbox (cc_test_ keys)" } ], "tags": [ { "name": "Verification" }, { "name": "Products" }, { "name": "Recalls" }, { "name": "Codes" }, { "name": "Analytics" }, { "name": "Alerts" }, { "name": "Consumer reports" }, { "name": "Webhooks" }, { "name": "Platform" } ], "paths": { "/v1/verify": { "post": { "tags": ["Verification"], "summary": "Verify a product code", "description": "Checks a code (or a full QR URL). Always answers 200 with an outcome for well-formed requests — an unknown code is `suspected_counterfeit`, never an error. Safe to retry. `unable_to_verify` and service errors never imply product risk. Public callers can report `channel` as `web`, `mobile_app` or `api`; any other value is recorded as `web` (SMS, USSD and WhatsApp are reserved for CredCheck gateways).", "operationId": "postV1Verify", "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 3, "maxLength": 200 }, "channel": { "type": "string", "enum": ["mobile_app", "web", "ussd", "sms", "whatsapp", "api", "retail_sdk"], "default": "web" }, "signature": { "type": "string", "maxLength": 64 }, "deviceId": { "type": "string", "maxLength": 200 }, "location": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "consent": { "type": "boolean" } }, "additionalProperties": false }, "captchaToken": { "type": "string" }, "sellerCode": { "type": "string", "maxLength": 40 } }, "required": ["code"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResult" } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/verify/{ref}": { "get": { "tags": ["Verification"], "summary": "Re-open a verification receipt", "description": "A record of an earlier check (24 hours). It does not check the product in hand.", "operationId": "getV1VerifyRef", "security": [], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The stored result, with receipt view metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResult" } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reports": { "post": { "tags": ["Verification"], "summary": "Report a concern about a product", "operationId": "postV1Reports", "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "referenceId": { "type": "string", "maxLength": 64 }, "type": { "type": "string", "enum": ["fake", "damaged", "wrong_packaging", "suspicious_seller", "other"] }, "description": { "type": "string", "maxLength": 2000 }, "deviceId": { "type": "string", "maxLength": 128 }, "location": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lon": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": ["lat", "lon"], "additionalProperties": false } }, "required": ["type"], "additionalProperties": false } } } }, "responses": { "202": { "description": "Report accepted; returns a public reference", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": ["Consumer reports"], "summary": "List consumer reports", "operationId": "getV1Reports", "x-credcheck-scope": "reports:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["submitted", "reviewing", "actioned", "dismissed"] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["fake", "damaged", "wrong_packaging", "suspicious_seller", "other"] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Reports", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/products": { "get": { "tags": ["Products"], "summary": "List products", "operationId": "getV1Products", "x-credcheck-scope": "products:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 60 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["draft", "active", "discontinued", "recalled"] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } } ], "responses": { "200": { "description": "Cursor-paginated products", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": ["Products"], "summary": "Create a product", "operationId": "postV1Products", "x-credcheck-scope": "products:write", "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "sku": { "type": "string", "minLength": 1, "maxLength": 80 }, "gtin": { "type": "string", "maxLength": 14, "pattern": "^\\d*$" }, "category": { "type": "string", "minLength": 2, "maxLength": 60 }, "description": { "type": "string", "maxLength": 4000 }, "specs": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } }, "packaging": { "type": "object", "additionalProperties": {} }, "orgUnitId": { "type": "string", "format": "uuid" } }, "required": ["name", "sku", "category"], "additionalProperties": false } } } }, "responses": { "201": { "description": "The created product", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/products/export.csv": { "get": { "tags": ["Products"], "summary": "Export products as CSV", "operationId": "getV1ProductsExportCsv", "x-credcheck-scope": "products:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Streamed CSV", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/products/{id}": { "get": { "tags": ["Products"], "summary": "Get a product", "operationId": "getV1ProductsId", "x-credcheck-scope": "products:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The product with media", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": ["Products"], "summary": "Update a product", "operationId": "patchV1ProductsId", "x-credcheck-scope": "products:write", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "sku": { "type": "string", "minLength": 1, "maxLength": 80 }, "gtin": { "type": "string", "maxLength": 14, "pattern": "^\\d*$" }, "category": { "type": "string", "minLength": 2, "maxLength": 60 }, "description": { "type": "string", "maxLength": 4000 }, "specs": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } }, "packaging": { "type": "object", "additionalProperties": {} }, "orgUnitId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["draft", "active", "discontinued"] }, "verificationEnabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The updated product", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Products"], "summary": "Delete (discontinue) a product", "operationId": "deleteV1ProductsId", "x-credcheck-scope": "products:write", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/products/{id}/batches": { "get": { "tags": ["Products"], "summary": "List a product’s batches", "operationId": "getV1ProductsIdBatches", "x-credcheck-scope": "products:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batches", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": ["Products"], "summary": "Create a batch", "operationId": "postV1ProductsIdBatches", "x-credcheck-scope": "products:write", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batchNumber": { "type": "string", "minLength": 1, "maxLength": 80 }, "manufacturedDate": { "type": "string", "format": "date" }, "expiryDate": { "type": "string", "format": "date" }, "productionSite": { "type": "string", "maxLength": 120 }, "quantity": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 1000000000 } }, "required": ["batchNumber"], "additionalProperties": false } } } }, "responses": { "201": { "description": "The created batch", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/batches/{id}": { "get": { "tags": ["Products"], "summary": "Get a batch with stats", "operationId": "getV1BatchesId", "x-credcheck-scope": "products:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch with codes generated, verified and suspicious counts", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/batches/{id}/recall": { "post": { "tags": ["Recalls"], "summary": "Recall a batch", "description": "Irreversible. Requires the batch number as confirmation. Consumers verifying affected codes are told to stop using the product.", "operationId": "postV1BatchesIdRecall", "x-credcheck-scope": "recalls:write", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 5, "maxLength": 1000 }, "classification": { "type": "string", "enum": ["class_i", "class_ii", "class_iii"] }, "consumerMessage": { "type": "string", "maxLength": 1000 }, "replacementInfo": { "type": "string", "maxLength": 1000 }, "confirmBatchNumber": { "type": "string", "minLength": 1 } }, "required": ["reason", "classification", "confirmBatchNumber"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recall initiated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/codes/generate": { "post": { "tags": ["Codes"], "summary": "Generate codes for a batch", "description": "Starts an asynchronous job. Send an `idempotencyKey` so retries never duplicate a job.", "operationId": "postV1CodesGenerate", "x-credcheck-scope": "codes:write", "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batchId": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 5000000 }, "codeType": { "type": "string", "enum": ["qr", "serial", "scratch", "nfc", "datamatrix", "barcode"], "default": "qr" }, "formatConfig": { "type": "object", "additionalProperties": {} }, "regionLock": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "maxItems": 50 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 120 } }, "required": ["batchId", "quantity"], "additionalProperties": false } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/codes/jobs": { "get": { "tags": ["Codes"], "summary": "List generation jobs", "operationId": "getV1CodesJobs", "x-credcheck-scope": "codes:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "batchId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Jobs", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/codes/jobs/{id}": { "get": { "tags": ["Codes"], "summary": "Get a generation job", "operationId": "getV1CodesJobsId", "x-credcheck-scope": "codes:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job progress and deliverable status", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/codes/jobs/{id}/download": { "get": { "tags": ["Codes"], "summary": "Download the code deliverable (once)", "description": "Plaintext serials. Single use and audited; requires the `codes:export` scope.", "operationId": "getV1CodesJobsIdDownload", "x-credcheck-scope": "codes:export", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CSV of serials and QR URLs", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/codes/import": { "post": { "tags": ["Codes"], "summary": "Import existing serials", "operationId": "postV1CodesImport", "x-credcheck-scope": "codes:write", "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batchId": { "type": "string", "format": "uuid" }, "serials": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "minItems": 1, "maxItems": 100000 } }, "required": ["batchId", "serials"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Import summary", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/codes/lookup": { "get": { "tags": ["Codes"], "summary": "Look up a code by serial", "operationId": "getV1CodesLookup", "x-credcheck-scope": "codes:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "serial", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 120 } } ], "responses": { "200": { "description": "Code metadata (never the plaintext)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/codes/stats": { "get": { "tags": ["Codes"], "summary": "Code totals by status and type", "description": "Exact totals for the company, a product (`productId`) or a batch (`batchId`), from maintained counters.", "operationId": "getV1CodesStats", "x-credcheck-scope": "codes:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "productId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "batchId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Totals, scanned count, generation volume and top products", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/codes/bulk-status": { "post": { "tags": ["Codes"], "summary": "Change status of many codes", "operationId": "postV1CodesBulkStatus", "x-credcheck-scope": "codes:write", "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batchId": { "type": "string", "format": "uuid" }, "from": { "type": "string", "enum": ["active", "suspended", "expired", "recalled", "void"] }, "to": { "type": "string", "enum": ["active", "suspended", "expired", "recalled", "void"] }, "reason": { "type": "string", "maxLength": 500 }, "dryRun": { "type": "boolean", "default": true } }, "required": ["batchId", "to"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Affected count", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/codes": { "get": { "tags": ["Codes"], "summary": "List codes", "operationId": "getV1Codes", "x-credcheck-scope": "codes:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "batchId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "productId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["active", "suspended", "expired", "recalled", "void"] } }, { "name": "codeType", "in": "query", "required": false, "schema": { "type": "string", "enum": ["qr", "serial", "scratch", "nfc", "datamatrix", "barcode"] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Cursor-paginated code metadata", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/codes/{id}": { "get": { "tags": ["Codes"], "summary": "Get a code", "operationId": "getV1CodesId", "x-credcheck-scope": "codes:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Code metadata", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/codes/{id}/status": { "post": { "tags": ["Codes"], "summary": "Suspend, void or reactivate a code", "operationId": "postV1CodesIdStatus", "x-credcheck-scope": "codes:write", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["active", "suspended", "expired", "recalled", "void"] }, "reason": { "type": "string", "maxLength": 500 } }, "required": ["status"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/analytics/overview": { "get": { "tags": ["Analytics"], "summary": "Verification overview", "operationId": "getV1AnalyticsOverview", "x-credcheck-scope": "analytics:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": ["7d", "30d", "90d", "12mo"], "default": "30d" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "KPIs for the range", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/analytics/timeseries": { "get": { "tags": ["Analytics"], "summary": "Verifications over time", "operationId": "getV1AnalyticsTimeseries", "x-credcheck-scope": "analytics:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": ["7d", "30d", "90d", "12mo"], "default": "30d" } }, { "name": "bucket", "in": "query", "required": false, "schema": { "type": "string", "enum": ["day", "week", "month"], "default": "day" } }, { "name": "split", "in": "query", "required": false, "schema": { "type": "string", "enum": ["outcome", "channel", "first_repeat", "none"], "default": "none" } } ], "responses": { "200": { "description": "Series", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/analytics/channel-mix": { "get": { "tags": ["Analytics"], "summary": "Verifications by channel", "operationId": "getV1AnalyticsChannelMix", "x-credcheck-scope": "analytics:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": ["7d", "30d", "90d", "12mo"], "default": "30d" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Channel breakdown", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/analytics/geo": { "get": { "tags": ["Analytics"], "summary": "Verifications by place", "operationId": "getV1AnalyticsGeo", "x-credcheck-scope": "analytics:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": ["7d", "30d", "90d", "12mo"], "default": "30d" } }, { "name": "level", "in": "query", "required": false, "schema": { "type": "string", "enum": ["country"], "default": "country" } } ], "responses": { "200": { "description": "Geographic breakdown", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/analytics/authenticity-score": { "get": { "tags": ["Analytics"], "summary": "Authenticity score", "operationId": "getV1AnalyticsAuthenticityScore", "x-credcheck-scope": "analytics:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": ["7d", "30d", "90d", "12mo"], "default": "30d" } } ], "responses": { "200": { "description": "Score and factors", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/analytics/products/{productId}": { "get": { "tags": ["Analytics"], "summary": "Product analytics", "operationId": "getV1AnalyticsProductsProductId", "x-credcheck-scope": "analytics:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": ["7d", "30d", "90d", "12mo"], "default": "30d" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Product KPIs", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/analytics/batches/{batchId}": { "get": { "tags": ["Analytics"], "summary": "Batch analytics", "operationId": "getV1AnalyticsBatchesBatchId", "x-credcheck-scope": "analytics:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": ["7d", "30d", "90d", "12mo"], "default": "30d" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Batch KPIs", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/analytics/events": { "get": { "tags": ["Analytics"], "summary": "List verification events", "operationId": "getV1AnalyticsEvents", "x-credcheck-scope": "analytics:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": ["7d", "30d", "90d", "12mo"], "default": "30d" } }, { "name": "productId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "batchId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "outcome", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "verified", "unable_to_verify", "suspected_counterfeit", "recalled", "expired", "service_error" ] } }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": ["mobile_app", "web", "ussd", "sms", "whatsapp", "api", "retail_sdk"] } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Cursor-paginated events", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/analytics/events/export.csv": { "get": { "tags": ["Analytics"], "summary": "Export verification events", "description": "Streams every event matching the filters as CSV. `cursor` and `limit` are ignored: the export is not paginated.", "operationId": "getV1AnalyticsEventsExportCsv", "x-credcheck-scope": "analytics:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": ["7d", "30d", "90d", "12mo"], "default": "30d" } }, { "name": "productId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "batchId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "outcome", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "verified", "unable_to_verify", "suspected_counterfeit", "recalled", "expired", "service_error" ] } }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": ["mobile_app", "web", "ussd", "sms", "whatsapp", "api", "retail_sdk"] } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Streamed CSV", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/analytics/events/{id}": { "get": { "tags": ["Analytics"], "summary": "Get a verification event", "operationId": "getV1AnalyticsEventsId", "x-credcheck-scope": "analytics:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Event detail", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/fraud/alerts": { "get": { "tags": ["Alerts"], "summary": "List fraud alerts", "operationId": "getV1FraudAlerts", "x-credcheck-scope": "alerts:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["open", "acknowledged", "investigating", "resolved", "false_positive"] } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string", "enum": ["low", "medium", "high", "critical"] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Alerts", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/fraud/alerts/{id}": { "get": { "tags": ["Alerts"], "summary": "Get a fraud alert", "operationId": "getV1FraudAlertsId", "x-credcheck-scope": "alerts:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Alert with evidence", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": ["Alerts"], "summary": "Update an alert’s status", "operationId": "patchV1FraudAlertsId", "x-credcheck-scope": "alerts:write", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["acknowledged", "investigating", "resolved", "false_positive"] }, "assignedTo": { "type": "string", "format": "uuid", "nullable": true }, "resolution": { "type": "string", "maxLength": 500 } }, "required": ["status"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated alert", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reports/counts": { "get": { "tags": ["Consumer reports"], "summary": "Report counts by status", "operationId": "getV1ReportsCounts", "x-credcheck-scope": "reports:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Counts", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reports/{id}": { "get": { "tags": ["Consumer reports"], "summary": "Get a report", "operationId": "getV1ReportsId", "x-credcheck-scope": "reports:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Report with timeline", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reports/{id}/status": { "patch": { "tags": ["Consumer reports"], "summary": "Change a report’s status", "operationId": "patchV1ReportsIdStatus", "x-credcheck-scope": "reports:write", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["submitted", "reviewing", "actioned", "dismissed"] } }, "required": ["status"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reports/{id}/respond": { "post": { "tags": ["Consumer reports"], "summary": "Reply to the consumer", "operationId": "postV1ReportsIdRespond", "x-credcheck-scope": "reports:write", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["message"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Reply sent", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks": { "get": { "tags": ["Webhooks"], "summary": "List webhook endpoints", "operationId": "getV1Webhooks", "x-credcheck-scope": "webhooks:manage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Endpoints (the signing secret is never listed; see `secretHint`)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": ["Webhooks"], "summary": "Create a webhook endpoint", "description": "Public https URLs only. Deliveries are signed: `X-CredCheck-Signature: t=,v1=`.", "operationId": "postV1Webhooks", "x-credcheck-scope": "webhooks:manage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "fraud_alert_created", "fraud_alert_escalated", "recall_initiated", "code_job_completed", "report_received", "usage_threshold", "billing_event", "platform_maintenance" ] }, "minItems": 1 }, "description": { "type": "string", "maxLength": 200 } }, "required": ["url", "events"], "additionalProperties": false } } } }, "responses": { "201": { "description": "The endpoint, including its signing secret", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}": { "patch": { "tags": ["Webhooks"], "summary": "Update a webhook endpoint", "operationId": "patchV1WebhooksId", "x-credcheck-scope": "webhooks:manage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "fraud_alert_created", "fraud_alert_escalated", "recall_initiated", "code_job_completed", "report_received", "usage_threshold", "billing_event", "platform_maintenance" ] }, "minItems": 1 }, "description": { "type": "string", "maxLength": 200 }, "enabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": ["Webhooks"], "summary": "Delete a webhook endpoint", "operationId": "deleteV1WebhooksId", "x-credcheck-scope": "webhooks:manage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted (no body)" }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "tags": ["Webhooks"], "summary": "Rotate the signing secret", "operationId": "postV1WebhooksIdRotateSecret", "x-credcheck-scope": "webhooks:manage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The endpoint with its new signing secret, shown once", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "tags": ["Webhooks"], "summary": "Send a test delivery", "operationId": "postV1WebhooksIdTest", "x-credcheck-scope": "webhooks:manage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Test delivery queued; returns its delivery id", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/deliveries": { "get": { "tags": ["Webhooks"], "summary": "List deliveries", "operationId": "getV1WebhooksDeliveries", "x-credcheck-scope": "webhooks:manage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "endpointId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recent deliveries with status", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/deliveries/{id}/replay": { "post": { "tags": ["Webhooks"], "summary": "Replay a delivery", "operationId": "postV1WebhooksDeliveriesIdReplay", "x-credcheck-scope": "webhooks:manage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Delivery re-queued", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope, or the route is not available to API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not in your company)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/public/status": { "get": { "tags": ["Platform"], "summary": "Service status", "operationId": "getV1PublicStatus", "security": [], "parameters": [], "responses": { "200": { "description": "Component states, 90-day uptime and incidents", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/public/plans": { "get": { "tags": ["Platform"], "summary": "Plans and prices", "operationId": "getV1PublicPlans", "security": [], "parameters": [], "responses": { "200": { "description": "Active plans with current prices", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily overloaded — retry once after Retry-After (code `overloaded`)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Scopes: `products:read` — Read products, batches and batch details; `products:write` — Create, update and delete products and add batches; `recalls:write` — Initiate batch recalls; `codes:read` — Read code metadata and generation jobs (never plaintext serials); `codes:write` — Generate and import codes, change code status; `codes:export` — Download encrypted code deliverables (plaintext serials); `analytics:read` — Read verification analytics; `alerts:read` — Read fraud alerts; `alerts:write` — Update fraud alert status; `reports:read` — Read consumer reports; `reports:write` — Update consumer report status and respond; `webhooks:manage` — Manage webhook endpoints and deliveries" } }, "schemas": { "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string", "example": "insufficient_scope" }, "message": { "type": "string", "example": "This API key needs the \"products:write\" scope for this request." }, "requestId": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } }, "VerifyResult": { "type": "object", "required": ["outcome", "checkedAt", "referenceId", "trust", "actions"], "properties": { "outcome": { "type": "string", "enum": ["verified", "unable_to_verify", "suspected_counterfeit", "recalled", "expired"] }, "checkedAt": { "type": "string", "format": "date-time" }, "referenceId": { "type": "string", "example": "vrf_9f2kQ1x7Lm3pQ8zA" }, "product": { "type": ["object", "null"], "properties": { "name": { "type": "string" }, "brand": { "type": "string" }, "imageUrl": { "type": ["string", "null"] }, "batchNumber": { "type": "string" }, "expiryDate": { "type": ["string", "null"] }, "manufacturerVerified": { "type": "boolean" } } }, "trust": { "type": "object", "properties": { "scanCount": { "type": "integer" }, "firstScan": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } } } } } } } } }