> ## Documentation Index
> Fetch the complete documentation index at: https://learn.biq.li/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve DNS configuration

> Retrieve the exact DNS routing and ownership-verification records for a domain.

Retrieve the exact records needed to connect a domain. Requires **Custom
domains: Read** (`custom_domains.view`).

```bash theme={null}
curl --request GET \
  --url https://biq.li/api/v1/domain/biq_dom_01M18D4A8QRJY5G6K3N2W7X9TZ/dns-config \
  --header 'Authorization: Bearer biqli_your_workspace_api_key' \
  --header 'Accept: application/json'
```

## Response

```json theme={null}
{
  "domain": {
    "id": "biq_dom_01M18D4A8QRJY5G6K3N2W7X9TZ",
    "host": "go.example.com",
    "status": "pending_dns",
    "dns_status": "pending",
    "ssl_status": "pending",
    "dns_verified": false,
    "active": false
  },
  "dns_config": {
    "host": "go.example.com",
    "is_subdomain": true,
    "records": [
      {"type":"CNAME","name":"go","value":"biq.li","ttl":"auto"},
      {"type":"TXT","name":"_verify.example.com","value":"domain-verify=...","ttl":"auto"}
    ]
  },
  "status": "success"
}
```

The actual `domain` object contains every field documented by
[Retrieve a domain](/docs/api-reference/domains/get); it is abbreviated above.

Publish both records exactly as returned. `name` is the DNS-provider host/name
field, `value` is its target/content, and `ttl: auto` means to use Auto or the
provider default. Some providers automatically append the apex domain; follow
their display convention without duplicating it.

* Apex domains receive an `A` routing record with name `@`.
* Subdomains receive a `CNAME` routing record.
* Every claim receives a TXT ownership record.

The TXT value is intentionally returned because it must be public in DNS. The
endpoint does not expose DNS lookup logs or internal SSL and cleanup errors.
Values may be deployment-specific, so fetch this endpoint instead of hardcoding
Biqli's IP address or hostname.

## Shared API behavior

Authentication is workspace-scoped; see [Authentication](/docs/api-reference/authentication). Errors use the standard envelope and request IDs described in [Errors](/docs/api-reference/errors), and requests are subject to [Rate limits](/docs/api-reference/rate-limits).


## OpenAPI

````yaml GET /v1/domain/{domain}/dns-config
openapi: 3.1.0
info:
  title: Biqli API
  version: 1.0.0
  description: Workspace-scoped REST API for Biqli.
servers:
  - url: https://biq.li/api
security:
  - bearerAuth: []
