{"openapi":"3.0.0","paths":{"/api/v1/webhooks":{"get":{"operationId":"WebhooksController_listEndpoints","summary":"List customer's webhook endpoints","parameters":[],"responses":{"200":{"description":"List of customer webhook endpoints","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpointResponseDto"}}}}},"401":{"description":"Unauthorized - Valid JWT token required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized - Valid JWT token required","instance":"/api/v1/webhooks"}}}}},"tags":["Webhooks"],"security":[{"BearerAuth":[]},{"BearerAuth":[]}]},"post":{"operationId":"WebhooksController_createEndpoint","summary":"Create a new webhook endpoint","parameters":[],"requestBody":{"required":true,"description":"Webhook endpoint creation payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookDto"}}}},"responses":{"201":{"description":"Webhook endpoint created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointResponseDto"}}}},"400":{"description":"Bad Request - Validation error in request payload","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/bad-request","title":"Bad Request","status":400,"detail":"Bad Request - Validation error in request payload","instance":"/api/v1/webhooks"}}}},"401":{"description":"Unauthorized - Valid JWT token required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized - Valid JWT token required","instance":"/api/v1/webhooks"}}}},"422":{"description":"Unprocessable Entity - SSRF validation failed or non-HTTPS URL","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unprocessable-entity","title":"Unprocessable Entity","status":422,"detail":"Unprocessable Entity - SSRF validation failed or non-HTTPS URL","instance":"/api/v1/webhooks"}}}}},"tags":["Webhooks"],"security":[{"BearerAuth":[]},{"BearerAuth":[]}]}},"/api/v1/webhooks/{id}":{"get":{"operationId":"WebhooksController_getEndpoint","summary":"Get a specific webhook endpoint","parameters":[{"name":"id","required":true,"in":"path","description":"Webhook endpoint UUID","schema":{"example":"ep_10fa67f1-7df2-4ce0-819a-324c5683b544","type":"string"}}],"responses":{"200":{"description":"Webhook endpoint details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointResponseDto"}}}},"401":{"description":"Unauthorized - Valid JWT token required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized - Valid JWT token required","instance":"/api/v1/webhooks/{id}"}}}},"404":{"description":"Endpoint not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/not-found","title":"Not Found","status":404,"detail":"Endpoint not found","instance":"/api/v1/webhooks/{id}"}}}}},"tags":["Webhooks"],"security":[{"BearerAuth":[]},{"BearerAuth":[]}]},"patch":{"operationId":"WebhooksController_updateEndpoint","summary":"Update a webhook endpoint","parameters":[{"name":"id","required":true,"in":"path","description":"Webhook endpoint UUID","schema":{"example":"ep_10fa67f1-7df2-4ce0-819a-324c5683b544","type":"string"}}],"requestBody":{"required":true,"description":"Webhook endpoint update payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookDto"}}}},"responses":{"200":{"description":"Webhook endpoint updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointResponseDto"}}}},"400":{"description":"Bad Request - Validation error in request payload","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/bad-request","title":"Bad Request","status":400,"detail":"Bad Request - Validation error in request payload","instance":"/api/v1/webhooks/{id}"}}}},"401":{"description":"Unauthorized - Valid JWT token required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized - Valid JWT token required","instance":"/api/v1/webhooks/{id}"}}}},"404":{"description":"Endpoint not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/not-found","title":"Not Found","status":404,"detail":"Endpoint not found","instance":"/api/v1/webhooks/{id}"}}}},"422":{"description":"Unprocessable Entity - SSRF validation failed on updated target URL","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unprocessable-entity","title":"Unprocessable Entity","status":422,"detail":"Unprocessable Entity - SSRF validation failed on updated target URL","instance":"/api/v1/webhooks/{id}"}}}}},"tags":["Webhooks"],"security":[{"BearerAuth":[]},{"BearerAuth":[]}]},"delete":{"operationId":"WebhooksController_deleteEndpoint","summary":"Delete a webhook endpoint","parameters":[{"name":"id","required":true,"in":"path","description":"Webhook endpoint UUID","schema":{"example":"ep_10fa67f1-7df2-4ce0-819a-324c5683b544","type":"string"}}],"responses":{"200":{"description":"Webhook endpoint deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeleteResponseDto"}}}},"401":{"description":"Unauthorized - Valid JWT token required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized - Valid JWT token required","instance":"/api/v1/webhooks/{id}"}}}},"404":{"description":"Endpoint not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/not-found","title":"Not Found","status":404,"detail":"Endpoint not found","instance":"/api/v1/webhooks/{id}"}}}}},"tags":["Webhooks"],"security":[{"BearerAuth":[]},{"BearerAuth":[]}]}},"/api/v1/webhooks/{id}/deliveries":{"get":{"operationId":"WebhooksController_getDeliveries","summary":"List recent deliveries for a webhook endpoint","parameters":[{"name":"id","required":true,"in":"path","description":"Webhook endpoint UUID","schema":{"example":"ep_10fa67f1-7df2-4ce0-819a-324c5683b544","type":"string"}}],"responses":{"200":{"description":"List of recent delivery attempts","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDeliveryResponseDto"}}}}},"401":{"description":"Unauthorized - Valid JWT token required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized - Valid JWT token required","instance":"/api/v1/webhooks/{id}/deliveries"}}}},"404":{"description":"Endpoint not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/not-found","title":"Not Found","status":404,"detail":"Endpoint not found","instance":"/api/v1/webhooks/{id}/deliveries"}}}}},"tags":["Webhooks"],"security":[{"BearerAuth":[]},{"BearerAuth":[]}]}},"/api/v1/webhooks/{id}/test":{"post":{"operationId":"WebhooksController_testEndpoint","summary":"Dispatch a test webhook event to an endpoint","parameters":[{"name":"id","required":true,"in":"path","description":"Webhook endpoint UUID","schema":{"example":"ep_10fa67f1-7df2-4ce0-819a-324c5683b544","type":"string"}}],"responses":{"200":{"description":"Test webhook event dispatched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestDispatchResponseDto"}}}},"401":{"description":"Unauthorized - Valid JWT token required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized - Valid JWT token required","instance":"/api/v1/webhooks/{id}/test"}}}},"404":{"description":"Endpoint not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/not-found","title":"Not Found","status":404,"detail":"Endpoint not found","instance":"/api/v1/webhooks/{id}/test"}}}}},"tags":["Webhooks"],"security":[{"BearerAuth":[]},{"BearerAuth":[]}]}},"/api/v1/devices/brands":{"get":{"operationId":"DevicesController_getBrands","summary":"List supported brands and serial number format hints","parameters":[],"responses":{"200":{"description":"Supported brands collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandsResponseDto"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized - Missing or invalid API key","instance":"/api/v1/devices/brands"}}}},"403":{"description":"Forbidden - Client IP address not whitelisted","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/forbidden","title":"Forbidden","status":403,"detail":"Forbidden - Client IP address not whitelisted","instance":"/api/v1/devices/brands"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/too-many-requests","title":"Too Many Requests","status":429,"detail":"Too Many Requests - Rate limit exceeded","instance":"/api/v1/devices/brands"}}}}},"tags":["Devices"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}]}},"/api/v1/devices/lookup":{"post":{"operationId":"DevicesController_lookup","summary":"Synchronous single device serial lookup","parameters":[{"name":"idempotency-key","required":true,"in":"header","description":"Unique idempotency key","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Single device serial and brand lookup payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupRequestDto"}}}},"responses":{"200":{"description":"Device warranty details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncLookupResponseDto"}}}},"202":{"description":"Lookup accepted for asynchronous processing (timeout fallback)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncTimeoutResponseDto"}}}},"400":{"description":"Bad Request - Missing Idempotency-Key or validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/bad-request","title":"Bad Request","status":400,"detail":"Bad Request - Missing Idempotency-Key or validation error","instance":"/api/v1/devices/lookup"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized - Missing or invalid API key","instance":"/api/v1/devices/lookup"}}}},"402":{"description":"Payment Required - Insufficient credits","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/payment-required","title":"Payment Required","status":402,"detail":"Payment Required - Insufficient credits","instance":"/api/v1/devices/lookup"}}}},"403":{"description":"Forbidden - Client IP address not whitelisted","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/forbidden","title":"Forbidden","status":403,"detail":"Forbidden - Client IP address not whitelisted","instance":"/api/v1/devices/lookup"}}}},"409":{"description":"Conflict - Idempotency key reused with different payload","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/conflict","title":"Conflict","status":409,"detail":"Conflict - Idempotency key reused with different payload","instance":"/api/v1/devices/lookup"}}}},"422":{"description":"Manufacturer requires corrected input, a product number, or verification","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unprocessable-entity","title":"Unprocessable Entity","status":422,"detail":"Manufacturer requires corrected input, a product number, or verification","instance":"/api/v1/devices/lookup"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/too-many-requests","title":"Too Many Requests","status":429,"detail":"Too Many Requests - Rate limit exceeded","instance":"/api/v1/devices/lookup"}}}},"503":{"description":"Service Unavailable - Provider failure or concurrent sync wait limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/service-unavailable","title":"Service Unavailable","status":503,"detail":"Service Unavailable - Provider failure or concurrent sync wait limit exceeded","instance":"/api/v1/devices/lookup"}}}}},"tags":["Devices"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}]}},"/api/v1/devices/auto-detect":{"post":{"operationId":"DevicesController_autoDetect","summary":"Synchronous single device lookup with automatic brand detection","parameters":[{"name":"idempotency-key","required":true,"in":"header","description":"Unique idempotency key","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Auto-detection lookup payload with optional candidate brands","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutoDetectRequestDto"}}}},"responses":{"200":{"description":"Device warranty details with detected brand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncLookupResponseDto"}}}},"202":{"description":"Lookup accepted for asynchronous processing (timeout fallback)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncTimeoutResponseDto"}}}},"400":{"description":"Bad Request - Missing Idempotency-Key or validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/bad-request","title":"Bad Request","status":400,"detail":"Bad Request - Missing Idempotency-Key or validation error","instance":"/api/v1/devices/auto-detect"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized - Missing or invalid API key","instance":"/api/v1/devices/auto-detect"}}}},"402":{"description":"Payment Required - Insufficient credits","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/payment-required","title":"Payment Required","status":402,"detail":"Payment Required - Insufficient credits","instance":"/api/v1/devices/auto-detect"}}}},"403":{"description":"Forbidden - Client IP address not whitelisted","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/forbidden","title":"Forbidden","status":403,"detail":"Forbidden - Client IP address not whitelisted","instance":"/api/v1/devices/auto-detect"}}}},"409":{"description":"Conflict - Idempotency key reused with different payload","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/conflict","title":"Conflict","status":409,"detail":"Conflict - Idempotency key reused with different payload","instance":"/api/v1/devices/auto-detect"}}}},"422":{"description":"Manufacturer requires corrected input, a product number, or verification","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unprocessable-entity","title":"Unprocessable Entity","status":422,"detail":"Manufacturer requires corrected input, a product number, or verification","instance":"/api/v1/devices/auto-detect"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/too-many-requests","title":"Too Many Requests","status":429,"detail":"Too Many Requests - Rate limit exceeded","instance":"/api/v1/devices/auto-detect"}}}},"503":{"description":"Service Unavailable - Provider failure or concurrent sync wait limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/service-unavailable","title":"Service Unavailable","status":503,"detail":"Service Unavailable - Provider failure or concurrent sync wait limit exceeded","instance":"/api/v1/devices/auto-detect"}}}}},"tags":["Devices"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}]}},"/api/v1/devices/bulk":{"post":{"operationId":"DevicesController_bulk","summary":"Asynchronous batch scan submission (up to 500 items)","description":"Each item is scanned using its own brand. Omitted brands inherit the first specified brand or lenovo. If callbackUrl is supplied, a POST notification is sent after every item reaches a terminal state.","parameters":[{"name":"idempotency-key","required":true,"in":"header","description":"Unique idempotency key","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Bulk batch scan payload containing up to 500 devices","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkScanRequestDto"}}}},"responses":{"202":{"description":"Batch accepted for background processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkScanResponseDto"}}}},"400":{"description":"Bad Request - Missing Idempotency-Key or invalid items payload","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/bad-request","title":"Bad Request","status":400,"detail":"Bad Request - Missing Idempotency-Key or invalid items payload","instance":"/api/v1/devices/bulk"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized - Missing or invalid API key","instance":"/api/v1/devices/bulk"}}}},"402":{"description":"Payment Required - Insufficient credits","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/payment-required","title":"Payment Required","status":402,"detail":"Payment Required - Insufficient credits","instance":"/api/v1/devices/bulk"}}}},"403":{"description":"Forbidden - Client IP address not whitelisted","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/forbidden","title":"Forbidden","status":403,"detail":"Forbidden - Client IP address not whitelisted","instance":"/api/v1/devices/bulk"}}}},"409":{"description":"Conflict - Idempotency key reused with different payload","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/conflict","title":"Conflict","status":409,"detail":"Conflict - Idempotency key reused with different payload","instance":"/api/v1/devices/bulk"}}}},"422":{"description":"Unprocessable Entity - Invalid webhook callback URL","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unprocessable-entity","title":"Unprocessable Entity","status":422,"detail":"Unprocessable Entity - Invalid webhook callback URL","instance":"/api/v1/devices/bulk"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/too-many-requests","title":"Too Many Requests","status":429,"detail":"Too Many Requests - Rate limit exceeded","instance":"/api/v1/devices/bulk"}}}}},"tags":["Devices"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}]}},"/api/v1/devices/scans/{batchId}":{"get":{"operationId":"DevicesController_getBatchStatus","summary":"Query status and paginated results for a scan batch","parameters":[{"name":"batchId","required":true,"in":"path","description":"Batch scan UUID identifier","schema":{"example":"6c40a5a3-764f-4d33-91ee-b6eef7699411","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number for items pagination","schema":{"example":1,"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page (1-100)","schema":{"example":20,"type":"string"}}],"responses":{"200":{"description":"Batch status details and item results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchStatusResponseDto"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized - Missing or invalid API key","instance":"/api/v1/devices/scans/{batchId}"}}}},"403":{"description":"Forbidden - Batch belongs to another customer account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/forbidden","title":"Forbidden","status":403,"detail":"Forbidden - Batch belongs to another customer account","instance":"/api/v1/devices/scans/{batchId}"}}}},"404":{"description":"Not Found - Batch not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/not-found","title":"Not Found","status":404,"detail":"Not Found - Batch not found","instance":"/api/v1/devices/scans/{batchId}"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/too-many-requests","title":"Too Many Requests","status":429,"detail":"Too Many Requests - Rate limit exceeded","instance":"/api/v1/devices/scans/{batchId}"}}}}},"tags":["Devices"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}]}},"/api/v1/account/balance":{"get":{"operationId":"AccountController_getBalance","summary":"Retrieve current available scan credit balance","parameters":[],"responses":{"200":{"description":"Current account scan balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountBalanceResponseDto"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized - Missing or invalid API key","instance":"/api/v1/account/balance"}}}},"403":{"description":"Forbidden - Client IP address not whitelisted","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/forbidden","title":"Forbidden","status":403,"detail":"Forbidden - Client IP address not whitelisted","instance":"/api/v1/account/balance"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/too-many-requests","title":"Too Many Requests","status":429,"detail":"Too Many Requests - Rate limit exceeded","instance":"/api/v1/account/balance"}}}}},"tags":["Account"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}]}},"/api/v1/account/usage":{"get":{"operationId":"AccountController_getUsage","summary":"Retrieve API usage and credit consumption metrics","parameters":[],"responses":{"200":{"description":"Aggregated usage telemetry metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountUsageResponseDto"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Unauthorized - Missing or invalid API key","instance":"/api/v1/account/usage"}}}},"403":{"description":"Forbidden - Client IP address not whitelisted","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/forbidden","title":"Forbidden","status":403,"detail":"Forbidden - Client IP address not whitelisted","instance":"/api/v1/account/usage"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Rfc7807ProblemDetailsDto"},"example":{"type":"https://api.checkwarranty.io/errors/too-many-requests","title":"Too Many Requests","status":429,"detail":"Too Many Requests - Rate limit exceeded","instance":"/api/v1/account/usage"}}}}},"tags":["Account"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}]}}},"info":{"title":"CheckWarranty B2B Public API","description":"Programmatic device warranty and information lookup API for Lenovo, HP, Dell, and Apple","version":"1.0","contact":{}},"tags":[{"name":"Devices","description":"Hardware warranty check and bulk lookup endpoints"},{"name":"Account","description":"Credit balance and API usage telemetry"},{"name":"Webhooks","description":"Webhook endpoints management and test delivery"}],"servers":[{"url":"https://checkwarranty.info","description":"Public API gateway"}],"components":{"securitySchemes":{"BearerAuth":{"scheme":"bearer","bearerFormat":"cw_* API key for Devices/Account; JWT for Webhooks","type":"http"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"WebhookEndpointResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique webhook endpoint identifier","example":"ep_10fa67f1-7df2-4ce0-819a-324c5683b544"},"userId":{"type":"string","description":"Owner user identifier","example":"usr_8fbc2301"},"url":{"type":"string","description":"Target HTTPS webhook receiver URL","example":"https://webhook.example.com/checkwarranty-events"},"secret":{"type":"string","description":"Shared HMAC-SHA256 signing secret for payload verification","example":"8fbc2301d0a5b931e9c201824ef08fbc2301d0a5b931e9c201824ef012345678"},"events":{"description":"Subscribed event types","example":["scan.completed"],"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean","description":"Whether the webhook endpoint is active and accepting deliveries","example":true},"failCount":{"type":"number","description":"Consecutive delivery failure count (trips circuit breaker at 10)","example":0},"disabledAt":{"type":"string","description":"Timestamp when endpoint was automatically disabled by circuit breaker","example":null},"createdAt":{"type":"string","description":"Endpoint creation timestamp (ISO 8601)","example":"2026-09-22T12:00:00.000Z"},"updatedAt":{"type":"string","description":"Endpoint last modification timestamp (ISO 8601)","example":"2026-09-22T12:00:00.000Z"}},"required":["id","userId","url","secret","events","isActive","failCount","createdAt","updatedAt"]},"ValidationErrorItemDto":{"type":"object","properties":{"field":{"type":"string","description":"Target request field that caused validation error","example":"serialNumber"},"message":{"type":"string","description":"Validation error description message","example":"serialNumber is required"}},"required":["message"]},"CreditsBreakdownDto":{"type":"object","properties":{"used":{"type":"number","description":"Actual credits captured for this operation (0 for free history or refunded results). An idempotent replay repeats the original operation result without a new charge.","example":1},"remaining":{"type":"number","description":"Remaining account scan balance","example":99}},"required":["used","remaining"]},"Rfc7807ProblemDetailsDto":{"type":"object","properties":{"type":{"type":"string","description":"URI reference identifying the problem type","example":"https://api.checkwarranty.io/errors/bad-request"},"title":{"type":"string","description":"Short summary of the problem type","example":"Bad Request"},"status":{"type":"number","description":"HTTP status code","example":400},"detail":{"type":"string","description":"Human-readable explanation specific to this occurrence","example":"A valid Idempotency-Key header is required"},"instance":{"type":"string","description":"URI reference identifying the specific occurrence","example":"/api/v1/devices/lookup"},"errors":{"description":"List of specific validation errors","type":"array","items":{"$ref":"#/components/schemas/ValidationErrorItemDto"}},"error":{"type":"string","description":"Machine error code for backward compatibility","example":"bad_request"},"batchId":{"type":"string","description":"Scan batch associated with a terminal lookup failure"},"credits":{"description":"Actual credit outcome of the failed operation","allOf":[{"$ref":"#/components/schemas/CreditsBreakdownDto"}]}},"required":["type","title","status","detail"]},"CreateWebhookDto":{"type":"object","properties":{"url":{"type":"string","description":"Target webhook HTTPS URL","example":"https://webhook-receiver.example.com/checkwarranty-events"},"events":{"description":"Event types to subscribe to","example":["scan.completed"],"default":["scan.completed"],"type":"array","items":{"type":"string"}}},"required":["url"]},"UpdateWebhookDto":{"type":"object","properties":{"url":{"type":"string","description":"Updated webhook HTTPS target URL","example":"https://webhook-receiver.example.com/checkwarranty-events"},"events":{"description":"Updated event types to subscribe to","example":["scan.completed","scan.failed"],"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean","description":"Enable or disable the webhook endpoint","example":true}}},"WebhookDeleteResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the deletion was successful","example":true},"message":{"type":"string","description":"Status message confirming deletion","example":"Webhook endpoint deleted successfully"}},"required":["success","message"]},"WebhookDeliveryResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique delivery attempt identifier","example":"deliv_a1b2c3d4e5f6"},"endpointId":{"type":"string","description":"Associated webhook endpoint identifier","example":"ep_10fa67f1-7df2-4ce0-819a-324c5683b544"},"scanId":{"type":"string","description":"Related scan job identifier if event was triggered by a scan","example":"scan-6c40a5a3-764f-4d33-91ee-b6eef7699411"},"payload":{"type":"object","description":"Dispatched event payload structure","example":{"id":"evt_test_123","type":"test.ping","createdAt":"2026-09-22T12:05:00.000Z","data":{"message":"Webhook delivery verification event"}}},"responseCode":{"type":"number","description":"HTTP response code received from target server","example":200},"responseBody":{"type":"string","description":"Response body snippet or error message returned by target","example":"{\"received\":true}"},"status":{"type":"string","description":"Delivery attempt status","enum":["success","failed"],"example":"success"},"createdAt":{"type":"string","description":"Delivery timestamp (ISO 8601)","example":"2026-09-22T12:05:00.000Z"},"completedAt":{"type":"string","description":"Delivery completion timestamp (ISO 8601)","example":"2026-09-22T12:05:01.000Z"}},"required":["id","endpointId","payload","status","createdAt"]},"WebhookTestDispatchResponseDto":{"type":"object","properties":{"message":{"type":"string","description":"Test dispatch status message","example":"Test webhook dispatched"},"delivery":{"description":"Detailed report of the dispatched test delivery","allOf":[{"$ref":"#/components/schemas/WebhookDeliveryResponseDto"}]}},"required":["message","delivery"]},"BrandHintDto":{"type":"object","properties":{"brand":{"type":"string","description":"Brand identifier","example":"lenovo"},"id":{"type":"string","description":"Alias identifier matching brand","example":"lenovo"},"name":{"type":"string","description":"Brand display name","example":"Lenovo"},"serialPattern":{"type":"string","description":"Regular expression pattern for serial number format","example":"^[A-Z0-9]{8}$"},"example":{"type":"string","description":"Example serial number","example":"R90J38ET"},"sample":{"type":"string","description":"Sample serial number","example":"R90J38ET"},"description":{"type":"string","description":"Description of format","example":"Lenovo 8-character alphanumeric serial number (e.g., PF4A1234)"},"formats":{"description":"Array of format hints","example":["8 alphanumeric characters for ThinkPad","7 alphanumeric characters for IdeaPad"],"type":"array","items":{"type":"string"}}},"required":["brand","id","name","serialPattern","example","sample","description","formats"]},"BrandsResponseDto":{"type":"object","properties":{"brands":{"description":"List of supported brands with format hints","type":"array","items":{"$ref":"#/components/schemas/BrandHintDto"}}},"required":["brands"]},"LookupRequestDto":{"type":"object","properties":{"brand":{"type":"string","description":"Hardware manufacturer brand","enum":["lenovo","hp","dell","apple"],"example":"lenovo"},"serialNumber":{"type":"string","description":"Device serial number","example":"PF4TEST001"},"pn":{"type":"string","description":"Product Number (required for some HP devices with ambiguous serials)","example":"5YN09UT"},"forceRefresh":{"type":"boolean","description":"Force bypass cache and query live vendor servers","default":false,"example":false}},"required":["brand","serialNumber"]},"DataQualityDto":{"type":"object","properties":{"modelKnown":{"type":"boolean","description":"True when a specific device model is available"},"warrantyVerified":{"type":"boolean","description":"True when manufacturer warranty status is verified; completed alone does not guarantee coverage data"},"warrantySource":{"type":"string","nullable":true,"description":"Warranty data source, or unverified for a failed live coverage check"},"limitations":{"description":"Missing or unverified portions of the result","type":"array","items":{"type":"string"}}},"required":["modelKnown","warrantyVerified","limitations"]},"DeviceInfoDto":{"type":"object","properties":{"brand":{"type":"string","description":"Hardware manufacturer brand","example":"lenovo"},"model":{"type":"string","description":"Device marketing or model name","example":"ThinkPad T14 Gen 3"},"serialNumber":{"type":"string","description":"Device serial number","example":"PF4TEST001"},"productNumber":{"type":"string","description":"Product number or machine type model","example":"21CB000VUS"},"manufactureDate":{"type":"string","description":"Manufacture date if reported by vendor","example":"2023-03"},"description":{"type":"string","description":"Detailed device specifications or description","example":"ThinkPad T14 Gen 3 Intel Core i7-1260P 16GB RAM 512GB SSD"}},"required":["brand","serialNumber"]},"WarrantyInfoDto":{"type":"object","properties":{"status":{"type":"string","description":"Warranty status","enum":["active","expired","not_found","unknown"],"example":"active"},"startDate":{"type":"string","description":"Warranty coverage start date (ISO 8601), null when unavailable","nullable":true,"example":"2023-01-15"},"startDateSource":{"type":"string","description":"Present when the start date is estimated from the end date and an explicit warranty term; omitted for unmarked historical dates","enum":["estimated"],"example":"estimated"},"warrantyDurationMonths":{"type":"number","description":"Explicit warranty term used to estimate the start date, in whole months","minimum":1,"example":36},"endDate":{"type":"string","description":"Warranty coverage expiration date (ISO 8601), null when unavailable","nullable":true,"example":"2026-01-15"},"coverageType":{"type":"string","description":"Plan or entitlement name","example":"Premier Support with Onsite NBD"},"details":{"type":"object","description":"Additional vendor-specific warranty details","example":{"onsite":true,"parts":true}}},"required":["status"]},"SyncLookupResponseDto":{"type":"object","properties":{"dataQuality":{"$ref":"#/components/schemas/DataQualityDto"},"device":{"description":"Device hardware information","allOf":[{"$ref":"#/components/schemas/DeviceInfoDto"}]},"warranty":{"description":"Warranty status and dates","allOf":[{"$ref":"#/components/schemas/WarrantyInfoDto"}]},"credits":{"description":"Credit consumption breakdown","allOf":[{"$ref":"#/components/schemas/CreditsBreakdownDto"}]},"status":{"type":"string","description":"Overall lookup status","example":"completed"},"message":{"type":"string","description":"Human-readable result summary","example":"Warranty details retrieved successfully"},"batchId":{"type":"string","description":"Internal batch identifier","example":"6c40a5a3-764f-4d33-91ee-b6eef7699411"}},"required":["device","warranty","credits"]},"SyncTimeoutResponseDto":{"type":"object","properties":{"batchId":{"type":"string","description":"Batch ID for asynchronous status querying","example":"6c40a5a3-764f-4d33-91ee-b6eef7699411"},"status":{"type":"string","description":"Processing status","enum":["in_progress","pending"],"example":"in_progress"},"message":{"type":"string","description":"Instruction message","example":"Scan processing is continuing asynchronously. Retrieve the result using the URL in the Location header."}},"required":["batchId","status","message"]},"AutoDetectRequestDto":{"type":"object","properties":{"serialNumber":{"type":"string","description":"Device serial number","example":"PF4AUTODETECT1"},"pn":{"type":"string","description":"Product Number (required for some HP devices with ambiguous serials)","example":"5YN09UT"},"candidates":{"description":"Optional subset of candidate brands to probe","example":["lenovo","hp","dell","apple"],"type":"array","items":{"type":"string"}},"forceRefresh":{"type":"boolean","description":"Force bypass cache and query live vendor servers","default":false,"example":false}},"required":["serialNumber"]},"BulkItemInputDto":{"type":"object","properties":{"serialNumber":{"type":"string","description":"Device serial number","example":"PF4BULK001"},"brand":{"type":"string","description":"Brand for this item. If omitted, inherits the first specified item brand, or lenovo when none is specified. Mixed-brand batches are supported.","enum":["lenovo","hp","dell","apple"],"example":"lenovo"},"pn":{"type":"string","description":"Product Number (required for some HP devices with ambiguous serials)","example":"5YN09UT"},"clientRefId":{"type":"string","description":"Client reference identifier for tracing","example":"asset-tag-991"}},"required":["serialNumber"]},"BulkScanRequestDto":{"type":"object","properties":{"items":{"description":"List of devices to scan (max 500 items)","type":"array","items":{"$ref":"#/components/schemas/BulkItemInputDto"}},"callbackUrl":{"type":"string","description":"Optional public HTTPS URL receiving one POST with a scan.completed event after all batch items finish. A failed delivery is retried; redirects are not followed.","example":"https://webhook.example.com/b2b-events"}},"required":["items"]},"BulkScanResponseDto":{"type":"object","properties":{"batchId":{"type":"string","description":"Unique batch scan identifier","example":"6c40a5a3-764f-4d33-91ee-b6eef7699411"},"itemCount":{"type":"number","description":"Number of submitted serial numbers","example":2},"status":{"type":"string","description":"Batch status","enum":["in_progress","pending"],"example":"in_progress"},"estimatedCredits":{"type":"number","description":"Estimated credit cost","example":2}},"required":["batchId","itemCount","status"]},"BatchProgressDto":{"type":"object","properties":{"total":{"type":"number","description":"Total items in batch","example":10},"completed":{"type":"number","description":"Successful items with useful data","example":8},"notFound":{"type":"number","description":"Items not found; no credits charged","example":1},"failed":{"type":"number","description":"Failed items","example":1},"pending":{"type":"number","description":"Pending or in-flight items","example":1}},"required":["total","completed","notFound","failed","pending"]},"BatchItemStatusDto":{"type":"object","properties":{"dataQuality":{"$ref":"#/components/schemas/DataQualityDto"},"id":{"type":"string","description":"Scan serial ID","example":"item-8fbc2301"},"serialNumber":{"type":"string","description":"Device serial number","example":"PF4BULK001"},"brand":{"type":"string","description":"Brand","example":"lenovo"},"clientRefId":{"type":"string","description":"Client reference ID","example":"asset-tag-991"},"status":{"type":"string","description":"Item processing status","enum":["pending","in_progress","completed","failed","not_found"],"example":"completed"},"device":{"description":"Device details if completed","allOf":[{"$ref":"#/components/schemas/DeviceInfoDto"}]},"warranty":{"description":"Warranty info if completed","allOf":[{"$ref":"#/components/schemas/WarrantyInfoDto"}]},"error":{"type":"string","description":"Failure reason or device-not-found outcome","example":null}},"required":["serialNumber","status"]},"BatchStatusResponseDto":{"type":"object","properties":{"batchId":{"type":"string","description":"Unique batch scan identifier","example":"6c40a5a3-764f-4d33-91ee-b6eef7699411"},"status":{"type":"string","description":"Overall batch status","enum":["pending","in_progress","completed","failed","partial"],"example":"completed"},"progress":{"description":"Batch progress counters","allOf":[{"$ref":"#/components/schemas/BatchProgressDto"}]},"items":{"description":"Array of batch item results","type":"array","items":{"$ref":"#/components/schemas/BatchItemStatusDto"}},"createdAt":{"type":"string","description":"Batch creation timestamp (ISO 8601)","example":"2026-09-22T12:00:00.000Z"},"completedAt":{"type":"string","description":"Batch completion timestamp (ISO 8601)","example":"2026-09-22T12:00:05.000Z"}},"required":["batchId","status","progress","items","createdAt"]},"AccountBalanceResponseDto":{"type":"object","properties":{"reservedCredits":{"type":"number","description":"Credits currently reserved by unfinished scans","example":3},"scanBalance":{"type":"number","description":"Current available scan credits","example":150},"balance":{"type":"number","description":"Alias for scanBalance","example":150},"currency":{"type":"string","description":"Credit unit description","example":"credits"},"userId":{"type":"string","description":"Account user ID","example":"usr_8fbc2301"}},"required":["reservedCredits","scanBalance","currency"]},"AccountUsage24hStatsDto":{"type":"object","properties":{"requests":{"type":"number","description":"Total requests in last 24h","example":140},"creditsUsed":{"type":"number","description":"Account credits captured in last 24h","example":95}},"required":["requests","creditsUsed"]},"AccountUsageResponseDto":{"type":"object","properties":{"totalRequests":{"type":"number","description":"Total requests logged","example":1250},"requests":{"type":"number","description":"Alias for totalRequests","example":1250},"total":{"type":"number","description":"Alias for totalRequests","example":1250},"successRate":{"type":"number","description":"Percentage of successful requests (0-100)","example":98.4},"creditsUsed":{"type":"number","description":"Total account credits captured, including completed website scans","example":850},"used":{"type":"number","description":"Alias for creditsUsed","example":850},"period":{"type":"string","description":"Reporting period","example":"all_time"},"recent24h":{"description":"Recent 24 hour stats","allOf":[{"$ref":"#/components/schemas/AccountUsage24hStatsDto"}]}},"required":["totalRequests","successRate","creditsUsed"]}}}}