> ## Documentation Index > Fetch the complete documentation index at: https://docs.closient.com/llms.txt > Use this file to discover all available pages before exploring further. # Resolve a QR code URL > Follow the HTTP redirect chain for a QR code URL captured from product packaging and return the final canonical URL plus the intermediate hops. Used by the dual-scan flow: after the operator scans a QR code, the client posts the URL here, displays the resolved value, and (if accepted) calls ``/captures/{id}/save-redirect`` to persist it as a redirect rule on the trade item. Behavior: * Follows up to 10 HTTP 3xx redirects (301/302/303/307/308). * 5-second timeout per the spec; surfaces the error in ``error_message`` rather than failing the request when the URL is unreachable. * HTTPS upgrades (302 → ``https://``) are followed transparently. * meta-refresh HTML redirects are NOT followed in v1 — known limitation; document this in the brand-manager UI. * Tracking-parameter stripping is out of scope for v1; the URL is returned exactly as the final hop reports it. ## OpenAPI ````yaml /openapi/openapi-scanner.json post /scanner/api/v1/resolve-url openapi: 3.1.0 info: title: Scanner API version: 1.0.0 description: > Barcode and product scanning with vision extraction. ## Authentication All endpoints require an API key passed via the `X-API-Key` HTTP header, unless otherwise noted. ``` X-API-Key: csb__ ``` Generate API keys in **Settings > API Keys** in your dashboard, or via the Account API. Session-based (cookie) authentication is also accepted for browser-based access. ## Rate Limits | Tier | Requests / minute | Requests / day | |-------------|-------------------|----------------| | Default | 300 | 10,000 | | Custom | Contact us | Contact us | Rate-limit headers are included on every response so callers can self-throttle without hitting our 429s ("informed governor"): - `RateLimit-Policy` — every active window, e.g. `300;w=60, 10000;w=86400` - `RateLimit-Limit` — quota for the **most-restrictive** currently-active window - `RateLimit-Remaining` — requests left in that window - `RateLimit-Reset` — seconds until that window resets (relative; clock-skew safe) Legacy `X-RateLimit-*` aliases are also emitted for back-compat. `X-RateLimit-Reset` keeps the absolute Unix-timestamp shape to avoid breaking existing consumers. When rate-limited, you receive `429 Too Many Requests` with a `retry_after_seconds` field in the error envelope and a `Retry-After` header. ## Pagination List endpoints return paginated results in this envelope: ```json { "data": [...], "pagination": { "page": 1, "page_size": 25, "total_count": 342, "total_pages": 14, "has_next": true, "has_previous": false } } ``` Use `?page=2&page_size=50` query parameters. Maximum page size is 100. ## Error Responses All errors conform to [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) with `Content-Type: application/problem+json`: ```json { "type": "https://closient.com/docs/errors/not_found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found.", "error_code": "not_found", "retryable": false, "timestamp": "2026-03-31T12:00:00+00:00" } ``` Common error codes: `unauthorized` (401), `forbidden` (403), `not_found` (404), `validation_error` (422), `rate_limited` (429), `internal_error` (500). termsOfService: https://www.closient.com/terms/ servers: - url: https://www.closient.com security: [] tags: - name: Scanner Sessions description: Create and manage barcode scanning sessions. - name: Scanner Captures description: Record barcode scan captures within sessions. - name: Scanner Enrichment description: Enrich scanned items with product data. - name: Scanner Photos description: Manage photos attached to scan sessions. - name: Scanner Upload description: Upload scan data in bulk. - name: Scanner Resolve description: >- Dual-scan QR resolve: follow QR redirect chains and save the canonical URL as a trade-item redirect (C-503). - name: Scanner Freshness description: >- Resolve color-coded freshness-chip thresholds for a scanned GTIN from the GPC-brick category config (C-2987). Anonymous-allowed; consumed by the public /scan/ overlay. externalDocs: description: Closient Documentation url: https://docs.closient.com paths: /scanner/api/v1/resolve-url: post: tags: - Scanner Resolve summary: Resolve a QR code URL description: >- Follow the HTTP redirect chain for a QR code URL captured from product packaging and return the final canonical URL plus the intermediate hops. Used by the dual-scan flow: after the operator scans a QR code, the client posts the URL here, displays the resolved value, and (if accepted) calls ``/captures/{id}/save-redirect`` to persist it as a redirect rule on the trade item. Behavior: * Follows up to 10 HTTP 3xx redirects (301/302/303/307/308). * 5-second timeout per the spec; surfaces the error in ``error_message`` rather than failing the request when the URL is unreachable. * HTTPS upgrades (302 → ``https://``) are followed transparently. * meta-refresh HTML redirects are NOT followed in v1 — known limitation; document this in the brand-manager UI. * Tracking-parameter stripping is out of scope for v1; the URL is returned exactly as the final hop reports it. operationId: apps_scanner_api_resolve_endpoints_resolve_url_endpoint parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/UrlResolveRequestSchema' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UrlResolveResponseSchema' '422': description: Unprocessable Content content: application/json: schema: additionalProperties: true title: Response type: object security: - APIKeyHeaderAuth: [] - OAuthTokenAuth: [] - SessionAuth: [] components: schemas: UrlResolveRequestSchema: description: Request body for following the redirect chain of a captured QR URL. examples: - url: https://qr.brand.example/p/12345 properties: url: description: >- QR code URL to resolve. Must be ``http://`` or ``https://``; non-HTTP schemes are rejected with ``error_message`` populated in the response (the request itself does not 4xx — failure modes are surfaced uniformly so the UI can render a single error path). maxLength: 2048 minLength: 1 title: Url type: string required: - url title: UrlResolveRequestSchema type: object UrlResolveResponseSchema: description: Result of following the redirect chain for a QR code URL. examples: - chain: - https://qr.brand.example/p/12345 - http://brand.example/products/widget - https://www.brand.example/products/widget error_message: '' final_url: https://www.brand.example/products/widget hops: 2 initial_url: https://qr.brand.example/p/12345 succeeded: true properties: initial_url: description: The URL submitted by the caller. title: Initial Url type: string final_url: description: >- Final URL after following all redirects. Equal to ``initial_url`` when no redirects were followed and when an error short-circuited the chain (so the UI always has a URL to show alongside ``error_message``). title: Final Url type: string hops: description: >- Number of HTTP 3xx redirects followed before reaching the final URL. Capped at 10 — chains longer than that surface as an ``error_message`` rather than a partial result. minimum: 0 title: Hops type: integer chain: description: >- Ordered list of URLs visited, starting with ``initial_url`` and ending with ``final_url``. Empty when an error short-circuited resolution before any response was received. items: type: string title: Chain type: array error_message: description: >- Empty on success. On failure, a human-readable description of the error (timeout, connection refused, too many redirects, malformed URL). The UI surfaces this string directly to the operator. title: Error Message type: string succeeded: description: True when ``error_message`` is empty. title: Succeeded type: boolean required: - initial_url - final_url - hops - error_message - succeeded title: UrlResolveResponseSchema type: object securitySchemes: APIKeyHeaderAuth: type: apiKey in: header name: X-API-Key OAuthTokenAuth: type: http scheme: bearer SessionAuth: type: apiKey in: cookie name: sessionid ````