> ## 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.

# List domains

> Filter and cursor-paginate custom domains attached to the API key's workspace.

List domains attached to the workspace. Requires **Custom domains: Read**
(`custom_domains.view`). Every item is the complete safe resource described in
[Retrieve a domain](/docs/api-reference/domains/get).

```bash theme={null}
curl --get 'https://biq.li/api/v1/domain' \
  --header 'Authorization: Bearer biqli_your_workspace_api_key' \
  --header 'Accept: application/json' \
  --data-urlencode 'dns_status=verified' \
  --data-urlencode 'page_size=25'
```

## Filters

| Query parameter  | Type             | Behavior                                         |
| ---------------- | ---------------- | ------------------------------------------------ |
| `search`         | string           | Partial host search, 1–255 characters.           |
| `dns_status`     | string           | `pending`, `verifying`, `verified`, or `failed`. |
| `ssl_status`     | string           | `pending`, `processing`, `active`, or `failed`.  |
| `starting_after` | public domain ID | Retrieve the next, older page.                   |
| `ending_before`  | public domain ID | Retrieve the previous, newer page.               |
| `page_size`      | integer          | Defaults to `50`; accepts `1`–`100`.             |

Filters combine with AND. Unknown parameters, custom sorting, numeric IDs, and
simultaneous `starting_after` and `ending_before` are rejected.

## Response and pagination

```json theme={null}
{
  "domains": [
    {
      "id": "biq_dom_01M18D4A8QRJY5G6K3N2W7X9TZ",
      "host": "go.example.com",
      "url": "https://go.example.com",
      "status": "active",
      "dns_status": "verified",
      "ssl_status": "active",
      "dns_verified": true,
      "active": true,
      "is_subdomain": true,
      "links_count": 42,
      "claim_expires_at": null,
      "dns_last_checked_at": "2026-08-30T03:00:00+00:00",
      "dns_verified_at": "2026-08-30T03:00:00+00:00",
      "ssl_last_checked_at": "2026-08-30T03:02:00+00:00",
      "use_default_redirect": false,
      "default_redirect_url": null,
      "use_not_found_redirect": false,
      "not_found_redirect_url": null,
      "use_expired_redirect": false,
      "expired_redirect_url": null,
      "created_at": "2026-08-30T02:30:00+00:00",
      "updated_at": "2026-08-30T03:02:00+00:00"
    }
  ],
  "pagination": {
    "page_size": 25,
    "has_more": true,
    "next_cursor": "biq_dom_01M18D4A8QRJY5G6K3N2W7X9TZ",
    "previous_cursor": null
  },
  "status": "success"
}
```

Results are newest first. Pass `next_cursor` as `starting_after` with the same
filters to get the next page. Pass `previous_cursor` as `ending_before` to move
back. Never construct cursors yourself. An unavailable cursor returns
`404 resource_not_found`; no matches returns an empty `domains` array.

`links_count` is isolated to this workspace. No numeric or operational IDs are
returned.

## 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). This endpoint uses cursor pagination; see [Pagination](/docs/api-reference/pagination).


## OpenAPI

````yaml GET /v1/domain
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:
    get:
      tags:
        - Domains
      summary: List domains
      description: >-
        Returns a cursor-paginated list of domains attached to the API key's
        workspace. Requires custom_domains.view.
      operationId: domain.index
      parameters:
        - name: search
          in: query
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: dns_status
          in: query
          schema:
            type: string
            enum:
              - pending
              - verifying
              - verified
              - failed
        - name: ssl_status
          in: query
          schema:
            type: string
            enum:
              - pending
              - processing
              - active
              - failed
        - name: starting_after
          in: query
          description: Return the next, older page. Mutually exclusive with ending_before.
          schema:
            type: string
            pattern: ^biq_dom_[0-9A-HJKMNP-TV-Z]{26}$
        - name: ending_before
          in: query
          description: >-
            Return the previous, newer page. Mutually exclusive with
            starting_after.
          schema:
            type: string
            pattern: ^biq_dom_[0-9A-HJKMNP-TV-Z]{26}$
        - name: page_size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
      responses:
        '200':
          description: Domains returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDomainsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    ListDomainsResponse:
      type: object
      additionalProperties: false
      required:
        - domains
        - pagination
        - status
      properties:
        domains:
          type: array
          items:
            $ref: '#/components/schemas/Domain'
        pagination:
          $ref: '#/components/schemas/DomainListPagination'
        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
    DomainListPagination:
      type: object
      additionalProperties: false
      required:
        - page_size
        - has_more
        - next_cursor
        - previous_cursor
      properties:
        page_size:
          type: integer
          minimum: 1
          maximum: 100
        has_more:
          type: boolean
        next_cursor:
          type:
            - string
            - 'null'
          pattern: ^biq_dom_[0-9A-HJKMNP-TV-Z]{26}$
        previous_cursor:
          type:
            - string
            - 'null'
          pattern: ^biq_dom_[0-9A-HJKMNP-TV-Z]{26}$
    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.
  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.
    UnprocessableEntity:
      $ref: '#/components/responses/ApiErrorResponse'
      description: >-
        The payload is invalid, a destination was blocked, or domain DNS
        verification is not ready.
    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_.

````