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

# Create domain

> Requires the `domains:write` scope. Connects a domain you already own. Add the returned
`dnsRecords` at your DNS provider, then call verify. A two-part domain such as `mybrand.com`
(`isApex: true`) needs a provider that supports CNAME flattening.

Limited to 10 domain requests per minute per account, together with verify.




## OpenAPI

````yaml /openapi.yaml post /domains
openapi: 3.1.0
info:
  title: URLdn API
  version: 1.0.0
  description: >
    Create and manage short links, tags and custom domains, read click
    analytics, generate

    QR codes and ask the AI analyst. Included on every plan, with limits by
    plan. Limits apply

    to your whole account, across all its keys.


    Keep API keys on your server: anything in front-end code can be read by
    anyone.
servers:
  - url: https://api.urldn.com/v1
security:
  - apiKey: []
tags:
  - name: Links
  - name: Tags
  - name: Domains
  - name: Analytics
  - name: QR codes
  - name: AI analyst
  - name: Account
paths:
  /domains:
    post:
      tags:
        - Domains
      summary: Create domain
      description: >
        Requires the `domains:write` scope. Connects a domain you already own.
        Add the returned

        `dnsRecords` at your DNS provider, then call verify. A two-part domain
        such as `mybrand.com`

        (`isApex: true`) needs a provider that supports CNAME flattening.


        Limited to 10 domain requests per minute per account, together with
        verify.
      operationId: createDomain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - domain
              properties:
                domain:
                  type: string
                  maxLength: 253
                  examples:
                    - links.mybrand.com
      responses:
        '201':
          description: The domain, with the DNS records to add
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/QuotaExceeded'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: >
            `domain_exists` (already in your account), `domain_taken` (connected
            to another account)

            or `domain_cooldown` (released recently and still reserved)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Domain:
      type: object
      required:
        - id
        - domain
        - state
        - verified
        - sslStatus
        - isApex
        - dnsRecords
        - verificationExpiresAt
        - lastVerified
        - createdAt
      properties:
        id:
          type: string
        domain:
          type: string
          examples:
            - links.mybrand.com
        state:
          type: string
          enum:
            - dns_pending
            - dns_failed
            - dns_broken
            - ssl_issuing
            - active
        verified:
          type: boolean
        sslStatus:
          type: string
          enum:
            - pending
            - active
            - failed
            - broken
        isApex:
          type: boolean
          description: True for a two-part domain such as mybrand.com
        dnsRecords:
          type: array
          description: The records to add at your DNS provider. Names are full names.
          items:
            type: object
            required:
              - type
              - name
              - value
            properties:
              type:
                type: string
                enum:
                  - CNAME
                  - TXT
              name:
                type: string
              value:
                type: string
        verificationExpiresAt:
          type:
            - string
            - 'null'
          format: date-time
        lastVerified:
          type:
            - string
            - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: A stable machine-readable code
          examples:
            - quota_exceeded
        message:
          type: string
        details:
          type: object
          additionalProperties: true
  responses:
    BadRequest:
      description: >-
        `invalid_request`, `invalid_json`, `invalid_cursor` or
        `blocked_destination`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: '`missing_api_key`, `invalid_api_key` or `revoked_api_key`'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    QuotaExceeded:
      description: >-
        `quota_exceeded`: your plan's limit is used up. `details` has the limit
        and an upgrade link.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: '`plan_required`, `insufficient_scope` or `domain_not_allowed`'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: >-
        `rate_limited`, `monthly_quota_exceeded` or `too_many_auth_failures`.
        Wait for `Retry-After` seconds.
      headers:
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'Your API key: `Authorization: Bearer urldn_live_...`'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.