> ## 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. # List custom resolver hostnames > All custom hostnames registered to the organization, any status, with the DNS records to publish for each. Requires VIEW permission. ## OpenAPI ````yaml /openapi/openapi-resolver.json get /resolver/api/v1/organizations/{organization_id}/custom-hostnames openapi: 3.1.0 info: title: Resolver API version: 1.0.0 description: > GS1 Digital Link resolution with content negotiation and linkset support. ## 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: Resolver description: GS1 Digital Link resolution with content negotiation and linkset support. - name: Custom URLs description: >- Reusable custom-URL catalog (C-3339) — create, list, edit, and delete the custom redirect destinations that resolution rules point at. - name: Verification description: >- Serial verification (`gs1:verificationService`) — tiered, rate-limited responses for serialized GTIN scans. Experimental v1; see the verification-service guide. - name: Resolver Custom Hostnames description: >- BYO domain (C-4058) — register a customer-owned hostname, publish the CNAME records, verify ownership, and serve an org's Digital Link QRs from its own DNS. externalDocs: description: Closient Documentation url: https://docs.closient.com paths: /resolver/api/v1/organizations/{organization_id}/custom-hostnames: get: tags: - Resolver Custom Hostnames summary: List custom resolver hostnames description: >- All custom hostnames registered to the organization, any status, with the DNS records to publish for each. Requires VIEW permission. operationId: apps_resolver_api_custom_hostnames_list_hostnames parameters: - in: path name: organization_id schema: description: Organization UUID. format: shortuuid maxLength: 22 minLength: 22 pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$ title: Organization Id type: string required: true description: Organization UUID. responses: '200': description: OK content: application/json: schema: items: $ref: '#/components/schemas/CustomHostnameOut' title: Response type: array '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorOut' security: - APIKeyHeaderAuth: [] - OAuthTokenAuth: [] - SessionAuth: [] components: schemas: CustomHostnameOut: examples: - hostname: id.theirco.com is_qr_ready: true last_checked_at: '2026-07-20T18:04:11Z' last_error: '' setup: challenge: name: _closient-challenge.id.theirco.com purpose: ownership_verification type: CNAME value: 9f86d081884c.verify.gtin.one qr_density_warning: false serving: name: id.theirco.com purpose: resolver_routing type: CNAME value: gtin.one status: VERIFIED tls_status: ACTIVE verified_at: '2026-07-20T18:04:11Z' properties: hostname: description: The customer-owned hostname, normalized lowercase. title: Hostname type: string status: $ref: '#/components/schemas/CustomHostnameStatusEnum' description: Ownership-verification state. tls_status: $ref: '#/components/schemas/CustomHostnameTLSStatusEnum' description: Edge-certificate state (read-only; driven by the cert pipeline). verified_at: anyOf: - type: string - type: 'null' description: ISO-8601 timestamp of the last successful verification, or null. title: Verified At last_checked_at: anyOf: - type: string - type: 'null' description: ISO-8601 timestamp of the last verification attempt, or null. title: Last Checked At last_error: default: '' description: Reason the last verification attempt failed (empty on success). title: Last Error type: string is_qr_ready: description: >- True when this hostname is VERIFIED and its edge cert is ACTIVE — QRs may print against it. title: Is Qr Ready type: boolean setup: $ref: '#/components/schemas/CustomHostnameSetupOut' description: DNS records to publish for this hostname. required: - hostname - status - tls_status - is_qr_ready - setup title: CustomHostnameOut type: object ErrorOut: description: |- RFC 9457 Problem Details response. All API errors are returned in this format with Content-Type: application/problem+json. examples: - detail: The requested resource was not found. error_code: not_found retryable: false status: 404 timestamp: '2026-03-31T12:00:00+00:00' title: Not Found type: https://closient.com/docs/errors/not_found - detail: Validation error. details: - loc: - body - name msg: Field required type: missing error_code: validation_error retryable: false status: 422 timestamp: '2026-03-31T12:00:00+00:00' title: Validation Error type: https://closient.com/docs/errors/validation_error - detail: Rate limit exceeded. Please try again later. error_code: rate_limited retry_after: 31 retryable: true status: 429 timestamp: '2026-03-31T12:00:00+00:00' title: Rate Limited type: https://closient.com/docs/errors/rate_limited properties: type: description: URI reference identifying the error type. title: Type type: string title: description: Short human-readable summary of the error. title: Title type: string status: description: HTTP status code. title: Status type: integer detail: description: Human-readable explanation of this specific occurrence. title: Detail type: string error_code: description: Machine-readable error code (e.g. not_found, unauthorized). title: Error Code type: string retryable: default: false description: Whether retrying the same request can succeed. title: Retryable type: boolean timestamp: description: ISO 8601 timestamp of when the error occurred. title: Timestamp type: string retry_after: anyOf: - type: integer - type: 'null' description: Seconds to wait before retrying (when applicable). title: Retry After owner_action_required: anyOf: - type: boolean - type: 'null' description: Whether the error requires account owner intervention. title: Owner Action Required details: description: Additional context (validation errors, etc.). title: Details required: - type - title - status - detail - error_code - timestamp title: ErrorOut type: object CustomHostnameStatusEnum: description: >- Ownership-verification state of a custom resolver hostname (C-4058). Mirrors :class:`apps.resolver.models.CustomHostnameStatus`. ``PENDING`` is the just-requested default; ``VERIFIED`` means the CNAME challenge was observed and the hostname routes to the org; ``DISABLED`` is a reversible turn-off that stops routing while keeping the row for audit. enum: - PENDING - VERIFIED - DISABLED title: CustomHostnameStatusEnum type: string CustomHostnameTLSStatusEnum: description: >- Edge-certificate provisioning state of a custom hostname (C-4058). Mirrors :class:`apps.resolver.models.CustomHostnameTLSStatus`. Driven by the cert-automation pipeline (a follow-up), so it is read-only over this API: ``NOT_REQUESTED`` until the pipeline starts, then ``PENDING`` → ``ACTIVE`` / ``FAILED``. A hostname only mints QRs once TLS is ``ACTIVE``. enum: - NOT_REQUESTED - PENDING - ACTIVE - FAILED title: CustomHostnameTLSStatusEnum type: string CustomHostnameSetupOut: examples: - challenge: name: _closient-challenge.id.theirco.com purpose: ownership_verification type: CNAME value: 9f86d081884c.verify.gtin.one qr_density_warning: false serving: name: id.theirco.com purpose: resolver_routing type: CNAME value: gtin.one properties: challenge: $ref: '#/components/schemas/DNSRecordOut' description: >- CNAME challenge record. Publishing it proves control and flips status to VERIFIED. serving: $ref: '#/components/schemas/DNSRecordOut' description: >- CNAME serving record. Points the hostname itself at the resolver for scans. qr_density_warning: description: >- True when the hostname is long enough to noticeably increase printed-QR density. title: Qr Density Warning type: boolean required: - challenge - serving - qr_density_warning title: CustomHostnameSetupOut type: object DNSRecordOut: examples: - name: _closient-challenge.id.theirco.com purpose: ownership_verification type: CNAME value: 9f86d081884c.verify.gtin.one properties: type: description: DNS record type — always ``CNAME`` for both records. title: Type type: string name: description: Fully-qualified record name to create in the customer's zone. title: Name type: string value: description: CNAME target the record must point at. title: Value type: string purpose: description: >- ``ownership_verification`` (challenge) or ``resolver_routing`` (serving). title: Purpose type: string required: - type - name - value - purpose title: DNSRecordOut type: object securitySchemes: APIKeyHeaderAuth: type: apiKey in: header name: X-API-Key OAuthTokenAuth: type: http scheme: bearer SessionAuth: type: apiKey in: cookie name: sessionid ````