paths:
  /v1/domain/{domain}/dns-config:
    get:
      tags:
        - Domains
      summary: Retrieve DNS configuration
      description: >-
        Returns the exact routing and TXT ownership records for a workspace
        domain. Requires custom_domains.view.
      operationId: domain.dnsConfig
      parameters:
        - $ref: '#/components/parameters/DomainId'
      responses:
        '200':
          description: DNS configuration returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainDnsConfigResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    DomainId:
      name: domain
      in: path
      required: true
      description: Public custom-domain ID. Numeric IDs and hosts are not accepted.
      schema:
        type: string
        pattern: ^biq_dom_[0-9A-HJKMNP-TV-Z]{26}$
  schemas:
    DomainDnsConfigResponse:
      type: object
      additionalProperties: false
      required:
        - domain
        - dns_config
        - status
      properties:
        domain:
          $ref: '#/components/schemas/Domain'
        dns_config:
          $ref: '#/components/schemas/DomainDnsConfig'
        status:
          type: string
          const: success
    Domain:
      type: object
      additionalProperties: false
      required:
        - id
        - host
        - url
        - status
        - dns_status
        - ssl_status
        - dns_verified
        - active
        - is_subdomain
        - links_count
        - claim_expires_at
        - dns_last_checked_at
        - dns_verified_at
        - ssl_last_checked_at
        - use_default_redirect
        - default_redirect_url
        - use_not_found_redirect
        - not_found_redirect_url
        - use_expired_redirect
        - expired_redirect_url
        - created_at
        - updated_at
      properties:
        id:
          type: string
          pattern: ^biq_dom_[0-9A-HJKMNP-TV-Z]{26}$
        host:
          type: string
          examples:
            - go.example.com
        url:
          type: string
          format: uri
        status:
          type: string
          enum:
            - pending_dns
            - verifying_dns
            - dns_failed
            - provisioning_ssl
            - ssl_failed
            - active
        dns_status:
          type: string
          enum:
            - pending
            - verifying
            - verified
            - failed
        ssl_status:
          type: string
          enum:
            - pending
            - processing
            - active
            - failed
        dns_verified:
          type: boolean
        active:
          type: boolean
        is_subdomain:
          type: boolean
        links_count:
          type: integer
          minimum: 0
          description: Links using this domain in the API key's workspace only.
        claim_expires_at:
          type:
            - string
            - 'null'
          format: date-time
        dns_last_checked_at:
          type:
            - string
            - 'null'
          format: date-time
        dns_verified_at:
          type:
            - string
            - 'null'
          format: date-time
        ssl_last_checked_at:
          type:
            - string
            - 'null'
          format: date-time
        use_default_redirect:
          type: boolean
        default_redirect_url:
          type:
            - string
            - 'null'
          format: uri
        use_not_found_redirect:
          type: boolean
        not_found_redirect_url:
          type:
            - string
            - 'null'
          format: uri
        use_expired_redirect:
          type: boolean
        expired_redirect_url:
          type:
            - string
            - 'null'
          format: uri
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
    DomainDnsConfig:
      type: object
      additionalProperties: false
      required:
        - host
        - is_subdomain
        - records
      properties:
        host:
          type: string
        is_subdomain:
          type: boolean
        records:
          type: array
          minItems: 2
          maxItems: 2
          items:
            $ref: '#/components/schemas/DnsRecord'
    ApiError:
      type: object
      required:
        - error
        - request_id
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - invalid_token
                - insufficient_scope
                - upgrade_required
                - quota_exceeded
                - resource_not_found
                - domain_taken
                - alias_taken
                - external_id_taken
                - folder_name_taken
                - tag_name_taken
                - pixel_name_taken
                - biolink_name_taken
                - method_not_allowed
                - url_blocked
                - dns_verification_failed
                - validation_error
                - rate_limit_exceeded
                - internal_server_error
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        request_id:
          type: string
          description: Request identifier to include when contacting support.
    DnsRecord:
      type: object
      additionalProperties: false
      required:
        - type
        - name
        - value
        - ttl
      properties:
        type:
          type: string
          enum:
            - A
            - CNAME
            - TXT
        name:
          type: string
        value:
          type: string
        ttl:
          type: string
          const: auto
  responses:
    Unauthorized:
      $ref: '#/components/responses/ApiErrorResponse'
      description: The workspace API key is missing, invalid, or revoked.
    Forbidden:
      $ref: '#/components/responses/ApiErrorResponse'
      description: >-
        The key lacks a required scope, the workspace must upgrade, or its quota
        is exhausted.
    NotFound:
      $ref: '#/components/responses/ApiErrorResponse'
      description: >-
        The requested resource or referenced public ID is unavailable in the
        key's workspace.
    RateLimited:
      description: The workspace exceeded its plan's API rate limit.
      headers:
        RateLimit-Policy:
          description: Current IETF HTTPAPI quota policy as a structured field.
          schema:
            type: string
            example: '"workspace-api";q=1000;w=60'
        RateLimit:
          description: Current IETF HTTPAPI service limit as a structured field.
          schema:
            type: string
            example: '"workspace-api";r=0;t=17'
        Retry-After:
          description: Seconds to wait before retrying the request.
          schema:
            type: integer
            minimum: 0
            example: 17
        X-RateLimit-Limit:
          description: Legacy maximum request count for the current window.
          schema:
            type: integer
            minimum: 1
            example: 1000
        X-RateLimit-Remaining:
          description: Legacy remaining request count.
          schema:
            type: integer
            minimum: 0
            example: 0
        X-RateLimit-Reset:
          description: Legacy reset time as a UTC Unix timestamp.
          schema:
            type: integer
            format: int64
            example: 1788126519
        X-Biq-Request-Id:
          description: Request identifier for support and tracing.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    InternalError:
      $ref: '#/components/responses/ApiErrorResponse'
      description: The request failed unexpectedly.
    ApiErrorResponse:
      description: API error.
      headers:
        X-Biq-Request-Id:
          description: Request identifier for support and tracing.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Workspace API key
      description: A workspace API key beginning with biqli_.

````