openapi: 3.1.0
info:
  contact:
    email: reseller@name.com
    name: Reseller Account Services
  description: RESTful API for managing domains, DNS records, and related services at name.com.  Access via HTTPS at api.name.com (production) or api.dev.name.com (testing).  Supports standard authentication, rate-limited to 20 requests/second.
  title: name.com Core API
  version: 1.36.0
  termsOfService: https://www.name.com/policies/api-access-agreement
servers:
  - description: Testing
    url: https://api.dev.name.com
security:
  - BasicAuth: []
tags:
  - name: Hello
    description: Use the Hello endpoint to verify that your API connection and credentials are working properly. This simple call returns a success message (along with server time and version info) to confirm the API is reachable and authenticated.
  - name: Account Info
    description: Use Account Info endpoints to retrieve basic information about your name.com account. For example, you can check your account’s current credit balance and other account details using these endpoints.
  - name: Accounts
    description: Use Accounts endpoints (available upon request) to manage sub-accounts under your main account. For example, resellers can programmatically create new customer accounts with their own login credentials and permissions.
  - name: Domains
    description: Use Domains endpoints to search for domain availability, register new domains, and manage existing domains.
  - name: Contact Verification
    description: Use Contact Verification endpoints to query a reseller’s unverified domains/emails and to programmatically mark an end user’s email as verified if the reseller has already completed the verification process. These endpoints help resellers meet ICANN requirements by ensuring end users confirm they can receive email at their listed address.
  - name: DNS
    description: Use DNS endpoints to manage DNS records for your domains. You can list all existing DNS records for a domain and create, update, or delete records as needed.
  - name: DNSSECs
    description: Use DNSSEC endpoints to configure DNS Security Extensions for your domains. These endpoints allow you to add, retrieve, or remove DNSSEC records.
  - name: Email Forwardings
    description: Use Email Forwardings endpoints to set up and manage email forwarding addresses on your domains.
  - name: URL Forwardings
    description: Use URL Forwardings endpoints to control URL redirection settings for your domains.
  - name: Vanity Nameservers
    description: Use Vanity Nameservers endpoints to configure custom nameserver hostnames (glue records) for your domains.
  - name: Transfers
    description: Use Transfers endpoints to move domains into your name.com account. Start by creating a transfer request for inbound transfers from **external** registrars, then monitor and manage the status of pending transfers. Use **internal transfer in** to pull a domain from another name.com account into your reseller account (enterprise allowlist; requires auth code from the losing account’s dashboard). You can cancel an incoming transfer if needed, or cancel an outbound transfer (domain leaving name.com) via the external transfer-out cancel endpoint. Use the **transfer eligibility** endpoint to check whether a domain is currently at name.com before initiating a transfer, so you can route to the correct flow (external vs internal transfer).
  - name: Orders
    description: Use Orders endpoints to review and track purchases made via the API.
  - name: Refunds
    description: |
      Use the Refunds endpoint to delete eligible domains and advanced security products during the Add Grace Period (AGP) and automatically issue refunds for the associated order items. You can use the List Orders endpoint to retrieve order IDs, then pass those IDs into the Refunds endpoint to process eligible deletions and refunds.   This endpoint enforces AGP delete limits and supports only domain registrations and advanced security add-ons. Refunds are issued  to the original payment method on file. If the original payment method is unavailable, the refund will be credited to the account balance.
  - name: Webhook Notifications
    description: |
      Use Webhook Notification endpoints to subscribe to real-time notifications for account and domain events. This keeps your application updated on important changes without polling the API.
      Outbound webhook POSTs include an `X-NAMECOM-SIGNATURE` header. HMAC uses one API v4 token per account, chosen deterministically when multiple tokens exist (see HMAC Signature Verification in the developer docs). The signing input format is unchanged.
  - name: Domain Info
    description: Use Domain Info endpoints to retrieve information about TLD-specific requirements and registration rules. These endpoints help you understand what fields, documents, or constraints are needed to successfully register domains across different TLDs.
  - name: TLD Pricing
    description: Use TLD Pricing endpoints to retrieve general pricing information for your account.
  - name: Premium Domains
    description: APIs for working with Premium Domains.
paths:
  /core/v1/accountinfo/balance:
    get:
      description: Returns the current account credit balance for the authenticated user.
      operationId: CheckAccountBalance
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckAccountBalanceResponse'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Check Account Balance
      tags:
        - Account Info
  /core/v1/accounts:
    post:
      description: Creates a new sub-account under your authenticated reseller account and returns API credentials for the new account.  This endpoint is only available to approved reseller accounts. Contact name.com support to request access.
      operationId: CreateAccount
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccountRequest'
        description: CreateAccountRequest has the information that is needed to create an account with the CreateAccount function.
        required: true
      responses:
        '200':
          description: A successful response containing the newly created account details and credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAccountResponse'
        '400':
          description: Bad request - Invalid query or request body parameters. Account creation requeires both TOS and APITOS values to be true.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Create Account
      tags:
        - Accounts
  /core/v1/domains:
    get:
      description: Lists all domains in your account (basic details for each domain).
      operationId: ListDomains
      parameters:
        - description: Per Page is the number of records to return per request. Per Page defaults to 250.
          in: query
          name: perPage
          schema:
            allOf:
              - $ref: '#/components/schemas/PerPageLimit'
              - default: 250
        - description: Page is which page to return.
          in: query
          name: page
          schema:
            format: int32
            type: integer
            minimum: 1
        - description: Sort specifies which domain property to order by.
          in: query
          name: sort
          schema:
            type: string
        - description: Dir indicates direction of sort. Possible values are 'asc' (default) or 'desc'.
          in: query
          name: dir
          schema:
            type: string
        - description: DomainName filters domains by exact domain name or wildcard (starts with '*').
          in: query
          name: domainName
          schema:
            type: string
        - description: Tld filters on specific tld.
          in: query
          name: tld
          schema:
            type: string
        - description: Locked filters on locked domains.
          in: query
          name: locked
          schema:
            type: boolean
        - description: CreateDate filters domains created on this date.
          in: query
          name: createDate
          schema:
            type: string
        - description: CreateDateStart filters domains created on or after this date.
          in: query
          name: createDateStart
          schema:
            type: string
        - description: CreateDateEnd filters domains created on or before this date.
          in: query
          name: createDateEnd
          schema:
            type: string
        - description: ExpireDate filters domains expiring on this date.
          in: query
          name: expireDate
          schema:
            type: string
        - description: ExpireDateStart filters domains with expire date on or after this date.
          in: query
          name: expireDateStart
          schema:
            type: string
        - description: ExpireDateEnd filters domains with expire date on or before this date.
          in: query
          name: expireDateEnd
          schema:
            type: string
        - description: PrivacyEnabled indicates whether there is a privacy product associated with the domain.
          in: query
          name: privacyEnabled
          schema:
            type: boolean
        - description: IsPremium indicates whether the domain is a premium domain.
          in: query
          name: isPremium
          schema:
            type: boolean
        - description: AutorenewEnabled indicates if the domain will attempt to renew automatically before expiration.
          in: query
          name: autorenewEnabled
          schema:
            type: boolean
        - description: OrderId specifies the order number of a domain purchase.
          in: query
          name: orderId
          schema:
            format: int32
            type: integer
        - description: IncludeRenewalPrice indicates whether to include renewal pricing information in the response.
          in: query
          name: includeRenewalPrice
          schema:
            type: boolean
            default: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDomainsResponse'
          description: A successful response.
          headers:
            Link:
              description: String delimited list of links for pagination
              schema:
                type: string
                example: <https://api.dev.name.com?page=3; rel="next">,<https://api.dev.name.com?page=1; rel="prev">,<https://api.dev.name.com?page=10; rel="last">
        '400':
          description: Bad request - Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: List Domains
      tags:
        - Domains
    post:
      description: |
        Registers a new domain under your account. You must provide `domain.domainName` at minimum.
        This endpoint is commonly used to programmatically onboard new domains through user signup flows or checkout experiences.

        If no contacts are passed in this request, the default contacts for your name.com account will be used.

        ### Create Domain pricing

        See the [Domain purchase pricing guide](/guides/domain-pricing) for the full reference.
        **Recommendation:** For most integrations, scope discovery to `purchaseType: registration`. Other purchase types are supported but add complexity — details in the guide above.

        **Discovery (required before create):** Call [Search](/api/v1/reference/domains/search) or [Check Availability](/api/v1/reference/domains/check-availability), not Get Pricing alone. Both return the same `SearchResult` fields (`purchaseType`, `purchasePrice`, `premium`, `purchasable`). [Zone Check](/api/v1/reference/domains/zone-check) is designed for rapid availability checks only; it is not sufficient to complete a purchase.

        ### Getting the price for Create Domain

        1. **Search or Check Availability** → copy `purchaseType`, `premium`, note `purchasePrice`.

        2. Branch on `purchaseType`:
           - **`registration` + `premium: false`** — omit `purchasePrice` on create, set `years`. Optional: Get Pricing with same `years` to preview the total.
           - **`registration` + `premium: true`** — Get Pricing with same `years` → pass `purchasePrice` exactly.
           - **aftermarket / expiring / backorder** — use discovery `purchasePrice` (flat fee). Re-check discovery before create. Do not use Get Pricing for create price. `years` does not multiply price or guarantee registration length.

        3. If `purchasePrice` is sent, it must match exactly or the request fails with `400` and `"Purchase price does not match"`.

        **Years on acquisition types:** For `aftermarket_s`, `aftermarket_b`, `aftermarket_i`, `expiring`, and `backorder`: omit `years` or pass the TLD default. Check `domain.expireDate` in the response; [Renew](/api/v1/reference/domains/renew-domain) to extend registration.

        ### Best Practices For Domain Creates

        In general, you should check that a domain is available prior to attempting to purchase a domain.
        You can use either the [checkAvailability](/api/v1/reference/domains/check-availability) endpoint, or the [Search](/api/v1/reference/domains/search) endpoint
        to confirm that a domain is purchasable.

        #### Important Note on Dropcatching and Abuse Prevention

        _The createDomain endpoint is designed for standard domain registrations and is not intended for automated dropcatching (i.e., mass or high-frequency attempts to register domains the moment they become available after expiration). The use of drop-catching tools or services to acquire expired domains is strictly prohibited. All domain acquisitions must go through approved channels to ensure fair and transparent access._

        #### Contact Verification
        When a new domain registration is created and a contact is submitted, name.com may need to validate the contact's email address in accordance with ICANN policy. This validation involves sending an email to the provided address, prompting the recipient to click a link to verify their email address.
      operationId: CreateDomain
      parameters:
        - name: X-Idempotency-Key
          in: header
          description: A unique string (e.g., a UUID v4) to make the request idempotent. This key ensures that if the request is retried, the operation will not be performed multiple times. Subsequent requests with the same key will return the original result.
          schema:
            type: string
            example: 083910ef-04e4-4bd1-a0bf-3737fe005ca8
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDomainRequest'
            examples:
              noContacts:
                summary: Creating a domain without contacts.
                description: For a basic domain create, you do not need to send contacts in the request. **When contacts are not sent in the request, we will apply the default contacts for your account to the domain.**
                value:
                  domain:
                    domainName: example.com
              multipleYears:
                summary: Standard registration, 2 years (omit purchasePrice).
                description: 'For `purchaseType: registration` with `premium: false`, omit `purchasePrice` and set `years` on create. Optionally call Get Pricing with `years=2` to preview the registration total.'
                value:
                  domain:
                    domainName: example.com
                  years: 2
              registryPremium:
                summary: Registry premium domain, 1 year.
                description: 'Registry premium uses `purchaseType: registration` with `premium: true` from Search or Check Availability. Call Get Pricing with matching `years` and pass `purchasePrice` exactly.'
                value:
                  domain:
                    domainName: premiumexample.com
                  purchasePrice: 349.95
                  purchaseType: registration
                  years: 1
              premiumPurchaseMultiYear:
                summary: Registry premium domain, 2 years (from Get Pricing).
                description: 'For registry premium multi-year, call Get Pricing with `years=2` and pass the returned `purchasePrice` total. Example: flat $349.95/yr registry premium → `purchasePrice: 699.90` for 2 years. Do not use discovery `renewalPrice` or multiply aftermarket acquisition fees by years.'
                value:
                  domain:
                    domainName: premiumexample.com
                  purchasePrice: 699.9
                  purchaseType: registration
                  years: 2
              aftermarketFlatPrice:
                summary: Aftermarket domain — flat acquisition fee.
                description: 'Aftermarket domains use a flat acquisition fee from Search or Check Availability — not Get Pricing. `purchasePrice: 5000.00` is the acquisition fee only; it does not buy multiple years. Omit `years` or pass the TLD default — it does not affect price or guarantee registration length.'
                value:
                  domain:
                    domainName: rarename.com
                  purchasePrice: 5000
                  purchaseType: aftermarket_s
                  years: 1
              expiringPurchase:
                summary: Expiring domain (non-registration purchaseType).
                description: Expiring domains use a flat acquisition fee from discovery — not Get Pricing. Pass discovery `purchasePrice` with matching `purchaseType`. Omit `years` or pass the TLD default — it does not affect price or guarantee registration length.
                value:
                  domain:
                    domainName: expiringexample.com
                  purchasePrice: 349.95
                  purchaseType: expiring
                  years: 1
              backorderPurchase:
                summary: Backorder domain (non-registration purchaseType).
                description: Backorder domains use a flat TLD-based acquisition fee from discovery — not Get Pricing. Pass discovery `purchasePrice` with matching `purchaseType`. `purchasePrice` is required regardless of the `premium` flag. Omit `years` or pass the TLD default — it does not affect price or guarantee registration length. Re-check Check Availability immediately before create — prices can change. Example price below is illustrative — use the value from your discovery result.
                value:
                  domain:
                    domainName: backorderexample.com
                  purchasePrice: 79.99
                  purchaseType: backorder
              singleContactAtCreate:
                summary: Send single, specific contact with domain create
                description: Generally all contacts need to be submitted when creating a domain that will not use your account default contacts. By passing a single contact during a domain create, you can set a single contact to be different than the account default contacts. This may also be required for some TLDs due to ICANN changes in registration contact requirements
                value:
                  domain:
                    domainName: example.com
                    contacts:
                      tech:
                        firstName: Jonny
                        lastName: IT Guy
                        companyName: My Company
                        address1: 1234 Any Street
                        address2: null
                        city: Anytown
                        state: NY
                        zip: '11222'
                        country: US
                        email: support@example.com
                        phone: '+15555555'
              idnRegistration:
                summary: Registering an IDN domain
                description: How to pass the correct IDN language for domains using non-ASCII characters.
                value:
                  domain:
                    domainName: exámple.com
                  tldRequirements:
                    language: ES
                  years: 1
              cctldRequirements:
                summary: Registering a .se domain with TLD requirements
                description: Some ccTLDs require additional registry-specific fields at create time. Fetch the required keys from [Get TLD Requirements as JSON Schema](/api/v1/reference/domain-info/get-specific-tld-requirements-v2), then pass them under `tldRequirements`. For `.se`, `X-NICSE-IDNUMBER` is required (personal or organizational ID).
                value:
                  domain:
                    domainName: example.se
                  tldRequirements:
                    X-NICSE-IDNUMBER: '5566778899'
                  years: 1
              withClaims:
                summary: Creating a domain with trademark claims acknowledgment
                description: When a domain has trademark claims (as determined by the [Domain Claims Check](/api/v1/reference/domain-info/check-domain-claims) endpoint), you must include the claims acknowledgment data in the domain creation request. This includes the claim identifier and validity dates from the claims check response.
                value:
                  domain:
                    domainName: tiktok.page
                  claims:
                    claimId: 8c3027d30000000000382500785
                    notBefore: '2020-01-01T00:00:00Z'
                    notAfter: '2030-01-01T00:00:00Z'
        required: true
      responses:
        '200':
          headers:
            X-Idempotency-Key:
              description: If the initial request contained this header, echoes back with the initial value.
              schema:
                type: string
                example: 083910ef-04e4-4bd1-a0bf-3737fe005ca8
            X-Idempotent-Replay:
              description: Indicates that the response is being replayed from an idempotent request. This header will only be returned if the API is responding with cached data. Caches are cleared after 1 hour.
              schema:
                type: number
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDomainResponse'
          description: A successful response.
        '400':
          description: Bad request - Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
              examples:
                premiumPriceRequired:
                  summary: Premium domain purchase requires price
                  value:
                    message: Purchase price is required for premium domains in order to complete this request
                priceRequired:
                  summary: Purchase price required (non-registration purchaseType)
                  value:
                    message: Purchase price is required in order to complete this request
                priceMismatch:
                  summary: Purchase price does not match
                  value:
                    message: Purchase price does not match
                invalidYears:
                  summary: Invalid registration term
                  value:
                    message: Invalid years
                promoNoDiscount:
                  summary: Promo code applies no discount
                  description: Returned when the supplied promo applies no discount. The order is not created. Promo codes specify eligibility criteria, including duration.
                  value:
                    message: Promo code does not apply a discount to this purchase
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '402':
          description: Payment has failed for this transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired402'
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or requested resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '409':
          description: When sending idempotent requests, this response indicates that there was an issue with the idempotency keys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Idempotency key has been reused for a different request
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '422':
          description: Pricing information unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity422'
              examples:
                registrationUnavailable:
                  summary: Registration price unavailable
                  value:
                    message: Domain pricing unavailable
                    details: The pricing information required to process this request is temporarily unavailable. This is an internal system error. Please try again in a few minutes or contact support if the issue persists.
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '451':
          description: Unavailable for Legal Reasons.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnavailableForLegal451'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '501':
          description: Not implemented.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError501'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Create Domain
      tags:
        - Domains
  /core/v1/domains/{domainName}:
    get:
      description: Retrieves detailed information for a specific domain in your account.
      operationId: GetDomain
      parameters:
        - description: DomainName is the domain to retrieve.
          in: path
          name: domainName
          required: true
          schema:
            type: string
            example: example.com
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainResponsePayload'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: The requested domain could not be located.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Get Domain
      tags:
        - Domains
    patch:
      description: Allows updating of the autorenew, WhoIs Privacy and lock status of the specified domain. The request requires one, or any combination of the parameters in order to pass validation. If any of the requested updates failed, the domain will be returned to it's original state.
      operationId: UpdateDomain
      summary: Update a domain
      tags:
        - Domains
      parameters:
        - description: DomainName is the domain to update.
          in: path
          name: domainName
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Fields for updating a domain. At least one of `autorenewEnabled`, `privacyEnabled`, or `locked` is required. Omit a property to leave it unchanged.
              minProperties: 1
              properties:
                autorenewEnabled:
                  type: boolean
                  description: Enable or disable automatic renewal for the domain.
                  example: true
                privacyEnabled:
                  type: boolean
                  description: Enable or disable Whois privacy for the domain.
                  example: true
                locked:
                  type: boolean
                  description: Set the transfer lock status for the domain
                  example: true
              anyOf:
                - type: object
                  properties:
                    autorenewEnabled:
                      type: boolean
                  required:
                    - autorenewEnabled
                - type: object
                  properties:
                    privacyEnabled:
                      type: boolean
                  required:
                    - privacyEnabled
                - type: object
                  properties:
                    locked:
                      type: boolean
                  required:
                    - locked
      responses:
        '200':
          description: A successful response will return the updated domain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainResponsePayload'
        '400':
          description: The request failed to pass validation. See the response message for information as to what failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: The domain you are attempting to update has expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '404':
          description: We were unable to locate the domain to update.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '409':
          description: A condition of the domain prevents the update. There are several reasons you may receive this error. For example, not all domains can be locked by the registrar. Another reason is that a domain does not have WHOIS Privacy available. Please check the "message" property of the response so you know why the request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericConflict409'
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
  /core/v1/domains/{domainName}/dnssec:
    get:
      description: Lists all DNSSEC (DS) records configured for a domain.
      operationId: ListDNSSECs
      parameters:
        - description: DomainName is the domain name to list keys for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDNSSECsResponse'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or DNSSEC not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: List DNSSECs
      tags:
        - DNSSECs
    post:
      description: Adds (registers) a new DNSSEC DS record for a domain.
      operationId: CreateDNSSEC
      parameters:
        - description: DomainName is the domain name to create keys for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDNSSECBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSSEC'
          description: A successful response.
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
              example:
                message: This resource already exists.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or DNSSEC not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '409':
          description: Conflict - A DNSSEC record with this digest already exists for the domain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericConflict409'
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Create DNSSEC
      tags:
        - DNSSECs
  /core/v1/domains/{domainName}/dnssec/{digest}:
    delete:
      description: Deletes a DNSSEC record from a domain.
      operationId: DeleteDNSSEC
      parameters:
        - description: DomainName is the domain name the key is registered for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
        - description: Digest is the digest for the DNSKEY RR to remove from the registry.
          in: path
          name: digest
          required: true
          schema:
            type: string
      responses:
        '204':
          description: DNSSEC successfully deleted.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or DNSSEC not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Delete DNSSEC
      tags:
        - DNSSECs
    get:
      description: Retrieves details of a specific DNSSEC record for a domain.
      operationId: GetDNSSEC
      parameters:
        - description: DomainName is the domain name.
          in: path
          name: domainName
          required: true
          schema:
            type: string
        - description: Digest is the digest for the DNSKEY RR to retrieve.
          in: path
          name: digest
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSSEC'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or DNSSEC not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Get DNSSEC
      tags:
        - DNSSECs
  /core/v1/domains/{domainName}/email/forwarding:
    get:
      description: Returns a paginated list of all email forwarding rules for a domain.
      operationId: ListEmailForwardings
      parameters:
        - description: DomainName is the domain to list email forwarded boxes for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
        - description: (optional) Per Page is the number of records to return per request. Per Page defaults to 500 if not set.
          in: query
          name: perPage
          schema:
            allOf:
              - $ref: '#/components/schemas/PerPageLimit'
              - default: 500
                example: 100
        - description: (optional) Page is which page to return. Default to page 1 if not set.
          in: query
          name: page
          schema:
            format: int32
            type: integer
            example: 1
            minimum: 1
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEmailForwardingsResponse'
          headers:
            Link:
              description: String delimited list of links for pagination
              schema:
                type: string
                example: <https://api.dev.name.com?page=3; rel="next">,<https://api.dev.name.com?page=1; rel="prev">,<https://api.dev.name.com?page=10; rel="last">
          description: A successful response.
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: The requested domain could not be located.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: List Email Forwardings
      tags:
        - Email Forwardings
    post:
      description: Creates a new email forwarding rule for a domain, such as redirecting info@example.com to an external inbox.  If this is the first email forwarding rule created for the domain, the API may also update your MX records automatically to enable mail routing.  The alias must not conflict with existing email services or MX records.  Wildcard and catch-all forwarding is not supported, so an `emailBox` containing `*` is rejected with a `400 Bad Request`.  To modify a forwarding rule later, use [UpdateEmailForwarding](/api/v1/reference/email-forwardings/update-email-forwarding).
      operationId: CreateEmailForwarding
      parameters:
        - description: DomainName is the domain part of the email address to forward.
          in: path
          name: domainName
          required: true
          schema:
            type: string
            example: example.com
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmailForwardingRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailForwarding'
          description: An email forwarding record has been successfully created.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
          description: Bad request - Invalid input data.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: The requested domain could not be located.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Create Email Forwarding
      tags:
        - Email Forwardings
  /core/v1/domains/{domainName}/email/forwarding/{emailBox}:
    delete:
      description: Deletes an email forwarding rule from a domain.
      operationId: DeleteEmailForwarding
      parameters:
        - description: DomainName is the domain to delete the email forwarded box from.
          in: path
          name: domainName
          required: true
          schema:
            type: string
        - description: EmailBox is which email box to delete.
          in: path
          name: emailBox
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Email Forwarding entry successfully deleted.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
          description: The Email Forwarding record cannot be found.
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Delete Email Forwarding
      tags:
        - Email Forwardings
    get:
      description: Retrieves the details of a specific email forwarding entry.
      operationId: GetEmailForwarding
      parameters:
        - description: DomainName is the domain to list email forwarded box for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
        - description: EmailBox is which email box to retrieve.
          in: path
          name: emailBox
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailForwarding'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
          description: The Email Forwarding record cannot be found.
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Get Email Forwarding
      tags:
        - Email Forwardings
    put:
      description: Updates the destination email address for an existing forwarding rule.
      operationId: UpdateEmailForwarding
      parameters:
        - description: DomainName is the domain part of the email address to forward.
          in: path
          name: domainName
          required: true
          schema:
            type: string
        - description: EmailBox is the user portion of the email address to forward.
          in: path
          name: emailBox
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailForwardingsUpdateEmailForwardingBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailForwarding'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
          description: The Email Forwarding record cannot be found.
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Update Email Forwarding
      tags:
        - Email Forwardings
  /core/v1/domains/{domainName}/records:
    get:
      description: Lists all DNS records for a specified domain.
      operationId: ListRecords
      parameters:
        - description: DomainName is the zone to list the records for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
        - description: Per Page is the number of records to return per request. Per Page defaults to 500.
          in: query
          name: perPage
          schema:
            allOf:
              - $ref: '#/components/schemas/PerPageLimit'
              - default: 500
        - description: Page is which page to return.
          in: query
          name: page
          schema:
            format: int32
            type: integer
            minimum: 1
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRecordsResponse'
          description: A successful response.
        '400':
          description: Bad request - Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: The requested domain could not be located.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: List Records
      tags:
        - DNS
    post:
      description: Adds a new DNS record to the specified domain zone. Provide the record type (e.g. A, MX, CNAME), host, value, and TTL.  This is used for configuring domain-based services such as email, website hosting, or third-party verifications.
      operationId: CreateRecord
      parameters:
        - description: DomainName is the zone that the record belongs to.
          in: path
          name: domainName
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DNSCreateRecordBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Record'
          description: A successful response.
          links:
            GetCreatedRecord:
              operationId: GetRecord
              parameters:
                domainName: $request.path.domainName
                id: $response.body#/id
            UpdateCreatedRecord:
              operationId: UpdateRecord
              parameters:
                domainName: $request.path.domainName
                id: $response.body#/id
            DeleteCreatedRecord:
              operationId: DeleteRecord
              parameters:
                domainName: $request.path.domainName
                id: $response.body#/id
        '400':
          description: Bad request - Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: The requested domain could not be located.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Create Record
      tags:
        - DNS
  /core/v1/domains/{domainName}/records/{id}:
    delete:
      description: Removes a DNS record by ID. Often used during cleanup operations or when replacing outdated DNS settings with updated records.
      operationId: DeleteRecord
      parameters:
        - description: DomainName is the zone that the record to be deleted exists in.
          in: path
          name: domainName
          required: true
          schema:
            type: string
        - description: ID is the server-assigned unique identifier for the Record to be deleted. If the Record with that ID does not exist in the specified Domain, an error is returned.
          in: path
          name: id
          required: true
          schema:
            format: int32
            type: integer
      responses:
        '204':
          description: Record successfully deleted.
        '400':
          description: Bad request - Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or DNS record not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Delete Record
      tags:
        - DNS
    get:
      description: Retrieves details of a specific DNS record.
      operationId: GetRecord
      parameters:
        - description: DomainName is the zone the record exists in.
          in: path
          name: domainName
          required: true
          schema:
            type: string
        - description: ID is the server-assigned unique identifier for this record.
          in: path
          name: id
          required: true
          schema:
            format: int32
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Record'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or DNS record not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Get Record
      tags:
        - DNS
    put:
      description: Replaces an existing DNS record with new data. This is a full overwrite — all required fields (host, type, answer, ttl) must be included in the request body. If you omit a field, the existing value will not be preserved and the request may fail. Use [GetRecord](/api/v1/reference/dns/get-record) beforehand to retrieve the current values if you intend to modify just one field. The record ID must belong to a domain you manage.
      operationId: UpdateRecord
      parameters:
        - description: DomainName is the zone that the record belongs to.
          in: path
          name: domainName
          required: true
          schema:
            type: string
        - description: Unique record id. Value is ignored on Create, and must match the URI on Update.
          in: path
          name: id
          required: true
          schema:
            format: int32
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DNSUpdateRecordBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Record'
          description: A successful response.
        '400':
          description: Bad request - Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or DNS record not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Update Record
      tags:
        - DNS
  /core/v1/domains/{domainName}/url/forwarding:
    get:
      deprecated: true
      description: Returns all URL forwarding settings configured for a domain. **Deprecated.** Use [List URL Forwardings by domain](/api/v1/reference/url-forwardings/list-urlforwardings-by-domain) instead, which returns entries with an `id` for use with by-ID endpoints.
      operationId: ListURLForwardings
      parameters:
        - description: DomainName is the domain to list URL forwarding entries for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
            example: example.com
            format: hostname
        - description: Per Page is the number of records to return per request. Per Page defaults to 500.
          in: query
          name: perPage
          schema:
            allOf:
              - $ref: '#/components/schemas/PerPageLimit'
              - default: 500
                example: 100
        - description: Page is which page to return. Starts at 1 for first page.
          in: query
          name: page
          schema:
            format: int32
            type: integer
            default: 1
            minimum: 1
            example: 1
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListURLForwardingsResponse'
          headers:
            Link:
              description: String delimited list of links for pagination
              schema:
                type: string
                example: <https://api.dev.name.com?page=3; rel="next">,<https://api.dev.name.com?page=1; rel="prev">,<https://api.dev.name.com?page=10; rel="last">
          description: A successful response containing the list of URL forwarding entries.
        '400':
          description: Bad Request - Invalid parameters or malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain not found or not owned by the authenticated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: List URLForwardings
      tags:
        - URL Forwardings
    post:
      description: Sets up a new URL forwarding (redirect) for a domain or subdomain. If this is the first URL forwarding entry, it may modify the A records for the domain accordingly. Note that changes may take up to 24 hours to fully propagate.
      operationId: CreateURLForwarding
      parameters:
        - description: DomainName is the domain part of the hostname to forward.
          in: path
          name: domainName
          required: true
          schema:
            type: string
            example: example.com
            format: hostname
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/URLForwardingInput'
        required: true
        description: URL forwarding details to create
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/URLForwardingResponse'
          description: A successful response containing the created URL forwarding entry.
        '400':
          description: Bad Request - Invalid parameters or malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Not Found - The specified domain was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '409':
          description: Conflict - A URL forwarding entry already exists for this host.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericConflict409'
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Create URLForwarding
      tags:
        - URL Forwardings
  /core/v1/domains/{domainName}/url/forwarding/{host}:
    delete:
      deprecated: true
      description: Removes a URL forwarding configuration from the domain. This operation cannot be undone. **Deprecated.** Use [Delete URL Forwarding by ID](/api/v1/reference/url-forwardings/delete-urlforwarding-by-id) instead.
      operationId: DeleteURLForwarding
      parameters:
        - description: DomainName is the domain to delete the URL forwarding entry from.
          in: path
          name: domainName
          required: true
          schema:
            type: string
            example: example.com
            format: hostname
        - description: The full hostname, including subdomain.
          in: path
          name: host
          required: true
          schema:
            type: string
            format: hostname
            example: www.example.org
      responses:
        '204':
          description: URL Forwarding entry successfully deleted.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or URL forwarding entry not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Delete URLForwarding
      tags:
        - URL Forwardings
    get:
      deprecated: true
      description: Retrieves the details of a specific URL forwarding configuration. **Deprecated.** Use [Get URL Forwarding by ID](/api/v1/reference/url-forwardings/get-urlforwarding-by-id) instead.
      operationId: GetURLForwarding
      parameters:
        - description: DomainName is the domain to get the URL forwarding entry for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
            example: example.com
            format: hostname
        - description: The full hostname, including subdomain.
          in: path
          name: host
          required: true
          schema:
            type: string
            format: hostname
            example: www.example.org
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/URLForwardingResponse'
          description: A successful response containing the requested URL forwarding entry.
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or URL forwarding entry not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Get URLForwarding
      tags:
        - URL Forwardings
    put:
      deprecated: true
      description: Modifies an existing URL forwarding rule. Changes may take up to 24 hours to fully propagate. **Deprecated.** Use [Update URL Forwarding by ID](/api/v1/reference/url-forwardings/update-urlforwarding-by-id) instead.
      operationId: UpdateURLForwarding
      parameters:
        - description: DomainName is the domain part of the hostname to forward.
          in: path
          name: domainName
          required: true
          schema:
            type: string
            example: example.com
            format: hostname
        - description: The full hostname, including subdomain.
          in: path
          name: host
          required: true
          schema:
            type: string
            format: hostname
            example: www.example.org
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/URLForwardingUpdate'
        required: true
        description: Updated URL forwarding configuration
      responses:
        '200':
          description: A successful response containing the updated URL forwarding entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/URLForwardingResponse'
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or URL forwarding entry not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Update URLForwarding
      tags:
        - URL Forwardings
  /core/v1/urlforwarding/{domainName}:
    get:
      description: Returns all URL forwarding settings configured for a domain. Each entry includes an `id` that can be used with the URL Forwarding by-ID endpoints to get, update, or delete records.
      operationId: ListURLForwardingsByDomain
      parameters:
        - description: DomainName is the domain to list URL forwarding entries for. The domain must be owned by the authenticated account.
          in: path
          name: domainName
          required: true
          schema:
            type: string
            example: example.com
            format: hostname
        - description: Per Page is the number of records to return per request. Per Page defaults to 500.
          in: query
          name: perPage
          schema:
            allOf:
              - $ref: '#/components/schemas/PerPageLimit'
              - default: 500
                example: 100
        - description: Page is which page to return. Starts at 1 for first page.
          in: query
          name: page
          schema:
            format: int32
            type: integer
            default: 1
            minimum: 1
            example: 1
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListURLForwardingsResponse'
          headers:
            Link:
              description: String delimited list of links for pagination
              schema:
                type: string
                example: <https://api.dev.name.com?page=3; rel="next">,<https://api.dev.name.com?page=1; rel="prev">,<https://api.dev.name.com?page=10; rel="last">
          description: A successful response containing the list of URL forwarding entries.
        '400':
          description: Bad Request - Invalid parameters or malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain not found or not owned by the authenticated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: List URL Forwardings by domain
      tags:
        - URL Forwardings
  /core/v1/urlforwarding/{domainName}/{id}:
    get:
      description: Retrieves the details of a specific URL forwarding configuration by ID.  The domain must be owned by the authenticated account.
      operationId: GetURLForwardingById
      parameters:
        - description: DomainName is the domain that owns the URL forwarding entry. Must be owned by the authenticated account.
          in: path
          name: domainName
          required: true
          schema:
            type: string
            example: example.com
            format: hostname
        - description: ID is the server-assigned unique identifier for the URL forwarding record (returned in list responses).
          in: path
          name: id
          required: true
          schema:
            type: integer
            format: int32
            example: 12345
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/URLForwardingResponse'
          description: A successful response containing the requested URL forwarding entry.
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or URL forwarding entry not found, or domain not owned by the authenticated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Get URL Forwarding by ID
      tags:
        - URL Forwardings
    patch:
      description: Modifies an existing URL forwarding rule by ID.  The domain must be owned by the authenticated account. Changes may take up to 24 hours to fully propagate.
      operationId: UpdateURLForwardingById
      parameters:
        - description: DomainName is the domain that owns the URL forwarding entry. Must be owned by the authenticated account.
          in: path
          name: domainName
          required: true
          schema:
            type: string
            example: example.com
            format: hostname
        - description: ID is the server-assigned unique identifier for the URL forwarding record (returned in list responses).
          in: path
          name: id
          required: true
          schema:
            type: integer
            format: int32
            example: 12345
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/URLForwardingUpdate'
        required: true
        description: Updated URL forwarding configuration
      responses:
        '200':
          description: A successful response containing the updated URL forwarding entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/URLForwardingResponse'
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or URL forwarding entry not found, or domain not owned by the authenticated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Update URL Forwarding by ID
      tags:
        - URL Forwardings
    delete:
      description: Removes a URL forwarding configuration by ID. The domain must be owned by the authenticated account. This operation cannot be undone.
      operationId: DeleteURLForwardingById
      parameters:
        - description: DomainName is the domain that owns the URL forwarding entry. Must be owned by the authenticated account.
          in: path
          name: domainName
          required: true
          schema:
            type: string
            example: example.com
            format: hostname
        - description: ID is the server-assigned unique identifier for the URL forwarding record (returned in list responses).
          in: path
          name: id
          required: true
          schema:
            type: integer
            format: int32
            example: 12345
      responses:
        '204':
          description: URL Forwarding entry successfully deleted.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or URL forwarding entry not found, or domain not owned by the authenticated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Delete URL Forwarding by ID
      tags:
        - URL Forwardings
  /core/v1/domains/{domainName}/vanity_nameservers:
    get:
      summary: List Vanity Nameservers
      description: Lists all vanity nameserver hostnames configured for a domain.
      operationId: ListVanityNameservers
      tags:
        - Vanity Nameservers
      parameters:
        - name: domainName
          in: path
          description: The domain name to list vanity nameservers for.
          required: true
          schema:
            type: string
            format: hostname
            example: example.com
        - name: perPage
          in: query
          description: The number of records to return per page. Defaults to 500.
          schema:
            allOf:
              - $ref: '#/components/schemas/PerPageLimit'
              - default: 500
                example: 50
          style: form
          explode: true
        - name: page
          in: query
          description: The page number to return.
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
            example: 2
          style: form
          explode: true
      responses:
        '200':
          description: List of vanity nameservers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVanityNameserversResponse'
          headers:
            Link:
              description: String delimited list of links for pagination
              schema:
                type: string
                example: <https://api.dev.name.com?page=3; rel="next">,<https://api.dev.name.com?page=1; rel="prev">,<https://api.dev.name.com?page=10; rel="last">
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
    post:
      summary: Create Vanity Nameserver
      description: Register a new vanity nameserver for the specified domain.
      operationId: CreateVanityNameserver
      tags:
        - Vanity Nameservers
      parameters:
        - name: domainName
          in: path
          description: The domain name to create a vanity nameserver for.
          required: true
          schema:
            type: string
            format: hostname
            example: example.com
      requestBody:
        description: Details of the vanity nameserver to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVanityNameserverBody'
      responses:
        '200':
          description: Vanity nameserver successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VanityNameserverResponse'
        '400':
          description: Bad request - Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '409':
          description: Vanity nameserver already exists for this domain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericConflict409'
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
  /core/v1/domains/{domainName}/vanity_nameservers/{hostname}:
    delete:
      summary: Delete Vanity Nameserver
      description: Deletes a vanity nameserver from the domain’s registry settings. This operation might fail if the registry detects the nameserver is still in use.
      operationId: DeleteVanityNameserver
      tags:
        - Vanity Nameservers
      parameters:
        - name: domainName
          in: path
          description: The domain name associated with the vanity nameserver.
          required: true
          schema:
            type: string
            format: hostname
            example: example.com
        - name: hostname
          in: path
          description: The hostname of the vanity nameserver to delete.
          required: true
          schema:
            type: string
            format: hostname
            example: ns1.example.com
      responses:
        '204':
          description: Vanity nameserver successfully deleted.
        '400':
          description: Bad request - Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or vanity nameserver hostname not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
    get:
      summary: Get Vanity Nameserver
      description: Retrieves details for a of a specific vanity nameserver (including its IP addresses).
      operationId: GetVanityNameserver
      tags:
        - Vanity Nameservers
      parameters:
        - name: domainName
          in: path
          description: The domain name associated with the vanity nameserver.
          required: true
          schema:
            type: string
            format: hostname
            example: example.com
        - name: hostname
          in: path
          description: The hostname of the vanity nameserver to retrieve.
          required: true
          schema:
            type: string
            format: hostname
            example: ns1.example.com
      responses:
        '200':
          description: Details of the vanity nameserver.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VanityNameserverResponse'
        '400':
          description: Bad request - Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or vanity nameserver hostname not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
    put:
      summary: Update Vanity Nameserver IP
      description: Updates the glue record IP addresses for a vanity nameserver.
      operationId: UpdateVanityNameserver
      tags:
        - Vanity Nameservers
      parameters:
        - name: domainName
          in: path
          description: The domain name associated with the vanity nameserver.
          required: true
          schema:
            type: string
            format: hostname
            example: example.com
        - name: hostname
          in: path
          description: The hostname of the vanity nameserver to update.
          required: true
          schema:
            type: string
            format: hostname
            example: ns1.example.com
      requestBody:
        description: Updated IP addresses for the vanity nameserver.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVanityNameserverBody'
      responses:
        '200':
          description: Vanity nameserver successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VanityNameserverResponse'
        '400':
          description: Bad request - Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain or vanity nameserver hostname not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
  /core/v1/domains/{domainName}:disableAutorenew:
    post:
      description: Turns off automatic renewal for a domain. **DEPRECATED** This endpoint is deprecated in favor of the new UpdateDomain API. This will be removed in a future release.
      operationId: DisableAutorenew
      deprecated: true
      parameters:
        - description: DomainName is the domain name to disable autorenew for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
          example: example.com
      requestBody:
        required: true
        description: 'No fields are accepted. Send an empty JSON object `{}` with `Content-Type: application/json`.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyObject'
            example: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
          description: A successful response.
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Disable Autorenew
      tags:
        - Domains
  /core/v1/domains/{domainName}:disableWhoisPrivacy:
    post:
      description: Disables WHOIS privacy protection on a domain. **DEPRECATED** This endpoint is deprecated in favor of the new UpdateDomain API. This will be removed in a future release.
      operationId: DisableWhoisPrivacy
      deprecated: true
      parameters:
        - description: DomainName is the domain name to disable whoisprivacy for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
          example: example.com
      requestBody:
        required: true
        description: 'No fields are accepted. Send an empty JSON object `{}` with `Content-Type: application/json`.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyObject'
            example: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
          description: A successful response.
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Disable Whois Privacy
      tags:
        - Domains
  /core/v1/domains/{domainName}:enableAutorenew:
    post:
      description: Turns on automatic renewal for a domain. **DEPRECATED** This endpoint is deprecated in favor of the new UpdateDomain API. This will be removed in a future release.
      operationId: EnableAutorenew
      deprecated: true
      parameters:
        - description: DomainName is the domain name to enable autorenew for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
          example: example.com
      requestBody:
        required: true
        description: 'No fields are accepted. Send an empty JSON object `{}` with `Content-Type: application/json`.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyObject'
            example: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
          description: A successful response.
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Enable Autorenew
      tags:
        - Domains
  /core/v1/domains/{domainName}:enableWhoisPrivacy:
    post:
      description: Enables WHOIS privacy protection on a domain. **DEPRECATED** This endpoint is deprecated in favor of the new UpdateDomain API. This will be removed in a future release.
      operationId: EnableWhoisPrivacy
      deprecated: true
      parameters:
        - description: DomainName is the domain name to enable whoisprivacy for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
      requestBody:
        required: true
        description: 'No fields are accepted. Send an empty JSON object `{}` with `Content-Type: application/json`.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyObject'
            example: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
          description: A successful response.
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Enable Whois Privacy
      tags:
        - Domains
  /core/v1/domains/{domainName}:getAuthCode:
    get:
      description: Retrieves the transfer authorization code (EPP code) for a domain.
      operationId: GetAuthCodeForDomain
      parameters:
        - name: domainName
          description: DomainName is the domain name to retrieve the authorization code for.
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthCodeResponse'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain name not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '406':
          description: We were unable to retrieve an auth code for the domain. You will need to reach out to the registrar for more information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError500'
              example:
                message: No authcode found
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Get Auth Code For Domain
      tags:
        - Domains
  /core/v1/domains/{domainName}:getPricing:
    get:
      description: |
        Returns registration, renewal, and transfer pricing for a domain and term.

        **Not a discovery endpoint:** Does not return `purchaseType`. Cannot determine whether a domain is acquired via registration vs aftermarket/expiring/backorder — call [Search](/api/v1/reference/domains/search) or [Check Availability](/api/v1/reference/domains/check-availability) first.

        **Scope:** `purchasePrice` and `premium` reflect **standard and registry-premium registration** only. They do **not** return aftermarket, expiring, or backorder acquisition prices. For those types, use `purchasePrice` from Search or Check Availability.

        **Registration create (`purchaseType: registration`):** When create requires `purchasePrice` (registry premium), call with the **same** `years` you will send on create. Pass `purchasePrice` directly — it is the **total** for that term, not a per-year component.

        **Renew:** Pass `renewalPrice` as `purchasePrice` on [Renew Domain](/api/v1/reference/domains/renew-domain) for premium renewals — not for computing Create Domain totals.

        **Transfer:** Pass `transferPrice` as `purchasePrice` on [Create Transfer](/api/v1/reference/transfers/create-transfer) for premium transfers. The `years` query parameter does not affect `transferPrice`.

        See the [Domain pricing guide](/guides/domain-pricing) for the full workflow.
      operationId: GetPricingForDomain
      parameters:
        - name: domainName
          description: DomainName is the domain to retrieve.
          in: path
          required: true
          schema:
            type: string
        - name: years
          description: 'Years specifies the registration term to price in years. Defaults to each TLD''s minimum registration term if omitted — usually 1 year (2 for `.ai`). Must be a supported registration term for the TLD (commonly 1–10 years). Use the same value on Create Domain when passing `purchasePrice` for `purchaseType: registration`.'
          in: query
          schema:
            format: int32
            type: integer
            minimum: 1
            maximum: 10
            example: 2
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PricingResponse'
          description: A successful response.
        '400':
          description: Bad request - Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
              examples:
                invalidYears:
                  summary: Invalid registration term
                  value:
                    message: Invalid value for years for this domain
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain name not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '422':
          description: TLD not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity422'
              examples:
                tldNotSupported:
                  summary: TLD not supported
                  value:
                    message: Unsupported TLD
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Get Pricing For Domain
      tags:
        - Domains
  /core/v1/domains/{domainName}:lock:
    post:
      description: Locks a domain to prevent it from being transferred. **DEPRECATED** This endpoint is deprecated in favor of the new UpdateDomain API. This will be removed in a future release.
      operationId: LockDomain
      deprecated: true
      parameters:
        - description: DomainName is the domain name to lock.
          in: path
          name: domainName
          required: true
          schema:
            type: string
          example: example.com
      requestBody:
        required: true
        description: 'No fields are accepted. Send an empty JSON object `{}` with `Content-Type: application/json`.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyObject'
            example: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
          description: A successful response.
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Lock Domain
      tags:
        - Domains
  /core/v1/domains/{domainName}:purchasePrivacy:
    post:
      description: Adds or renews WHOIS privacy protection for a domain. This is used to ensure personal contact details remain hidden from public WHOIS lookups.  If WHOIS privacy is already enabled, this will extend the protection. If it’s not yet active, this will enable the service.  WHOIS privacy is free for API users and does not add a fee.
      operationId: PurchasePrivacy
      parameters:
        - description: DomainName is the domain to enable or extend Whois Privacy for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
        - name: X-Idempotency-Key
          in: header
          description: A unique string (e.g., a UUID v4) to make the request idempotent. This key ensures that if the request is retried, the operation will not be performed multiple times. Subsequent requests with the same key will return the original result.
          schema:
            type: string
            example: 083910ef-04e4-4bd1-a0bf-3737fe005ca8
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainsPurchasePrivacyBody'
        required: true
      responses:
        '200':
          headers:
            X-Idempotency-Key:
              description: If the initial request contained this header, echoes back with the initial value.
              schema:
                type: string
                example: 083910ef-04e4-4bd1-a0bf-3737fe005ca8
            X-Idempotent-Replay:
              description: Indicates that the response is being replayed from an idempotent request. This header will only be returned if the API is responding with cached data. Caches are cleared after 1 hour.
              schema:
                type: number
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivacyResponse'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '402':
          description: Payment has failed for this transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired402'
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: The requested domain could not be located.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '409':
          description: Conflict - Idempotency key reused for a different request, or privacy protection already exists for this domain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict409'
              examples:
                idempotencyConflict:
                  summary: Idempotency key reused
                  value:
                    message: Conflict
                    details: Idempotency key has been reused for a different request.
                privacyAlreadyExists:
                  summary: Privacy already exists
                  value:
                    message: Conflict
                    details: Privacy protection already exists for this domain.
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '422':
          description: TLD not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity422'
              examples:
                tldNotSupported:
                  summary: TLD not supported
                  value:
                    message: Unsupported TLD
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Purchase Privacy
      tags:
        - Domains
  /core/v1/domains/{domainName}:renew:
    post:
      description: Renews an existing domain for an additional registration period. Include the domain name and renewal term. Omit `purchasePrice` for standard (non-premium) renewals. For premium renewals, pass `renewalPrice` from [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) with matching `years` as `purchasePrice`. Renewal pricing is separate from Create Domain registration/acquisition pricing. This is typically used to extend ownership before a domain’s expiration.
      operationId: RenewDomain
      parameters:
        - description: DomainName is the domain to renew.
          in: path
          name: domainName
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainsRenewDomainBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenewDomainResponse'
          description: A successful response.
        '400':
          description: Invalid purchase price.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
              examples:
                premiumRenewalPriceRequired:
                  summary: Premium renewal price required
                  value:
                    message: Purchase price is required for premium domains in order to complete this request
                priceMismatch:
                  summary: Purchase price does not match
                  value:
                    message: Purchase price does not match
                invalidYears:
                  summary: Invalid renewal term
                  value:
                    message: Invalid years
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain name not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '422':
          description: Pricing information unavailable, or TLD not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity422'
              examples:
                pricingUnavailable:
                  summary: Pricing unavailable for domain
                  value:
                    message: Domain pricing unavailable
                    details: The pricing information required to process this request is temporarily unavailable. This is an internal system error. Please try again in a few minutes or contact support if the issue persists.
                tldNotSupported:
                  summary: TLD not supported
                  value:
                    message: Unsupported TLD
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Renew Domain
      tags:
        - Domains
  /core/v1/domains/{domainName}:setContacts:
    post:
      description: |-
        Updates WHOIS contact information for a domain. This includes the registrant, administrative, technical, and billing contacts.  All contact objects must be complete — partial updates are not supported.  You should fetch the existing contact data first (e.g., via [GetDomain](/api/v1/reference/domains/get-domain) and modify only the values you wish to change.  This call replaces all four contact sets at once.
        #### Contact Verification
        When registrant contact information is updated, validation may be triggered if the new contact information has not been previously validated. This validation is required by ICANN for all TLDs except country-code TLDs (ccTLDs). This validation involves sending an email to the provided address, prompting the recipient to click a link to verify their email address.
      operationId: SetContacts
      parameters:
        - description: DomainName is the domain name to set the contacts for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
            example: example.com
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainsSetContactsBody'
        required: true
      responses:
        '200':
          description: A successful response with updated domain contact information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainResponsePayload'
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Set Contacts
      tags:
        - Domains
  /core/v1/domains/{domainName}:setNameservers:
    post:
      description: SetNameservers will set the nameservers for the Domain. This operation updates the DNS configuration by changing which nameservers are responsible for the domain's zone.
      operationId: SetNameservers
      parameters:
        - description: DomainName is the domain name to set the nameservers for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
            example: example.com
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainsSetNameserversBody'
        required: true
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainResponsePayload'
        '400':
          description: Bad request — invalid parameters or the registry rejected the update because the domain's status prohibits it (EPP 2304, for example clientUpdateProhibited). Remove the blocking lock or hold, then retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
              examples:
                domainStatusProhibitsUpdate:
                  summary: Domain status prohibits nameserver update
                  value:
                    message: Domain status does not allow this operation.
                    details: Command Failed - The Domain Cannot Be Updated (clientUpdateProhibited).
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Set Nameservers
      tags:
        - Domains
  /core/v1/domains/{domainName}:unlock:
    post:
      description: Unlocks a domain to allow it to be transferred. **DEPRECATED** This endpoint is deprecated in favor of the new UpdateDomain API. This will be removed in a future release.
      operationId: UnlockDomain
      deprecated: true
      parameters:
        - description: DomainName is the domain name to unlock.
          in: path
          name: domainName
          required: true
          schema:
            type: string
      requestBody:
        required: true
        description: 'No fields are accepted. Send an empty JSON object `{}` with `Content-Type: application/json`.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyObject'
            example: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
          description: A successful response.
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Unlock Domain
      tags:
        - Domains
  /core/v1/domains:checkAvailability:
    post:
      description: |
        Checks whether up to 50 domain names are purchasable and returns **discovery** pricing for each result.

        **Discovery endpoint:** Returns `SearchResult` fields — `purchaseType`, `purchasePrice`, `premium`, `purchasable`. [Search](/api/v1/reference/domains/search) returns the same fields for keyword/suggestion flows. Use this endpoint to determine what to send on [Create Domain](/api/v1/reference/domains/create-domain).

        When results show `premium: true` or a non-`registration` `purchaseType`, follow the [Domain pricing guide](/guides/domain-pricing) before calling Create Domain. For non-registration types, re-check Check Availability immediately before create — acquisition prices can change.

        **Recommendation:** Set `purchaseType` to `registration`. Most resellers 
        restrict results to domains with a `purchaseType` of `registration`
        to ensure predictable pricing and immediate fulfillment. Other purchase types
        (such as aftermarket variants) can introduce higher costs and non-instant
        transactions that may be delayed or declined by third parties.
      operationId: CheckAvailability
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvailabilityRequest'
        description: AvailabilityRequest is used to list the domain names to check availability for.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '422':
          description: The request was well-formed but contains no valid domains to check. This occurs when all provided domain names contain TLDs that are not supported or available for registration. The request must contain at least one domain with a valid TLD.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity422'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Check Availability
      tags:
        - Domains
  /core/v1/domains:search:
    post:
      description: |
        Searches for domain name suggestions based on a keyword or term. Important: Do not
        encode the `:` in the path. Use `/core/v1/domains:search`, not `/core/v1/domains%3Asearch`.

        **Discovery endpoint:** Returns `SearchResult` fields — `purchaseType`, `purchasePrice`, `premium`, `purchasable`.

        **Recommendation:** Set `purchaseType` to `registration`. Most resellers restrict
        results to domains with a `purchaseType` of `registration` to ensure predictable
        pricing and immediate fulfillment. Other purchase types (such as aftermarket) can
        introduce higher costs and non-instant transactions that may be delayed or declined
        by third parties.
        With `purchaseType: registration`, domains that do not match the filter are **omitted** from results (unlike Check Availability, which returns them with `purchasable: false`).

        When results show `premium: true` or a non-`registration` `purchaseType`, follow the [Domain pricing guide](/guides/domain-pricing) before calling Create Domain. For all types, re-check with Check Availability immediately before create — prices and availability can change.
      operationId: Search
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
        description: SearchRequest is used to specify the search parameters.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
          description: A successful response.
        '400':
          description: Returned when an invalid request is made. The message will contain information on the field that is failing validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Search
      tags:
        - Domains
  /core/v1/hello:
    get:
      description: Returns basic information about the API server (useful for testing connectivity and version checks).
      operationId: Hello
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelloResponse'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Hello
      tags:
        - Hello
  /core/v1/notifications:
    get:
      description: Retrieves all active webhook subscriptions on the account.
      operationId: GetSubscribedNotifications
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSubscribedWebhooksResponse'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Get Subscribed Notifications
      tags:
        - Webhook Notifications
    post:
      description: |-
        Creates a webhook subscription to receive real-time notifications about specific domain or account events (e.g. transfer completions, renewals). Pass the callback URL and event types. This allows external systems to stay in sync with name.com changes.
        Supported webhook event names:
        - `account.credit.balance_change` – account credit balance changes (increases or decreases).
        - `account.domain.removal` – domain removed from the subscribing account.
        - `domain.lock.status_change` – domain lock added or removed.
        - `domain.transfer.status_change` – domain transfer IN to name.com; status updates while name.com is the gaining registrar.
        - `domain.transfer_out.status_change` – domain transfer OUT from name.com; `initiated`, `completed` (domain removed), or `canceled` (no longer pending at the registry).
        - `domain.transfer.internal_in` - name.com domain transfers in to the subscribing account via internal transfer.
        - `domain.transfer.internal_out` - name.com domain transfers out of the subscribing account via internal transfer.
        - `contact.verification.status_change` - contact verification status changes (verified or unverified).
        - `domain.registry.rejection` – domain **create** failed after asynchronous registry processing (uncommon; most creates succeed at request time).
        - `domain.registry.compliance_notice` – a registry requires policy remediation for a domain. Default is a registrant email (whitelabeled when configured); subscribe to send it yourself. If you have signed an addendum to assume all email responsibility, name.com does not send this email and the webhook is the only delivery path.
        - `domain.expiration` – domain has expired and entered the post-expiry grace period. This is informational only.
      operationId: SubscribeToNotification
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeToNotification'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscribeToNotificationResponse'
          description: A successful response.
        '400':
          description: Bad request - Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '409':
          description: The API will return this response if you are attempting to subscribe to a webhook you have already subscribed to.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict409'
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Subscribe to Notification
      tags:
        - Webhook Notifications
  /core/v1/notifications/{id}:
    delete:
      description: Removes a webhook subscription from the account.
      operationId: DeleteSubscription
      parameters:
        - description: ID of the subscription to delete.
          in: path
          name: id
          required: true
          schema:
            format: int32
            type: integer
      responses:
        '204':
          description: Subscription successfully deleted.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: The requested resource could not be located.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Delete Subscription
      tags:
        - Webhook Notifications
    put:
      description: Updates an existing webhook’s configuration.  This may include changing the callback URL or updating whether the webhook is currently active.
      operationId: ModifySubscription
      parameters:
        - description: ID of the subscription to update.
          in: path
          name: id
          required: true
          schema:
            format: int32
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: Optionally update the URL we send the webhook data to
                  example: https://example2.com
                  format: uri
                active:
                  type: boolean
                  description: Optionally update if the subscription is currently active
                  example: false
              anyOf:
                - type: object
                  properties:
                    url:
                      type: string
                  required:
                    - url
                - type: object
                  properties:
                    active:
                      type: boolean
                  required:
                    - active
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModifySubscriptionResponse'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: The requested resource could not be located.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Modify Subscription
      tags:
        - Webhook Notifications
  /core/v1/orders:
    get:
      description: Retrieves a list of all orders placed in the account.
      operationId: ListOrders
      parameters:
        - name: perPage
          description: Per Page is the number of records to return per request. Per Page defaults to 500.
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/PerPageLimit'
              - default: 500
        - name: page
          description: Page is which page to return.
          in: query
          schema:
            format: int32
            type: integer
            default: 1
            minimum: 1
        - name: dir
          description: Dir indicates direction of list order. Possible values are 'asc' (default) or 'desc'.
          in: query
          schema:
            type: string
        - name: domainName
          description: DomainName filters orders by domain name. Supports exact match or wildcard (starts with '*').
          in: query
          schema:
            type: string
        - name: tld
          description: Tld filters orders by tld.
          in: query
          schema:
            type: string
        - name: createDateStart
          description: CreateDateStart filters orders created on or after this date.
          in: query
          schema:
            type: string
        - name: createDateEnd
          description: CreateDateEnd filters orders created on or before this date.
          in: query
          schema:
            type: string
        - name: type
          description: Type filters orders by order item type (e.g., 'registration', 'renewal', 'transfer', 'whois_privacy').
          in: query
          schema:
            type: string
        - name: orderStatus
          description: OrderStatus filters orders by status.
          in: query
          schema:
            type: string
            enum:
              - success
              - failed
              - initialized
              - review
              - started
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOrdersResponse'
          description: A successful response.
          headers:
            Link:
              description: String delimited list of links for pagination
              schema:
                type: string
                example: <https://api.dev.name.com?page=3; rel="next">,<https://api.dev.name.com?page=1; rel="prev">,<https://api.dev.name.com?page=10; rel="last">
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: List Orders
      tags:
        - Orders
  /core/v1/orders/{orderId}:
    get:
      description: Fetches full details about a specific order using its ID. This includes domains, prices, and timestamps.  Useful for confirming transactions, receipts, or generating invoices.
      operationId: GetOrder
      parameters:
        - description: OrderId is the unique identifier of the requested order.
          in: path
          name: orderId
          required: true
          schema:
            format: int32
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Order not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Get Order
      tags:
        - Orders
  /core/v1/refund:
    post:
      description: |
        Deletes eligible domains and security products during the Add Grace Period (AGP) and automatically issues refunds for the associated order items.

        ### Eligibility Requirements

        - **Product Types**: Only `registration` and `whois_privacy` product types are eligible for refunds.
        - **AGP Timing**: Items must be within the Add Grace Period (typically 5 days from registration, varies by TLD).
        - **Order Ownership**: All `orderItemIds` must belong to the specified `orderId`.

        ### Refund Processing

        Refunds are processed in the following order:
        1. Domain deletion is attempted for each eligible order item
        2. Upon successful deletion, the refund is issued
        3. Refunds are sent to the original payment method on file
        4. If the original payment method is unavailable, the refund is credited to the account balance

        ### Idempotency

        This endpoint supports idempotent requests via the `X-Idempotency-Key` header. If you retry a request with the same idempotency key, you will receive the same response as the original request. This is useful for safely retrying requests without risk of processing duplicate refunds.
      operationId: ProcessRefund
      parameters:
        - name: X-Idempotency-Key
          in: header
          description: A unique string (e.g., a UUID v4) to make the request idempotent. This key ensures that if the request is retried, the operation will not be performed multiple times. Subsequent requests with the same key will return the original result. Idempotency keys are valid for 1 hour.
          schema:
            type: string
            example: 083910ef-04e4-4bd1-a0bf-3737fe005ca8
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
            examples:
              singleItem:
                summary: Refund a single order item
                description: Request to refund a single domain registration from an order.  If there is a security product associated with the domain, it will also be refunded.
                value:
                  orderId: 123456
                  orderItemIds:
                    - 987654
              multipleItems:
                summary: Refund multiple order items
                description: Request to refund multiple items (e.g., domain registration and security product) from a single order.
                value:
                  orderId: 123456
                  orderItemIds:
                    - 987654
                    - 987655
        description: RefundRequest contains the order ID and array of order item IDs to be refunded.
        required: true
      responses:
        '200':
          headers:
            X-Idempotency-Key:
              description: If the initial request contained this header, echoes back with the initial value.
              schema:
                type: string
                example: 083910ef-04e4-4bd1-a0bf-3737fe005ca8
            X-Idempotent-Replay:
              description: Indicates that the response is being replayed from an idempotent request. This header will only be returned if the API is responding with cached data. Caches are cleared after 1 hour.
              schema:
                type: number
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
              examples:
                successfulRefund:
                  summary: Successful refund of domain registration
                  value:
                    results:
                      - orderId: 123456
                        orderItemId: 987654
                        orderItemStatus: refunded
                        refundAmount: 10.99
                        message: Domain successfully deleted and refund processed.
                    totalRefundAmount: 10.99
          description: Refund processed successfully. The response includes the detailed results for each refunded item.
        '400':
          description: Bad request - Invalid input data or order item has already been refunded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
              examples:
                alreadyRefunded:
                  summary: Order item already refunded
                  value:
                    message: Bad Request
                    details: Order item 987654 has already been refunded.
                invalidProductType:
                  summary: Invalid product type
                  value:
                    message: Bad Request
                    details: Order item 987654 is not eligible for refund. Only 'registration' and 'whois_privacy' product types are supported.
                emptyOrderItems:
                  summary: Empty order items array
                  value:
                    message: Bad Request
                    details: orderItemIds array must contain at least one item.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Not Found - Order ID or order item ID does not exist, or order items do not belong to the specified order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
              examples:
                orderNotFound:
                  summary: Order not found
                  value:
                    message: Not Found
                    details: Order with ID 123456 does not exist.
                itemNotFound:
                  summary: Order item not found
                  value:
                    message: Not Found
                    details: Order item 987654 does not exist or does not belong to order 123456.
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '409':
          description: Conflict - Idempotency key reused for different request, or AGP delete threshold exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict409'
              examples:
                idempotencyConflict:
                  summary: Idempotency key reused
                  value:
                    message: Conflict
                    details: Idempotency key has been reused for a different request.
                thresholdExceeded:
                  summary: AGP threshold exceeded
                  value:
                    message: Conflict
                    details: AGP delete threshold has been exceeded for this account. Please contact support.
        '415':
          description: 'Unsupported Media Type - All POST requests must include the `Content-Type: application/json` header.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '423':
          description: Locked - The deletion timing is outside registry limits. The Add Grace Period (AGP) has expired for one or more items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Locked423'
              examples:
                agpExpired:
                  summary: AGP window expired
                  value:
                    message: Resource Locked
                    details: The Add Grace Period (AGP) deletion window has expired for domain example.com. AGP deletes are only allowed within 5 days of registration.
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway - Registry connection unavailable or registry-related problem occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGateway502'
              examples:
                registryError:
                  summary: Registry connection error
                  value:
                    message: Registry Connection Unavailable
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Process Refund
      tags:
        - Refunds
  /core/v1/transfers:
    get:
      description: Returns all domain transfer requests for the account, including in-progress and recent transfers.
      operationId: ListTransfers
      parameters:
        - description: Per Page is the number of records to return per request. Per Page defaults to 500.
          in: query
          name: perPage
          schema:
            allOf:
              - $ref: '#/components/schemas/PerPageLimit'
              - default: 500
        - description: Page is which page to return.
          in: query
          name: page
          schema:
            format: int32
            type: integer
            minimum: 1
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTransfersResponse'
          headers:
            Link:
              description: String of comma delimited links for pagination of the response
              schema:
                type: string
                example: <https:\\api.dev.name.com?page=3; rel="next">,<https:\\api.dev.name.com?page=1; rel="prev">,<https:\\api.dev.name.com?page=10; rel="last">
          description: A successful response.
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '402':
          description: Payment has failed for this transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired402'
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: List Transfers
      tags:
        - Transfers
    post:
      description: |-
        Initiates a domain transfer into your name.com account from another registrar. You must provide the domain name and its valid transfer authorization code (EPP code). The domain must not be locked or under any transfer restrictions (e.g. clientTransferProhibited). If successful, the transfer is submitted and tracked through the ICANN transfer process. Once a transfer has been created, you can track its progress via the [GetTransfer](/api/v1/reference/transfers/get-transfer) endpoint.
        **Transfer pricing:** Omit `purchasePrice` for standard (non-premium) transfers. For premium transfers, pass `transferPrice` from [Get Pricing For Domain](/api/v1/reference/domains/get-pricing-for-domain) as `purchasePrice`. If sent, it must match Get Pricing `transferPrice` exactly or the request will fail. Premium transfers without `purchasePrice` will fail. See the [Domain pricing guide](/guides/domain-pricing) for how [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) `transferPrice` relates to the `years` query parameter.
        **Optional `contacts`** - Omit for account defaults; provided roles override; omitted roles use defaults.
      operationId: CreateTransfer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTransferRequest'
        description: CreateTransferRequest passes the required transfer info to the CreateTransfer function.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTransferResponse'
          description: A successful response.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
              examples:
                premiumPriceRequired:
                  summary: Premium transfer requires purchasePrice
                  value:
                    message: PurchasePrice is required if the domain to transfer is a premium domain
                priceMismatch:
                  summary: Transfer price does not match
                  value:
                    message: Invalid Price
          description: There was an invalid or missing argument in the request. The response messages will indicate which fields are invalid.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '402':
          description: The account placing the order has insufficient account credit to process this transfer order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError500'
              example:
                message: Insufficient Funds
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '409':
          description: The status of the domain indicates that we are unable to process a transfer for it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericConflict409'
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '422':
          description: Pricing information unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity422'
              examples:
                pricingUnavailable:
                  summary: Pricing unavailable for domain
                  value:
                    message: Domain pricing unavailable
                    details: The pricing information required to process this request is temporarily unavailable. This is an internal system error. Please try again in a few minutes or contact support if the issue persists.
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Unable to retrieve domain status due to blocked-hostname.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeout504'
      summary: Create Transfer
      tags:
        - Transfers
  /core/v1/transfers/{domainName}:
    get:
      description: Retrieves details of a specific domain transfer request.
      operationId: GetTransfer
      parameters:
        - description: DomainName is the domain you want to get the transfer information for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
          description: A successful response.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
          description: We were unable to locate a transfer for the requested domain.
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '422':
          description: TLD not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity422'
              examples:
                tldNotSupported:
                  summary: TLD not supported
                  value:
                    message: Unsupported TLD
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Get Transfer
      tags:
        - Transfers
  /core/v1/transfers/{domainName}:cancel:
    post:
      description: |
        Cancels a pending transfer request. This can be used if the transfer was initiated in error or if the authorization code provided was incorrect.
        The price of the transfer will refund the amount to account credit.

        Cancelable statuses:
        - pending
        - submitting_transfer
        - pending_new_auth_code
        - pending_unlock
        - pending_registry_unlock
        - rejected

        Non-cancelable statuses:
        - pending_transfer
        - pending_insert
        - completed
        - failed
        - canceled
        - canceled_pending_refund
      operationId: CancelTransfer
      parameters:
        - description: DomainName is the domain to cancel the transfer for.
          in: path
          name: domainName
          required: true
          schema:
            type: string
      requestBody:
        required: true
        description: 'No fields are accepted. Send an empty JSON object `{}` with `Content-Type: application/json`.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyObject'
            example: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
          description: A successful response.
        '400':
          description: Response returned when you have requested to cancel a transfer that has already been cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError500'
              example:
                message: A transfer for this domain has already been canceled.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
          description: We were unable to locate a cancelable transfer for the requested domain.
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '409':
          description: Response returned when the transfer cannot be canceled due to its current processing state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericConflict409'
              example:
                message: A transfer for this domain is already processing and cannot be canceled at this time.
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Cancel Transfer
      tags:
        - Transfers
  /core/v1/transfers/external/out/{domainName}:cancel:
    post:
      description: |-
        Cancels an outbound transfer for the given domain. Use this when the domain is being transferred out of name.com (losing registrar) to another (gaining) registrar and the registrant or reseller wants to cancel that transfer.
        On success, subscribers receive `domain.transfer_out.status_change` with status `canceled`.
        The endpoint validates that the domain exists and belongs to the authenticated account. Only domains in a pending transfer (out) state can be canceled.
      operationId: CancelOutboundTransfer
      parameters:
        - description: DomainName is the domain whose transfer out should be canceled.
          in: path
          name: domainName
          required: true
          schema:
            type: string
            example: example.com
      requestBody:
        required: true
        description: 'No fields are accepted. Send an empty JSON object `{}` with `Content-Type: application/json`.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyObject'
            example: {}
      responses:
        '200':
          description: Transfer out canceled successfully. Returns the domain name and updated status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelTransferOutResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain does not exist or does not belong to the authenticated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '409':
          description: Domain is not in a pending transfer (out) state and cannot be canceled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericConflict409'
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '422':
          description: The domain TLD does not support canceling an outbound transfer via losing-registrar explicit deny (EPP reject). Pending outbound transfers expire if they are not completed within the registry policy timeframe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity422'
              examples:
                tldDoesNotSupportExplicitReject:
                  summary: TLD does not support explicit outbound transfer reject
                  value:
                    message: This domain TLD does not support canceling an outbound transfer via losing-registrar explicit deny (EPP reject). Pending outbound transfers expire if they are not completed within the registry policy timeframe.
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError500'
        '502':
          description: The registry rejected the cancel command (e.g. registry unavailable or reject failed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGateway502'
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Cancel external transfer out
      tags:
        - Transfers
  /core/v1/transfers/internal/in:
    post:
      description: |-
        Pulls a domain from another [name.com](https://www.name.com) account into your reseller (gaining) account using a valid authorization code. This is an **internal** name.com-to-name.com move; it is separate from [Create Transfer](/api/v1/reference/transfers/create-transfer), which brings domains in from **external** registrars.
        Check if a TLD is eligible for internal transfer in by calling [Tld Requirements](/api/v1/reference/domaininfo/requirementsV2) for the TLD and checking property `supportsInternalTransfer`.
        This API is only available to approved reseller accounts. Contact name.com support to request access.
        #### Losing account (dashboard only)
        The party that holds the domain today must use the name.com dashboard on the **losing** account to **unlock** the domain (remove registrar transfer lock) and to **copy the authorization code** to provide to your integration. This endpoint does not unlock the domain or retrieve the auth code for the losing account.
        #### Gaining account (this API)
        Call this endpoint with `domainName`, `authCode`, and optional `contacts` using the **gaining** reseller's API credentials.
        #### Contacts and post-transfer lock
        If `contacts` is omitted, the gaining account's default contacts are applied. If `contacts` is provided, any roles included in the request are applied and omitted roles use the gaining account's default contacts (same pattern as [Create Domain](/api/v1/reference/domains/create-domain) and [Set Contacts](/api/v1/reference/domains/set-contacts)). The 60-day contact-change transfer lock is enforced based on the **gaining** account's settings, consistent with Set Contacts.
        #### Access
        Restricted to approved enterprise resellers; other callers receive `403 Forbidden`.
      operationId: CreateInternalTransferIn
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInternalTransferInRequest'
        required: true
      responses:
        '200':
          description: The domain was accepted into the gaining account. The response body matches the domain resource representation used elsewhere in the API (same shape as Get Domain / Set Contacts).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainResponsePayload'
        '400':
          description: Validation failed (missing or invalid fields, invalid authorization code, or other bad input). The `message` and `details` fields describe what to correct.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
              examples:
                missingAuthCode:
                  summary: Missing auth code
                  value:
                    message: Bad Request
                    details: '''authCode'' is required'
                invalidAuthCode:
                  summary: Invalid authorization code
                  value:
                    message: Bad Request
                    details: The authorization code is invalid or has expired.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden — for example, when the authenticated account is not allowlisted for internal transfers (enterprise-only; initial rollout is limited to designated partners), or when the caller otherwise lacks permission to use this operation.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: The domain could not be found for an internal transfer from another name.com account, or it is not eligible to be pulled into the gaining account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
              examples:
                domainNotFound:
                  summary: Domain not found for internal transfer
                  value:
                    message: Not Found
                    details: No eligible domain was found in another name.com account for this request.
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '409':
          description: The domain is in a state that blocks the operation — for example, **registrar transfer lock** is still active (`clientTransferProhibited` or equivalent). The losing account must remove transfer lock in the name.com dashboard before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericConflict409'
              examples:
                transferLockActive:
                  summary: Registrar transfer lock still enabled
                  value:
                    message: Conflict
                    details: The domain is locked for transfer at the registrar. Unlock the domain in the losing account's name.com dashboard, then retry.
        '415':
          description: 'POST requests must include `Content-Type: application/json`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Create Internal Transfer In
      tags:
        - Transfers
  /core/v1/transfers/eligibility/{domainName}:
    get:
      description: |-
        Returns whether a domain is currently registered at [name.com](https://www.name.com) and whether the TLD supports internal transfer between name.com accounts. Use this to decide whether to send your user through the [Create Transfer](/api/v1/reference/transfers/create-transfer) external transfer flow or the [Create Internal Transfer In](/api/v1/reference/transfers/create-internal-transfer-in) flow before initiating a transfer-in.

        #### Response semantics

        `atName` is `true` if the domain is currently registered at name.com in any account. This information is also publicly available via RDAP.

        `supportsInternalTransfer` mirrors the TLD-level value returned by [Tld Requirements](/api/v1/reference/domain-info/get-specific-tld-requirements). It indicates whether the TLD is eligible for internal transfer between name.com accounts. It does not reflect per-account allowlist eligibility — if your account is not allowlisted for internal transfer in, calling [Create Internal Transfer In](/api/v1/reference/transfers/create-internal-transfer-in) will return `403 Forbidden`.

        #### Privacy

        This endpoint never reveals which account a domain is in. To check whether a domain is in your own account, use [Get Domain](/api/v1/reference/domains/get-domain) instead.
      operationId: GetTransferEligibility
      parameters:
        - description: The domain to check transfer eligibility for. Punycode is normalized server-side, so either ASCII or UTF-8 is accepted.
          in: path
          name: domainName
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferEligibilityResponse'
              examples:
                domainAtNamecomInternalTransferSupported:
                  summary: Domain is at name.com and TLD supports internal transfer
                  value:
                    domainName: example.com
                    atName: true
                    supportsInternalTransfer: true
                domainAtExternalRegistrar:
                  summary: Domain is at an external registrar
                  value:
                    domainName: example.com
                    atName: false
                    supportsInternalTransfer: true
        '400':
          description: Validation failed (invalid domain name, or domain SLD does not meet the TLD's length requirements).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
              examples:
                invalidDomainName:
                  summary: Invalid domain name
                  value:
                    message: Invalid Domain Name
                sldLengthViolation:
                  summary: SLD length requirements not met
                  value:
                    message: The domain doesn't appear to meet the length requirements for the specified tld.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '422':
          description: TLD not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity422'
              examples:
                tldNotSupported:
                  summary: TLD not supported
                  value:
                    message: Unsupported Tld
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Get Transfer Eligibility
      tags:
        - Transfers
  /core/v1/domaininfo/requirements/{tld}:
    get:
      description: Returns the registration requirements some general information for a specific TLD. The response contains a detailed description of eligibility criteria and a fields object with all required and optional fields, including validation rules, conditional logic, and nested field structures. Provide the TLD as a path parameter to retrieve its complete registration requirements. Useful when you only need details for one TLD (e.g., when a user selects .fr from a dropdown).
      operationId: GetRequirement
      parameters:
        - name: tld
          description: TLD indicates which domain requirements to retrieve (without the dot prefix, e.g., 'fr' for .fr domains). For punycode TLDs, use the ASCII version instead of the UTF-8. So for the `онлайн` TLD, you would submit `xn--80asehdb`.
          in: path
          required: true
          schema:
            type: string
            example: fr
            pattern: ^((?!xn--)[a-z0-9-]{1,63}|xn--[a-z0-9-]{1,63})((?:\.(?!-)[a-z0-9-]{1,63})|(?:\.xn--[a-z0-9-]{1,63}))*$
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRequirementResponse'
              examples:
                complex_requirement_set:
                  summary: Complex requirement set
                  description: Example of a complex requirement set with multiple fields, conditional logic, and nested requirements
                  value:
                    tldInfo:
                      tld: fr
                      ccTld: true
                      supportsTransferLock: true
                      supportsDnssec: true
                      supportsPremium: true
                      supportsPrivacy: true
                      supportsInternalTransfer: true
                      requiresPreDelegation: true
                      expirationGracePeriod: 3
                      idnLanguages: {}
                      allowedRegistrationYears:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
                        - 7
                        - 8
                        - 9
                        - 10
                      hsts: false
                      minDomainLength: 5
                      minIdnDomainLength: 5
                      registryOperator: registryfr
                      claimsCheckRequired: []
                      requireIdnSld: false
                    contacts:
                      description: The contacts required to be submitted for registration
                      type: string
                      required: true
                      label: contacts
                      fields:
                        registrant:
                          description: Registrant contact requirements
                          type: string
                          required: true
                          fields:
                            firstName:
                              description: First name of registrant contact
                              type: string
                              required: true
                            lastName:
                              description: Last name of registrant contact
                              type: string
                              required: true
                            address1:
                              description: First part of mailing address
                              type: string
                              required: true
                            address2:
                              description: Second part of mailing address
                              type: string
                              required: false
                            companyName:
                              description: Company name of registrant contact
                              type: string
                              required: false
                            phone:
                              description: Phone number of registrant contact
                              type: string
                              required: true
                            fax:
                              description: Fax number of registrant contact
                              type: string
                              required: false
                            email:
                              description: Email address of registrant contact
                              type: string
                              required: true
                              validation: valid_email
                            city:
                              description: City of registrant contact
                              type: string
                              required: true
                            state:
                              description: State/Province of registrant. Only values from this list are allowed
                              type: string
                              required: true
                            zip:
                              description: Postal code of registrant contact
                              type: string
                              required: true
                            country:
                              description: Country of registrant, only options in this list are allowed
                              type: enum
                              required: true
                              options:
                                - value: AT
                                  label: Austria
                                - value: AX
                                  label: Åland Islands
                                - value: BE
                                  label: Belgium
                                - value: BG
                                  label: Bulgaria
                                - value: CH
                                  label: Switzerland
                                - value: CY
                                  label: Cyprus
                                - value: CZ
                                  label: Czech Republic
                                - value: DE
                                  label: Germany
                                - value: DK
                                  label: Denmark
                                - value: EE
                                  label: Estonia
                                - value: ES
                                  label: Spain
                                - value: FI
                                  label: Finland
                                - value: FR
                                  label: France
                                - value: GF
                                  label: Guiana
                                - value: GP
                                  label: Guadeloupe
                                - value: GR
                                  label: Greece
                                - value: HU
                                  label: Hungary
                                - value: IE
                                  label: Ireland
                                - value: IS
                                  label: Iceland
                                - value: IT
                                  label: Italy
                                - value: LI
                                  label: Liechtenstein
                                - value: LT
                                  label: Lithuania
                                - value: LU
                                  label: Luxembourg
                                - value: LV
                                  label: Latvia
                                - value: MQ
                                  label: Martinique
                                - value: MT
                                  label: Malta
                                - value: NC
                                  label: New Caledonia
                                - value: NL
                                  label: Netherlands
                                - value: 'NO'
                                  label: Norway
                                - value: PF
                                  label: Polynesia (French)
                                - value: PL
                                  label: Poland
                                - value: PM
                                  label: St. Pierre & Miquelon
                                - value: PT
                                  label: Portugal
                                - value: RE
                                  label: Reunion
                                - value: RO
                                  label: Romania
                                - value: SE
                                  label: Sweden
                                - value: SI
                                  label: Slovenia
                                - value: SK
                                  label: Slovakia
                                - value: TF
                                  label: French Southern and Antarctic Lands
                                - value: WF
                                  label: Wallis & Futuna Is.
                                - value: YT
                                  label: Mayotte
                        tech:
                          description: Technical contact requirements
                          type: string
                          required: true
                          fields:
                            firstName:
                              description: First name of tech contact
                              type: string
                              required: true
                            lastName:
                              description: Last name of tech contact
                              type: string
                              required: true
                            address1:
                              description: First part of mailing address
                              type: string
                              required: true
                            address2:
                              description: Second part of mailing address
                              type: string
                              required: false
                            companyName:
                              description: Required company name of tech contact
                              type: string
                              required: true
                            phone:
                              description: Phone number of tech contact
                              type: string
                              required: true
                            fax:
                              description: Fax number of tech contact
                              type: string
                              required: false
                            email:
                              description: Email address of tech contact
                              type: string
                              required: true
                              validation: valid_email
                            city:
                              description: City of tech contact
                              type: string
                              required: true
                            state:
                              description: State/Province of tech contact. Only values from this list are allowed
                              type: string
                              required: true
                            zip:
                              description: Postal code of tech contact
                              type: string
                              required: true
                            country:
                              description: Country of tech contact
                              type: enum
                              required: true
                    requirements:
                      description: Registration requirements for .fr domains
                      fields:
                        firstName:
                          description: First name of registrant
                          type: string
                          required: true
                        lastName:
                          description: Last name of registrant
                          type: string
                          required: true
                        address1:
                          description: First part of mailing address
                          type: string
                          required: true
                        address2:
                          description: Second part of mailing address
                          type: string
                          required: false
                        companyName:
                          description: Company name of registrant
                          type: string
                          required: false
                        phone:
                          description: Phone number of registrant
                          type: string
                          required: true
                        fax:
                          description: Fax number of registrant
                          type: string
                          required: false
                        email:
                          description: Email address of registrant
                          type: string
                          required: true
                          validation: valid_email
                        city:
                          description: City of registrant
                          type: string
                          required: true
                        state:
                          description: State/Province of registrant
                          type: string
                          required: true
                        zip:
                          description: Postal code of registrant
                          type: string
                          required: true
                        country:
                          description: Country of registrant, only options in this list are allowed
                          type: enum
                          required: true
                          options:
                            - value: AT
                              label: Austria
                            - value: AX
                              label: Åland Islands
                            - value: BE
                              label: Belgium
                            - value: BG
                              label: Bulgaria
                            - value: CH
                              label: Switzerland
                            - value: CY
                              label: Cyprus
                            - value: CZ
                              label: Czech Republic
                            - value: DE
                              label: Germany
                            - value: DK
                              label: Denmark
                            - value: EE
                              label: Estonia
                            - value: ES
                              label: Spain
                            - value: FI
                              label: Finland
                            - value: FR
                              label: France
                            - value: GF
                              label: Guiana
                            - value: GP
                              label: Guadeloupe
                            - value: GR
                              label: Greece
                            - value: HU
                              label: Hungary
                            - value: IE
                              label: Ireland
                            - value: IS
                              label: Iceland
                            - value: IT
                              label: Italy
                            - value: LI
                              label: Liechtenstein
                            - value: LT
                              label: Lithuania
                            - value: LU
                              label: Luxembourg
                            - value: LV
                              label: Latvia
                            - value: MQ
                              label: Martinique
                            - value: MT
                              label: Malta
                            - value: NC
                              label: New Caledonia
                            - value: NL
                              label: Netherlands
                            - value: 'NO'
                              label: Norway
                            - value: PF
                              label: Polynesia (French)
                            - value: PL
                              label: Poland
                            - value: PM
                              label: St. Pierre & Miquelon
                            - value: PT
                              label: Portugal
                            - value: RE
                              label: Reunion
                            - value: RO
                              label: Romania
                            - value: SE
                              label: Sweden
                            - value: SI
                              label: Slovenia
                            - value: SK
                              label: Slovakia
                            - value: TF
                              label: French Southern and Antarctic Lands
                            - value: WF
                              label: Wallis & Futuna Is.
                            - value: YT
                              label: Mayotte
                        business:
                          description: ''
                          type: enum
                          required: true
                          label: business
                          options:
                            - value: 'no'
                              label: I am an individual
                              fields:
                                X-FR-BIRTHDATE:
                                  description: ''
                                  type: string
                                  required: false
                                  label: Date of Birth (YYYY-MM-DD)
                                X-FR-BIRTHPLACE:
                                  description: ''
                                  type: string
                                  required: true
                                  label: Birth Country (2 Letter Code)
                                  fields:
                                    X-FR-BIRTHCITY:
                                      description: ''
                                      type: string
                                      required: false
                                      label: Birth City
                                      required_when: FR
                                    X-FR-BIRTHPC:
                                      description: ''
                                      type: string
                                      required: false
                                      label: Birth Postal Code
                                      required_when: FR
                            - value: 'yes'
                              label: I am an organization
                              fields:
                                X-FR-LOCAL:
                                  description: 'Local company registration #, or tax ID'
                                  type: string
                                  required: false
                                  label: 'Local company registration #, or tax ID'
                simple_acknowledgement_requirement:
                  summary: Simple acknowledgement requirement
                  description: Example of a simple requirement with just an acknowledgement field
                  value:
                    tldInfo:
                      tld: security
                      ccTld: false
                      supportsTransferLock: true
                      supportsDnssec: true
                      supportsPremium: true
                      supportsPrivacy: true
                      supportsInternalTransfer: true
                      requiresPreDelegation: true
                      expirationGracePeriod: 25
                      hsts: false
                      minDomainLength: 3
                      minIdnDomainLength: 4
                      idnLanguages:
                        AR: Arabic
                        GREK: Greek
                        HE: Hebrew
                        JA: Japanese
                        KO: Korean
                        LATN: Latin
                        LO: Lao
                        RU: Russian
                        TH: Thai
                        ZH: Chinese
                      allowedRegistrationYears:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
                        - 7
                        - 8
                        - 9
                        - 10
                      registryOperator: centralnic
                      claimsCheckRequired: []
                      requireIdnSld: false
                    contacts:
                      description: The contacts required to be submitted for registration
                      type: string
                      required: true
                      label: contacts
                      fields: {}
                    requirements:
                      description: Registration requirements for .security domains
                      fields:
                        acknowledgement:
                          description: .SECURITY domains will not resolve unless they have both DNSSEC and an SSL on the domain.
                          type: acknowledgement
                          required: false
                          label: I understand
                          value: accepted
                simple_notification_requirement:
                  summary: Simple notification requirement
                  description: Example of a simple requirement with just a notice field
                  value:
                    tldInfo:
                      tld: at
                      ccTld: true
                      supportsTransferLock: false
                      supportsDnssec: true
                      supportsPremium: false
                      supportsPrivacy: false
                      supportsInternalTransfer: false
                      requiresPreDelegation: false
                      expirationGracePeriod: 3
                      hsts: true
                      minDomainLength: 3
                      minIdnDomainLength: null
                      idnLanguages: {}
                      allowedRegistrationYears:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
                        - 7
                        - 8
                        - 9
                        - 10
                      registryOperator: nicat
                      claimsCheckRequired: []
                      requireIdnSld: false
                    contacts:
                      description: The contacts required to be submitted for registration
                      type: string
                      required: true
                      label: contacts
                      fields: {}
                    requirements:
                      description: Registration requirements for .at domains
                      fields:
                        description:
                          description: The .AT registry has special rules regarding the expiration and deletion of .AT domains. Customers who may choose not to renew .AT domains at their expiration should take note of these requirements. If you do not intend to renew your .AT domain when it comes up for renewal, you will need to complete the official NIC.AT cancellation form at least 28 days before it's expiration date and return it directly to the .AT registry. If an official cancellation form is not received by the .AT registry 28 days prior to the domain's expiration date, name.com will be required to withdraw the registration, which will result in NIC.AT billing you directly for the subsequent registration period at the NIC.AT standard rate.
                          type: notice
                          required: false
                          label: ''
          description: The complete registration requirements for the specified TLD.
        '400':
          description: Bad request - Invalid TLD format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Tld not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '422':
          description: TLD not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity422'
              examples:
                tldNotSupported:
                  summary: TLD not supported
                  value:
                    message: Unsupported TLD
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: Get Specific TLD Requirements
      tags:
        - Domain Info
  /core/v1/domaininfo/claims/{domain}:
    post:
      summary: Check Domain Claims
      description: Performs the actual claims check for a specific domain. This endpoint checks if a specific domain has trademark claims against it, returning detailed information about any matching trademarks and their holders. Use this to verify if a domain can be registered without trademark conflicts. Please see the [claims flow](/guides/claims-flow) for information on how to use this endpoint in your domain purchase flow.
      operationId: CheckDomainClaims
      parameters:
        - name: domain
          description: The domain name to check for trademark claims (e.g., 'tiktok.page', 'example.com'). Include the full domain name including the TLD.
          in: path
          required: true
          schema:
            type: string
            example: tiktok.page
            pattern: ^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$
      requestBody:
        description: Optional parameters for the claims check. The type defaults to 'registration' if not specified.
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainClaimsCheckRequest'
      responses:
        '200':
          description: Domain claims check completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainClaimsCheckResponse'
              examples:
                claims_found:
                  summary: Domain with trademark claims
                  description: Example of a domain that has trademark claims against it
                  value:
                    domain: tiktok.page
                    claims: []
                    claimsProcessActive: true
                    claimId: 8c3027d30000000000382500785
                    notBefore: '2020-01-01T00:00:00Z'
                    notAfter: '2030-01-01T00:00:00Z'
                no_claims_found:
                  summary: Domain without trademark claims
                  description: Example of a domain that has no trademark claims against it
                  value:
                    domain: mycompany.page
                    claims: []
                    claimsProcessActive: false
                    claimId: null
                    notBefore: null
                    notAfter: null
        '400':
          description: Bad request - invalid domain format or parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: Domain not found or TLD not supported for claims checking.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      tags:
        - Domain Info
  /core/v1/tldpricing:
    get:
      description: |
        This endpoint returns an alphabetical list of all TLDs supported by name.com, including pricing for each supported order type. All prices are in US Dollars (USD) and apply to non-premium domains. name.com provides three pricing types for each TLD:
        - Account-Level Pricing - Your price, including any applicable rebates, promotions, or account-level discounts. This is referenced as 'registrationprice', 'renewalprice', 'transferinprice' and 'domainrestorationprice' in this endpoint.
        - Original Pricing (No Discounts Applied) - The suggested retail price (MSRP) before any discounts are applied.
        - Retail Pricing (Public Site Pricing) - The current public retail price on name.com, including any public rebates or promotions, but before any account-level discounts.

        **Important Notes:**
        - Promo codes are not supported through the API, and therefore are not reflected in any pricing values returned.
        - General TLD pricing only: This represents standard pricing for domains registered under the specified TLD. Pricing for specific domains may differ based on multiple factors (e.g., premium classifications, registry pricing rules). To retrieve pricing for an individual domain, use the GetPricingForDomain endpoint.
        - Availability: If a pricing value is returned as null, that product type is not currently supported for the TLD. (Example: registrationPrice = null means registrations are not currently available.)
        - If you do not have account level pricing, the retail price will always match your account level price. (e.g., registration price = registration retail price)
      operationId: TldPriceList
      parameters:
        - description: Per Page is the number of records to return per request. Per Page defaults to 25.
          in: query
          name: perPage
          schema:
            allOf:
              - $ref: '#/components/schemas/PerPageLimit'
              - default: 25
        - description: Page is which page to return.
          in: query
          name: page
          schema:
            format: int32
            type: integer
            default: 1
            minimum: 1
        - name: duration
          description: The number of years to get pricing for. The requested duration must be between 1 and 10 (inclusive). If the duration is not passed in the request, it will default to 1.
          required: false
          in: query
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 10
            example: 1
            default: 5
        - name: tlds
          description: A list of specific TLDs to get pricing for. Maximum of 25 TLDs can be requested at a time.  When querying for IDN TLDs, due to character restrictions within a URL, they must be submitted in ASCII format.  This means using "xn--9dbq2a" as opposed to it's unicode equivalent. The submitted TLDs will be checked for validity and support at name.com, and any invalid TLD will be removed from the submitted list. If all submitted TLDs are invalid or not supported by name.com, this will be considered a bad request, and a `400 Bad Request` will be returned with an appropriate message.
          in: query
          required: false
          schema:
            type: array
            minItems: 1
            maxItems: 25
            items:
              type: string
              minLength: 1
            example:
              - com
              - net
              - org
          style: form
          explode: true
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TldPriceListResponse'
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
      summary: TLD Price List
      tags:
        - TLD Pricing
  /core/v1/zonecheck:
    post:
      description: |-
        Zone Check offers a rapid, preliminary check for domain availability by leveraging cached zone file data.  Ideal for large-batch queries, it provides a high confidence indication of a domain's availability significantly faster than live registry checks.  For definitive, real-time availability and pricing, you can follow up with the standard [Check Availability](/api/v1/reference/domains/check-availability) call.
        The API normalizes and validates each submitted domain string. Domains that fail validation, use an unsupported TLD for this service, or  are otherwise not eligible for zone check are **removed** from the request before the zone file lookup runs. The response includes **only**  a numeric count of removed domains (`removed`); individual removed strings are not returned. A future API version may extend the contract to  include details about removed domains.

        For the best results and to avoid `400 Bad Request` errors after cleaning, ensure each domain string meets the criteria described for  `domainNames` in the request body schema.

        If no valid domains remain after this process, the API returns a `400 Bad Request` response.
        **Note:** The cached zone files used for this check are refreshed twice daily based on the latest available data from the registries.
      operationId: ZoneCheck
      summary: Zone Check
      tags:
        - Domains
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ZoneCheckRequest'
        description: Request body to check for availability
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoneCheckResponse'
          description: Successful response for a DNS zone check.
        '400':
          description: Bad request - Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '422':
          description: Returned when, after cleaning, there were no valid domains passed in the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity422'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: There was a temporary error in processing the request. The request can be retried immediately.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGateway502'
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
  /core/v1/premiumdomainslist:
    get:
      description: |-
        Gets a pre-signed URL that will allow a user to download a list of premium domains, with their registration and renewal pricing.
        **Please Note:** The pre-signed URL will only be valid for 10 minutes. This endpoint is only available to approved reseller accounts. Contact name.com support to request access.
      operationId: PremiumDomainLists
      summary: Download Premium Domain Lists
      tags:
        - Premium Domains
      responses:
        '200':
          description: A successful response containing the pre-signed URL to download the file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PremiumDomainsDownloadResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: No premium list is currently available for download.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
              examples:
                noPremiumList:
                  summary: No premium list available
                  value:
                    message: No premium list is currently available for download.
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
  /core/v1/contacts/unverified:
    get:
      description: |-
        Returns a list of contacts, related to domains within your account, that require verification as per ICANN procedures.
        When a new domain is created, unverified contacts are not immediately available in API responses.  Records are added by a scheduled process that runs approximately every 10 minutes.  As a result, there may be up to a 10-minute delay before unverified contacts appear in the API. This delay also applies to related events such as webhooks or other downstream systems that depend on contact verification data. 
      operationId: UnverifiedContactsList
      summary: List Unverified Contacts
      tags:
        - Contact Verification
      parameters:
        - description: PerPage is the number of records to return per request. If not passed in the request, the default value is 100 records.
          in: query
          name: perPage
          schema:
            allOf:
              - $ref: '#/components/schemas/PerPageLimit'
              - default: 100
                example: 100
        - description: Page is which page to return. If not passed in the request, the default page is 1.
          in: query
          name: page
          schema:
            format: int32
            type: integer
            example: 2
            default: 1
            minimum: 1
      responses:
        '200':
          description: A successful response containing an array of unverified contacts.  This array may be empty if there are no unverified contacts related to domains in your account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnverifiedContactsResponse'
        '400':
          description: Bad request - Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
  /core/v1/contacts/verify/{verificationId}:
    post:
      description: |-
        Use this API to verify a contact.
        This API is only available to approved reseller accounts. Contact name.com support to request access.
      summary: Verify Contact
      operationId: VerifyContact
      tags:
        - Contact Verification
      parameters:
        - description: The VerificationId required to verify a specific contact.
          in: path
          name: verificationId
          schema:
            format: int32
            type: integer
          required: true
          example: 98752463
        - name: X-Idempotency-Key
          in: header
          description: A unique string (e.g., a UUID v4) to make the request idempotent. This key ensures that if the request is retried, the operation will not be performed multiple times. Subsequent requests with the same key will return the original result.
          schema:
            type: string
            example: 083910ef-04e4-4bd1-a0bf-3737fe005ca8
          required: false
      requestBody:
        required: true
        description: 'No fields are accepted. Send an empty JSON object `{}` with `Content-Type: application/json`.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyObject'
            example: {}
      responses:
        '204':
          description: Contact has been successfully verified.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: The submitted verificationId was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '409':
          description: When sending idempotent requests, this response indicates that there was an issue with the idempotency keys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Idempotency key has been reused for a different request.
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
  /core/v1/contacts/verify/{verificationId}:resend:
    post:
      description: |-
        Resend the contact verification email for a pending verification record.

        ### Throttling
        This endpoint enforces strict throttling to prevent abuse:
        - Per `verificationId`: max 1 resend per 15 minutes
        - Per reseller account: max 200 resends per rolling hour

        `nextEligibleAt` is always returned so the client knows when it can try again.

        On `429`, the response uses the standard error envelope, and `details` contains the earliest retry time (RFC3339 UTC).
      summary: Resend Contact Verification Email
      operationId: ResendContactVerificationEmail
      tags:
        - Contact Verification
      parameters:
        - description: The verificationId for the pending contact verification record.
          in: path
          name: verificationId
          schema:
            format: int32
            type: integer
          required: true
          example: 98752463
        - name: X-Idempotency-Key
          in: header
          description: A unique string (e.g., a UUID v4) to make the request idempotent. This key ensures that if the request is retried, the operation will not be performed multiple times. Subsequent requests with the same key will return the original result.
          schema:
            type: string
            example: 083910ef-04e4-4bd1-a0bf-3737fe005ca8
          required: false
      requestBody:
        required: true
        description: 'No fields are accepted. Send an empty JSON object `{}` with `Content-Type: application/json`.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyObject'
            example: {}
      responses:
        '200':
          description: Request accepted. An email may have been sent, or the request may be a no-op (for example, if the contact is already verified or there is nothing to send). The `sent` field indicates whether an email was sent for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactVerificationResendResponse'
              examples:
                sent:
                  summary: Email sent
                  value:
                    sent: true
                    verificationId: 98752463
                    nextEligibleAt: '2026-01-14T12:15:00Z'
                noop:
                  summary: No-op (already verified / nothing to send)
                  value:
                    sent: false
                    verificationId: 98752463
                    nextEligibleAt: '2026-01-14T12:00:00Z'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: The submitted verificationId was not found or is not associated with this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '409':
          description: When sending idempotent requests, this response indicates that there was an issue with the idempotency keys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Idempotency key has been reused for a different request.
        '415':
          description: 'All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMedia415'
        '429':
          description: Throttled. The response uses the standard error envelope; `details` contains the earliest retry time (RFC3339 UTC).
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Resend throttled
                  details:
                    type: string
                    description: Earliest retry time (RFC3339 UTC).
                    example: 'Next eligible at: 2026-01-20T21:49:58+00:00'
              examples:
                throttled:
                  summary: Throttled
                  value:
                    message: Resend throttled
                    details: 'Next eligible at: 2026-01-20T21:49:58+00:00'
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
  /core/v1/domaininfo/requirementsV2/{tld}:
    get:
      summary: Get TLD Requirements as JSON Schema
      description: Returns the registration requirements as a JSON Schema (Draft 7) document. This endpoint is designed for form generation and validation libraries that consume JSON Schema directly.
      operationId: GetTldRequirementsV2
      tags:
        - Domain Info
      parameters:
        - name: tld
          description: TLD indicates which domain requirements to retrieve (without the dot prefix, e.g., 'fr' for .fr domains). For punycode TLDs, use the ASCII version instead of the UTF-8. So for the `онлайн` TLD, you would submit `xn--80asehdb`.
          in: path
          required: true
          schema:
            type: string
            example: fr
            pattern: ^((?!xn--)[a-z0-9-]{1,63}|xn--[a-z0-9-]{1,63})((?:\.(?!-)[a-z0-9-]{1,63})|(?:\.xn--[a-z0-9-]{1,63}))*$
      responses:
        '200':
          description: JSON Schema document describing TLD registration requirements.
          content:
            application/schema+json:
              schema:
                $ref: '#/components/schemas/RequirementsJsonSchema'
              examples:
                it_tld_schema:
                  summary: Example for .it TLD
                  value:
                    $schema: http://json-schema.org/draft-07/schema#
                    type: object
                    title: .it Domain Registration Requirements Schema
                    description: Registration requirements for .it domains
                    properties:
                      tldInfo:
                        tld: .it
                        ccTld: true
                        supportsTransferLock: true
                        supportsDnssec: true
                        supportsPremium: false
                        supportsPrivacy: false
                        supportsInternalTransfer: true
                        requiresPreDelegation: false
                        expirationGracePeriod: 25
                        allowedRegistrationYears:
                          - 1
                          - 3
                          - 5
                          - 8
                          - 10
                        idnLanguages:
                          IT: Italian
                        hsts: false
                        minDomainLength: 3
                        minIdnDomainLength: 5
                        registryOperator: nic.it
                        claimsCheckRequired: []
                        requireIdnSld: false
                        readOnly: true
                      contacts:
                        type: object
                        properties:
                          registrant:
                            type: object
                            properties:
                              firstName:
                                type: string
                                title: First Name
                                description: First name of registrant contact
                              email:
                                type: string
                                format: email
                                title: Email
                                description: Email address of registrant contact
                            required:
                              - firstName
                              - email
                        required:
                          - registrant
                      tldRequirements:
                        type: object
                        properties:
                          X-IT-ENTITY-TYPE:
                            type: string
                            title: Registrant Entity Type
                            enum:
                              - '1'
                              - '2'
                              - '3'
                              - '4'
                              - '5'
                              - '6'
                              - '7'
                          X-IT-PIN:
                            type: string
                            title: .IT PIN number
                            description: 16 alphanumeric characters (tax code) for natural persons or 11 digits (VAT number) for organizations
                    required:
                      - tldInfo
                      - contacts
                      - tldRequirements
            application/json:
              schema:
                $ref: '#/components/schemas/RequirementsJsonSchema'
              examples:
                it_tld_schema:
                  summary: Example for .it TLD
                  value:
                    $schema: http://json-schema.org/draft-07/schema#
                    type: object
                    title: .it Domain Registration Requirements Schema
                    description: Registration requirements for .it domains
                    properties:
                      tldInfo:
                        tld: .it
                        ccTld: true
                        supportsTransferLock: true
                        supportsDnssec: true
                        supportsPremium: false
                        supportsPrivacy: false
                        supportsInternalTransfer: true
                        requiresPreDelegation: false
                        expirationGracePeriod: 25
                        allowedRegistrationYears:
                          - 1
                          - 3
                          - 5
                          - 8
                          - 10
                        idnLanguages:
                          IT: Italian
                        hsts: false
                        minDomainLength: 3
                        minIdnDomainLength: 5
                        registryOperator: nic.it
                        claimsCheckRequired: []
                        requireIdnSld: false
                        readOnly: true
                      contacts:
                        type: object
                        properties:
                          registrant:
                            type: object
                            properties:
                              firstName:
                                type: string
                                title: First Name
                                description: First name of registrant contact
                              email:
                                type: string
                                format: email
                                title: Email
                                description: Email address of registrant contact
                            required:
                              - firstName
                              - email
                        required:
                          - registrant
                      tldRequirements:
                        type: object
                        properties:
                          X-IT-ENTITY-TYPE:
                            type: string
                            title: Registrant Entity Type
                            enum:
                              - '1'
                              - '2'
                              - '3'
                              - '4'
                              - '5'
                              - '6'
                              - '7'
                          X-IT-PIN:
                            type: string
                            title: .IT PIN number
                            description: 16 alphanumeric characters (tax code) for natural persons or 11 digits (VAT number) for organizations
                    required:
                      - tldInfo
                      - contacts
                      - tldRequirements
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Unauthorized
        '403':
          description: Forbidden - you do not have permission to perform this action.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Permission denied
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error
                    example: Failed authentication
        '404':
          description: TLD not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error
                    example: Method Not Allowed
        '422':
          description: TLD not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity422'
              examples:
                tldNotSupported:
                  summary: Registration price unavailable
                  value:
                    message: Unsupported TLD
        '429':
          description: Rate limit has been exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - details
                properties:
                  message:
                    type: string
                    description: |-
                      ### Too Many Requests
                      You have exceeded the rate limit.

                      **Headers returned:**
                      * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry.
                    example: Rate Limit Exceeded
          headers:
            x-ratelimit-reset:
              description: Unix timestamp for the time at which the current rate limit will reset.
              schema:
                type: number
                example: 1747668270
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Internal Server Error
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: Something went wrong.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The server received an invalid response from the upstream server.
        '503':
          description: Service Unavailable — returned during scheduled maintenance when the API is offline. See https://status.name.com for updates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: Service Unavailable
                  details:
                    type:
                      - string
                      - 'null'
                    description: Additional context or information about the error.
                    example: The API is offline for scheduled maintenance. See https://status.name.com for updates.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: A human-readable message providing more details about the error.
                    example: The upstream server is taking too long to respond.
webhooks:
  accountCreditBalanceChange:
    post:
      tags:
        - Webhook Notifications
      operationId: AccountCreditBalanceChangeWebhook
      summary: Account Credit Balance Change
      description: This is the payload that will be sent to the subscribed URL, when a changed to the amount of account credit for an account changes. This will trigger on both increases and decreases in account credit for the account.
      parameters:
        - name: X-NAMECOM-SIGNATURE
          in: header
          description: HMAC signature for the request payload. See HMAC signing documentation for example code and detailed explanation of signing.
          required: true
          schema:
            type: string
            example: djasfgafgflgsdfgdsfkhfhjas,12334782,1123-3423-4dss4-354
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreditBalanceChange'
      responses:
        '200':
          description: The subscribed server accepted the request.
        4XX:
          description: The subscribed server returned an error (bad request, Unauthenticated etc).
        5XX:
          description: The subscribed server experienced an error while processing the request.
  accountDomainRemoval:
    post:
      tags:
        - Webhook Notifications
      operationId: AccountDomainRemovalWebhook
      summary: Account Domain Removal
      description: Sent when a domain leaves the subscribing account's inventory. Fires once per inventory-loss.
      parameters:
        - name: X-NAMECOM-SIGNATURE
          in: header
          description: HMAC signature for the request payload. See HMAC signing documentation for example code and detailed explanation of signing.
          required: true
          schema:
            type: string
            example: djasfgafgflgsdfgdsfkhfhjas,12334782,1123-3423-4dss4-354
      requestBody:
        description: The request sent to your server when a domain is removed from the account.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountDomainRemoval'
            examples:
              expiration:
                summary: Removed after expiration lifecycle
                value:
                  eventName: account.domain.removal
                  domainName: example.com
                  reason: expiration
                  expireDate: '2026-08-15T00:00:00Z'
              agp_refund:
                summary: Removed via AGP refund
                value:
                  eventName: account.domain.removal
                  domainName: example.com
                  reason: agp_refund
                  expireDate: '2027-07-01T00:00:00Z'
              administrative:
                summary: Removed administratively
                value:
                  eventName: account.domain.removal
                  domainName: example.com
                  reason: administrative
                  expireDate: '2026-08-15T00:00:00Z'
      responses:
        '200':
          description: The subscribed server accepted the request.
        4XX:
          description: The subscribed server returned an error (bad request, unauthenticated, etc).
        5XX:
          description: The subscribed server experienced an error while processing the request.
  domainLockStatusChange:
    post:
      tags:
        - Webhook Notifications
      operationId: DomainLockStatusChangeWebhook
      summary: Domain Lock Status Change
      description: Sent when a domain lock is added or removed, which may restrict or lift normal operations. This event is triggered automatically whenever covered lock types (e.g., compliance or verification holds) are added or removed. A webhook payload is delivered to the subscribed endpoint, providing details about the domain and its updated status.
      parameters:
        - name: X-NAMECOM-SIGNATURE
          in: header
          description: HMAC signature for the request payload. See HMAC signing documentation for example code and detailed explanation of signing.
          required: true
          schema:
            type: string
            example: djasfgafgflgsdfgdsfkhfhjas,12334782,1123-3423-4dss4-354
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainLockStatusChange'
            examples:
              example:
                value:
                  eventName: domain.lock.status_change
                  domainName: example.org
                  action: added
                  lockType: ClientHold
                  registryStatuses:
                    - clientHold
                    - clientTransferProhibited
                    - clientUpdateProhibited
      responses:
        '200':
          description: The subscribed server accepted the request.
        4XX:
          description: The subscribed server returned an error (bad request, Unauthenticated etc).
        5XX:
          description: The subscribed server experienced an error while processing the request.
  domainTransferStatusChange:
    post:
      tags:
        - Webhook Notifications
      operationId: DomainTransferStatusChangeWebhook
      summary: Domain Transfer In Status Change
      description: |-
        Sent when you have subscribed to the event on your account, and a domain transfer IN to name.com is processing.
        This webhook reports status changes for transfers where name.com is the gaining registrar (i.e., transfers into your name.com account).
        When `status` is `completed` and submitted contacts could not be applied, optional `warning` is included.
      parameters:
        - name: X-NAMECOM-SIGNATURE
          in: header
          description: HMAC signature for the request payload. See HMAC signing documentation for example code and detailed explanation of signing.
          required: true
          schema:
            type: string
            example: djasfgafgflgsdfgdsfkhfhjas,12334782,1123-3423-4dss4-354
      requestBody:
        description: The request sent to your server.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainTransferStatusChange'
            examples:
              completed:
                summary: Transfer completed
                value:
                  eventName: domain.transfer.status_change
                  domainName: example.com
                  status: completed
              completedContactFallback:
                summary: Transfer completed; submitted contacts not applied
                value:
                  eventName: domain.transfer.status_change
                  domainName: example.com
                  status: completed
                  warning: One or more submitted contacts could not be applied and were replaced with the account default contacts. Call Set Contacts to update them with the end-user contacts.
      responses:
        '200':
          description: The subscribed server accepted the request.
        4XX:
          description: The subscribed server returned an error (bad request, Unauthenticated etc).
        5XX:
          description: The subscribed server experienced an error while processing the request.
  domainTransferOutStatusChange:
    post:
      tags:
        - Webhook Notifications
      operationId: DomainTransferOutStatusChangeWebhook
      summary: Domain Transfer Out Status Change
      description: |-
        Sent when a domain transfer OUT from name.com has a status change: `initiated`, `completed`, or `canceled`.

        - **initiated** — pending outbound transfer started. Domain remains on the losing account.
        - **completed** — domain removed from name.com.
        - **canceled** — outbound transfer is no longer pending at the registry. Domain remains on the losing account.

        When status is `completed`, edge cases (including near-expiration) may briefly disagree with the registry.
      parameters:
        - name: X-NAMECOM-SIGNATURE
          in: header
          description: HMAC signature for the request payload. See HMAC signing documentation for example code and detailed explanation of signing.
          required: true
          schema:
            type: string
            example: djasfgafgflgsdfgdsfkhfhjas,12334782,1123-3423-4dss4-354
      requestBody:
        description: The request sent to your server when a domain transfer out status changes.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainTransferOutStatusChange'
            examples:
              initiated:
                summary: Transfer out initiated
                value:
                  eventName: domain.transfer_out.status_change
                  domainName: example.com
                  status: initiated
                  registryClientId: NAMECOM-123
              completed:
                summary: Transfer out completed
                value:
                  eventName: domain.transfer_out.status_change
                  domainName: example.com
                  status: completed
                  registryClientId: NAMECOM-123
              canceled:
                summary: Transfer out canceled (no longer pending at registry)
                value:
                  eventName: domain.transfer_out.status_change
                  domainName: example.com
                  status: canceled
                  registryClientId: NAMECOM-123
      responses:
        '200':
          description: The subscribed server accepted the request.
        4XX:
          description: The subscribed server returned an error (bad request, unauthenticated, etc).
        5XX:
          description: The subscribed server experienced an error while processing the request.
  contactVerificationStatusChange:
    post:
      tags:
        - Webhook Notifications
      operationId: ContactVerificationStatusChangeWebhook
      summary: Contact Verification Status Change
      description: This is the payload that will be sent to the subscribed URL, when a change to contact verification status occurs. This will trigger on both verified and unverified contact status change events.
      parameters:
        - name: X-NAMECOM-SIGNATURE
          in: header
          description: HMAC signature for the request payload. See HMAC signing documentation for example code and detailed explanation of signing.
          required: true
          schema:
            type: string
            example: djasfgafgflgsdfgdsfkhfhjas,12334782,1123-3423-4dss4-354
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactVerificationStatusChange'
      responses:
        '200':
          description: The subscribed server accepted the request.
        4XX:
          description: The subscribed server returned an error (bad request, Unauthenticated etc).
        5XX:
          description: The subscribed server experienced an error while processing the request.
  domainTransferInternalInStatusChange:
    post:
      tags:
        - Webhook Notifications
      operationId: DomainTransferInternalInStatusChangeWebhook
      summary: Internal Transfer In Status Change
      description: Sent when you have subscribed to the event on your account, and a name.com domain transfers into your account.
      parameters:
        - name: X-NAMECOM-SIGNATURE
          in: header
          description: HMAC signature for the request payload. See HMAC signing documentation for example code and detailed explanation of signing.
          required: true
          schema:
            type: string
            example: djasfgafgflgsdfgdsfkhfhjas,12334782,1123-3423-4dss4-354
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainTransferInternalInStatusChange'
      responses:
        '200':
          description: The subscribed server accepted the request.
        4XX:
          description: The subscribed server returned an error (bad request, unauthenticated etc).
        5XX:
          description: The subscribed server experienced an error while processing the request.
  domainTransferInternalOutStatusChange:
    post:
      tags:
        - Webhook Notifications
      operationId: DomainTransferInternalOutStatusChangeWebhook
      summary: Internal Transfer Out Status Change
      description: Sent when you have subscribed to the event on your account, and a name.com domain transfers out of your account.
      parameters:
        - name: X-NAMECOM-SIGNATURE
          in: header
          description: HMAC signature for the request payload. See HMAC signing documentation for example code and detailed explanation of signing.
          required: true
          schema:
            type: string
            example: djasfgafgflgsdfgdsfkhfhjas,12334782,1123-3423-4dss4-354
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainTransferInternalOutStatusChange'
      responses:
        '200':
          description: The subscribed server accepted the request.
        4XX:
          description: The subscribed server returned an error (bad request, unauthenticated etc).
        5XX:
          description: The subscribed server experienced an error while processing the request.
  domainRegistryRejection:
    post:
      tags:
        - Webhook Notifications
      operationId: DomainRegistryRejectionWebhook
      summary: Domain Registry Rejection
      description: Sent when you have subscribed to this event on your account, and a domain **create** request fails after asynchronous registry processing. Most registrations complete successfully at create time; this webhook covers the uncommon case where processing completes later with a failure.
      parameters:
        - name: X-NAMECOM-SIGNATURE
          in: header
          description: HMAC signature for the request payload. See HMAC signing documentation for example code and detailed explanation of signing.
          required: true
          schema:
            type: string
            example: djasfgafgflgsdfgdsfkhfhjas,12334782,1123-3423-4dss4-354
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainRegistryRejection'
      responses:
        '200':
          description: The subscribed server accepted the request.
        4XX:
          description: The subscribed server returned an error (bad request, unauthenticated etc).
        5XX:
          description: The subscribed server experienced an error while processing the request.
  domainRegistryComplianceNotice:
    post:
      tags:
        - Webhook Notifications
      operationId: DomainRegistryComplianceNoticeWebhook
      summary: Domain Registry Compliance Notice
      description: |-
        Sent when a registry reports that a domain in your account must remediate a policy compliance issue.
        By default, name.com emails this notice to the domain's registrant. Whitelabeled branding is applied to that email when your account has it configured. Subscribing replaces the email with this webhook so you can notify the end user; unsubscribing resumes the email.
        If you have signed an addendum to assume all email responsibility, name.com does not send this email. This webhook is the only delivery path. Without a subscription the registrant is not notified. Webhook delivery failure does not fall back to email.
      parameters:
        - name: X-NAMECOM-SIGNATURE
          in: header
          description: HMAC signature for the request payload. See HMAC signing documentation for verification details.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainRegistryComplianceNotice'
            examples:
              dotNew:
                summary: .new domain does not resolve to an action within 100 days
                value:
                  eventName: domain.registry.compliance_notice
                  domainName: example.new
                  policy: new_resolves_within_100_days
                  policyName: .NEW Domain Registration Policy
                  policyUrl: https://www.registry.google/policies/registration/new/#!/
                  registryName: Google Registry
                  registryEmail: registry-poc-primary@google.com
                  originalMessageId: <CA12345@mail.google.com>
                  issueDescription: The registry determined that the domain does not resolve to an action within 100 days of registration.
                  remediationInstructions: Configure the domain to launch an online creation or action-generation flow, and ensure the website is accessible using an active SSL certificate.
                  agreementReminder: As a reminder, when you registered this domain, you agreed to the .NEW Domain Registration Policy, which includes this requirement.
                  noncomplianceConsequences: If the website is still not compliant by the deadline, the registry may suspend or cancel the domain. Suspended domains do not resolve and cannot be transferred or deleted.
                  contactInstructions: If you believe the domain is compliant or need to submit evidence, contact Google Registry.
                  complianceDeadline: '2026-10-25T15:30:00+00:00'
                  remediationPeriodDays: 14
      responses:
        '200':
          description: The subscribed server accepted the request.
        4XX:
          description: The subscribed server returned an error.
        5XX:
          description: The subscribed server experienced an error.
  domainExpiration:
    post:
      tags:
        - Webhook Notifications
      operationId: DomainExpirationWebhook
      summary: Domain Expiration
      description: Sent when you have subscribed to this event on your account, and a domain has expired and entered the post-expiry grace period. This notification is informational only.
      parameters:
        - name: X-NAMECOM-SIGNATURE
          in: header
          description: HMAC signature for the request payload. See HMAC signing documentation for example code and detailed explanation of signing.
          required: true
          schema:
            type: string
            example: djasfgafgflgsdfgdsfkhfhjas,12334782,1123-3423-4dss4-354
      requestBody:
        description: The request sent to your server when a domain has expired and entered the post-expiry grace period.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainExpiration'
            examples:
              example:
                value:
                  eventName: domain.expiration
                  domainName: example.com
                  expirationDate: '2026-08-15T00:00:00Z'
      responses:
        '200':
          description: The subscribed server accepted the request.
        4XX:
          description: The subscribed server returned an error (bad request, unauthenticated, etc).
        5XX:
          description: The subscribed server experienced an error while processing the request.
components:
  securitySchemes:
    BasicAuth:
      scheme: basic
      type: http
      description: 'Authenticate via HTTP Basic with your account username and API token. Examples use an explicit ''Authorization: Basic <base64(username:token)>'' header; ''curl -u username:token'' is equivalent. For sandbox, append "-test" to your username and use your sandbox token on api.dev.name.com.'
  schemas:
    CheckAccountBalanceResponse:
      properties:
        balance:
          description: Balance is the current account balance in USD.
          format: double
          type: number
          example: 103.35
      title: CheckAccountBalanceResponse is the current account balance for the authenticated user
      type: object
      required:
        - balance
    Contact:
      description: Contact contains all relevant contact data for a domain registrant. This schema is used for API responses and may contain null values for legacy data. For creating or updating contacts, use ContactRequest which enforces all validation requirements.
      type: object
      properties:
        firstName:
          description: First name of the contact.
          type:
            - string
            - 'null'
          example: John
        lastName:
          description: Last name of the contact.
          type:
            - string
            - 'null'
          example: Doe
        companyName:
          description: Company name of the contact. Leave blank if the contact is an individual, as some registries may assume it is a corporate entity otherwise.
          type:
            - string
            - 'null'
          example: Example Inc.
        address1:
          description: The first line of the contact's address.
          type:
            - string
            - 'null'
          example: 123 Main Street
        address2:
          description: The second line of the contact's address (optional).
          type:
            - string
            - 'null'
          example: Suite 400
        city:
          description: City of the contact's address.
          type:
            - string
            - 'null'
          example: New York
        state:
          description: State or Province of the contact's address.
          type:
            - string
            - 'null'
          example: NY
        zip:
          description: ZIP or Postal Code of the contact's address.
          type:
            - string
            - 'null'
          example: '10001'
        country:
          description: Country code for the contact's address. Must be an ISO 3166-1 alpha-2 country code.
          type:
            - string
            - 'null'
          example: US
        email:
          description: Email address of the contact. Must be a valid email format. The validation is performed against the `addr-spec` syntax in [RFC 822](https://datatracker.ietf.org/doc/html/rfc822)
          type:
            - string
            - 'null'
          example: john.doe@example.com
        phone:
          description: 'Phone number of the contact. Should follow the E.164 international format: "+[country code][number]".'
          type:
            - string
            - 'null'
          example: '+15551234567'
        fax:
          description: 'Fax number of the contact. Should follow the E.164 international format: "+[country code][number]".'
          type:
            - string
            - 'null'
          example: '+15557654321'
        isVerified:
          description: Indicates if the contact has been verified as per ICANN requirements. If the value is `false` it indicates that the contact has not completed the required verification process. This property is read-only and will be included in responses but should not be included in requests.
          type: boolean
          example: true
          readOnly: true
        verificationId:
          description: When the contact is unverified, this is the ID of the pending verification record. Use this ID with the resend verification email and verify contact endpoints. Omitted or null when the contact is verified.
          type:
            - integer
            - 'null'
          format: int64
          example: 12345
          readOnly: true
    RegistrantContact:
      description: Contact contains all relevant contact data for a domain registrant. This schema is used for API responses and may contain null values for legacy data. For creating or updating contacts, use RegistrantContactRequest which enforces all validation requirements.
      type: object
      properties:
        firstName:
          description: First name of the contact.
          type:
            - string
            - 'null'
          example: John
        lastName:
          description: Last name of the contact.
          type:
            - string
            - 'null'
          example: Doe
        companyName:
          description: Company name of the contact. Leave blank if the contact is an individual. Please be advised that ICANN policy links the "Company Name" field (Organization) in your domain's contact details to its legal ownership. If this field contains information, the listed organization is considered the legal "Registered Name Holder" (domain owner).
          type:
            - string
            - 'null'
          example: Example Inc.
        address1:
          description: The first line of the contact's address.
          type:
            - string
            - 'null'
          example: 123 Main Street
        address2:
          description: The second line of the contact's address (optional).
          type:
            - string
            - 'null'
          example: Suite 400
        city:
          description: City of the contact's address.
          type:
            - string
            - 'null'
          example: New York
        state:
          description: State or Province of the contact's address.
          type:
            - string
            - 'null'
          example: NY
        zip:
          description: ZIP or Postal Code of the contact's address.
          type:
            - string
            - 'null'
          example: '10001'
        country:
          description: Country code for the contact's address. Must be an ISO 3166-1 alpha-2 country code.
          type:
            - string
            - 'null'
          example: US
        email:
          description: Email address of the contact. Must be a valid email format. The validation is performed against the `addr-spec` syntax in [RFC 822](https://datatracker.ietf.org/doc/html/rfc822)
          type:
            - string
            - 'null'
          example: john.doe@example.com
        phone:
          description: 'Phone number of the contact. Should follow the E.164 international format: "+[country code][number]".'
          type:
            - string
            - 'null'
          example: '+15551234567'
        fax:
          description: 'Fax number of the contact. Should follow the E.164 international format: "+[country code][number]".'
          type:
            - string
            - 'null'
          example: '+15557654321'
        isVerified:
          description: Indicates if the contact has been verified as per ICANN requirements. If the value is `false` it indicates that the contact has not completed the required verification process. This property is read-only and will be included in responses but should not be included in requests.
          type: boolean
          example: true
          readOnly: true
        verificationId:
          description: When the contact is unverified, this is the ID of the pending verification record. Use this ID with the resend verification email and verify contact endpoints. Omitted or null when the contact is verified.
          type:
            - integer
            - 'null'
          format: int64
          example: 12345
          readOnly: true
    Contacts:
      description: Contacts stores the contact information for the roles related to domains.
      properties:
        admin:
          $ref: '#/components/schemas/Contact'
        billing:
          $ref: '#/components/schemas/Contact'
        registrant:
          $ref: '#/components/schemas/RegistrantContact'
        tech:
          $ref: '#/components/schemas/Contact'
      type: object
    Account:
      description: Account lists all the data for an account.
      type: object
      properties:
        accountId:
          description: AccountId is the unique id of account.
          format: int32
          type: integer
          example: 12345
        accountName:
          description: AccountName is the unique name of the account.  Minimum length is 6 characters, maximum length is 60.
          type: string
          minLength: 6
          maxLength: 60
          example: namecom_reseller
        autoRenew:
          title: AutoRenew reflects account setting auto renew
          description: When set to true, domains in this account will be automatically renewed before expiration.
          type: boolean
          default: true
        contacts:
          $ref: '#/components/schemas/Contacts'
          description: Contact information associated with this account.
        createDate:
          description: CreateDate is the date the account was created.
          type: string
          format: date-time
          example: '2023-04-01T12:00:00Z'
        password:
          description: Password has minimum length of 7 characters. It must contain at least 1 letter and at least 1 number/symbol.
          type: string
          format: password
          minLength: 7
    ContactRequest:
      description: Contact contains all relevant contact data for a domain registrant.  This schema is used for creating and updating contacts (POST/PUT requests) and includes all validation requirements. All fields listed in the `required` array must be provided and cannot be null or empty.
      allOf:
        - $ref: '#/components/schemas/Contact'
        - type: object
          properties:
            firstName:
              description: First name of the contact.
              type: string
              example: John
              minLength: 1
            lastName:
              description: Last name of the contact.
              type: string
              example: Doe
              minLength: 1
            address1:
              description: The first line of the contact's address.
              type: string
              example: 123 Main Street
              minLength: 1
            city:
              description: City of the contact's address.
              type: string
              example: New York
              minLength: 1
            state:
              description: State or Province of the contact's address.
              type: string
              example: NY
              minLength: 1
            zip:
              description: ZIP or Postal Code of the contact's address. This field is required and must be a non-empty string.
              type: string
              example: '10001'
              minLength: 1
            country:
              description: Country code for the contact's address. Must be an ISO 3166-1 alpha-2 country code.
              type: string
              example: US
              pattern: ^[A-Z]{2}$
            email:
              description: Email address of the contact. Must be a valid email format. The validation is performed against the `addr-spec` syntax in [RFC 822](https://datatracker.ietf.org/doc/html/rfc822)
              type: string
              format: email
              example: john.doe@example.com
            phone:
              description: 'Phone number of the contact. Should follow the E.164 international format: "+[country code][number]".'
              type: string
              pattern: ^\+[1-9]\d{7,14}$
              example: '+15551234567'
            fax:
              description: 'Fax number of the contact. Should follow the E.164 international format: "+[country code][number]".'
              type:
                - string
                - 'null'
              pattern: ^\+[1-9]\d{7,14}$
              example: '+15557654321'
          required:
            - firstName
            - lastName
            - address1
            - city
            - state
            - zip
            - country
            - email
            - phone
    RegistrantContactRequest:
      description: Contact contains all relevant contact data for a domain registrant.  This schema is used for creating and updating contacts (POST/PUT requests) and includes all validation requirements. All fields listed in the `required` array must be provided and cannot be null or empty.
      allOf:
        - $ref: '#/components/schemas/RegistrantContact'
        - type: object
          properties:
            firstName:
              description: First name of the contact.
              type: string
              example: John
              minLength: 1
            lastName:
              description: Last name of the contact.
              type: string
              example: Doe
              minLength: 1
            address1:
              description: The first line of the contact's address.
              type: string
              example: 123 Main Street
              minLength: 1
            city:
              description: City of the contact's address.
              type: string
              example: New York
              minLength: 1
            state:
              description: State or Province of the contact's address.
              type: string
              example: NY
              minLength: 1
            zip:
              description: ZIP or Postal Code of the contact's address. This field is required and must be a non-empty string.
              type: string
              example: '10001'
              minLength: 1
            country:
              description: Country code for the contact's address. Must be an ISO 3166-1 alpha-2 country code.
              type: string
              example: US
              pattern: ^[A-Z]{2}$
            email:
              description: Email address of the contact. Must be a valid email format. The validation is performed against the `addr-spec` syntax in [RFC 822](https://datatracker.ietf.org/doc/html/rfc822)
              type: string
              format: email
              example: john.doe@example.com
            phone:
              description: 'Phone number of the contact. Should follow the E.164 international format: "+[country code][number]".'
              type: string
              pattern: ^\+[1-9]\d{7,14}$
              example: '+15551234567'
            fax:
              description: 'Fax number of the contact. Should follow the E.164 international format: "+[country code][number]".'
              type:
                - string
                - 'null'
              pattern: ^\+[1-9]\d{7,14}$
              example: '+15557654321'
          required:
            - firstName
            - lastName
            - address1
            - city
            - state
            - zip
            - country
            - email
            - phone
    ContactsRequest:
      description: Contacts stores the contact information for the roles related to domains. This schema is used for requests.
      properties:
        admin:
          $ref: '#/components/schemas/ContactRequest'
        billing:
          $ref: '#/components/schemas/ContactRequest'
        registrant:
          $ref: '#/components/schemas/RegistrantContactRequest'
        tech:
          $ref: '#/components/schemas/ContactRequest'
      type: object
    AccountRequest:
      description: Account lists all the data for an account. This schema is used for requests.
      allOf:
        - $ref: '#/components/schemas/Account'
        - type: object
          properties:
            contacts:
              $ref: '#/components/schemas/ContactsRequest'
              description: Contact information associated with this account.
    CreateAccountRequest:
      description: CreateAccountRequest has the information that is needed to create an account with the CreateAccount function.
      type: object
      required:
        - account
        - apiTos
        - tos
      properties:
        account:
          $ref: '#/components/schemas/AccountRequest'
          description: The account details for the new account being created.
        apiTos:
          title: ApiTos indicates accepted API Terms of Service agreement
          description: Must be set to true to indicate acceptance of the API Terms of Service.
          type: boolean
          example: true
        tos:
          title: Tos indicates accepted Terms of Service agreement
          description: Must be set to true to indicate acceptance of the general Terms of Service.
          type: boolean
          example: true
      example:
        account:
          accountName: reseller_subaccount
          password: SecureP4ss!
          contacts:
            registrant:
              firstName: Jane
              lastName: Doe
              address1: 123 Main St.
              city: Denver
              state: CO
              zip: '12345'
              country: US
              phone: '+13035551212'
              email: admin@example.net
        apiTos: true
        tos: true
    CreateAccountResponse:
      description: CreateAccountResponse contains information about the newly created account and the API credentials generated for it.
      type: object
      required:
        - accountName
        - apiToken
        - apiTokenName
      properties:
        accountName:
          description: AccountName is the unique user-assigned name of newly created account.
          type: string
          example: new_reseller_account
        apiToken:
          title: ApiToken secret hash to make api requests
          description: The authentication token that should be used to access the API. This value is only returned once upon account creation.
          type: string
          format: password
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        apiTokenName:
          description: ApiTokenName user assigned name of api token.
          type: string
          example: my_reseller_token
      example:
        accountName: new_reseller_account
        apiToken: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        apiTokenName: my_reseller_token
    InvalidArgument400:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: A human-readable message providing more details about the error
          example: Bad Request
        details:
          type:
            - string
            - 'null'
          description: Additional context or information about the error
          example: '''domainName'' cannot be null'
    UnsupportedMedia415:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: A human-readable message providing more details about the error
          example: The 'Content-Type' header must be 'application/json' for this request.
    PerPageLimit:
      description: Maximum number of records to return per page for paginated list endpoints.
      type: integer
      format: int32
      minimum: 1
      maximum: 1000
    Domain:
      description: Domain contains all relevant data for a domain.
      type: object
      properties:
        domainName:
          description: The punycode-encoded value of the domain name.
          type: string
          example: example.com
        createDate:
          description: The date and time when the domain was created at the registry.
          type: string
          format: date-time
          example: '2023-01-15T14:30:00Z'
          readOnly: true
        expireDate:
          description: The date and time when the domain will expire.
          type: string
          format: date-time
          example: '2025-01-15T14:30:00Z'
          readOnly: true
        autorenewEnabled:
          description: Indicates whether the domain is set to renew automatically before expiration.
          type: boolean
          example: true
        locked:
          description: Indicates if the domain is **transfer locked**, preventing transfers to another registrar.
          type: boolean
          example: true
        locks:
          description: List of all registry locking statuses currently applied to the domain. Use this to see which locks are active (e.g. clientTransferProhibited, clientHold). Empty when the domain has no locks applied.
          type: array
          items:
            type: string
          readOnly: true
          example:
            - clientTransferProhibited
            - clientHold
        transferLockExpiresAt:
          description: 'When present, the domain has an active ICANN-mandated transfer lock (new registration, transfer-in, or material registrant contact change) that blocks client unlock via the API until this time. When omitted, there is no active policy transfer lock with a known expiry — the domain may still be locked (`locked: true`) due to a voluntary user lock. Does not represent RegistrarLock, AccountLock, verification holds, trademark-claim locks, or admin TransferLock with no expiry date.'
          type: string
          format: date-time
          example: '2023-03-16T14:30:00Z'
          readOnly: true
        privacyEnabled:
          description: Indicates if Whois Privacy is enabled for this domain.
          type: boolean
          example: true
        contacts:
          $ref: '#/components/schemas/Contacts'
        nameservers:
          description: The list of nameservers assigned to this domain. If unspecified, it defaults to the account's default nameservers.
          type: array
          items:
            type: string
          example:
            - ns1.example.com
            - ns2.example.com
        renewalPrice:
          description: The cost to renew the domain. This may be required for the RenewDomain operation.
          type: number
          format: double
          example: 12.99
          readOnly: true
    domainName:
      description: The punycode-encoded value of the domain name.
      type: string
      example: example.com
    createDate:
      description: The date and time when the domain was created at the registry.
      type: string
      format: date-time
      example: '2023-01-15T14:30:00Z'
      readOnly: true
    expireDate:
      description: The date and time when the domain will expire.
      type: string
      format: date-time
      example: '2025-01-15T14:30:00Z'
      readOnly: true
    autorenewEnabled:
      description: Indicates whether the domain is set to renew automatically before expiration.
      type: boolean
      example: true
    locked:
      description: Indicates if the domain is **transfer locked**, preventing transfers to another registrar.
      type: boolean
      example: true
    transferLockExpiresAt:
      description: 'When present, the domain has an active ICANN-mandated transfer lock (new registration, transfer-in, or material registrant contact change) that blocks client unlock via the API until this time. When omitted, there is no active policy transfer lock with a known expiry — the domain may still be locked (`locked: true`) due to a voluntary user lock. Does not represent RegistrarLock, AccountLock, verification holds, trademark-claim locks, or admin TransferLock with no expiry date.'
      type: string
      format: date-time
      example: '2023-03-16T14:30:00Z'
      readOnly: true
    privacyEnabled:
      description: Indicates if Whois Privacy is enabled for this domain.
      type: boolean
      example: true
    nameservers:
      description: The list of nameservers assigned to this domain. If unspecified, it defaults to the account's default nameservers.
      type: array
      items:
        type: string
      example:
        - ns1.example.com
        - ns2.example.com
    renewalPrice:
      description: The cost to renew the domain. This may be required for the RenewDomain operation.
      type: number
      format: double
      example: 12.99
      readOnly: true
    DomainResponsePayload:
      description: The response format for a domain.
      allOf:
        - $ref: '#/components/schemas/Domain'
        - type: object
          properties:
            domainName:
              $ref: '#/components/schemas/domainName'
            createDate:
              $ref: '#/components/schemas/createDate'
            expireDate:
              $ref: '#/components/schemas/expireDate'
            autorenewEnabled:
              $ref: '#/components/schemas/autorenewEnabled'
            locked:
              $ref: '#/components/schemas/locked'
            transferLockExpiresAt:
              $ref: '#/components/schemas/transferLockExpiresAt'
            privacyEnabled:
              $ref: '#/components/schemas/privacyEnabled'
            contacts:
              $ref: '#/components/schemas/Contacts'
            nameservers:
              $ref: '#/components/schemas/nameservers'
            renewalPrice:
              $ref: '#/components/schemas/renewalPrice'
          required:
            - domainName
            - createDate
            - expireDate
            - autorenewEnabled
            - locked
            - privacyEnabled
            - contacts
            - nameservers
    ListDomainsResponse:
      description: ListDomainsResponse is the response from a list request, it contains the paginated list of Domains.
      properties:
        domains:
          description: Domains is the list of domains in your account.
          items:
            $ref: '#/components/schemas/DomainResponsePayload'
          type: array
        from:
          description: From is starting record count for current page.
          format: int32
          type: integer
        lastPage:
          description: LastPage is the identifier for the final page of results. It is only populated if there is another page of results after the current page.
          format: int32
          type: integer
        nextPage:
          description: NextPage is the identifier for the next page of results. It is only populated if there is another page of results after the current page.
          format: int32
          type: integer
        to:
          description: To is ending record count for current page.
          format: int32
          type: integer
        totalCount:
          description: TotalCount is total number of domains returned for request.
          format: int32
          type: integer
      type: object
      required:
        - to
        - from
        - totalCount
        - domains
    DomainCreatePayload:
      description: The payload to be sent for when making a request to purchase a domain.
      allOf:
        - $ref: '#/components/schemas/Domain'
        - type: object
          required:
            - domainName
          properties:
            domainName:
              type: string
            privacyEnabled:
              type: boolean
              description: Whether to include Whois Privacy with the registration. Whois Privacy is free. If omitted, the account default from account settings is used. Privacy is only added when the TLD supports it.
            contacts:
              $ref: '#/components/schemas/ContactsRequest'
    DomainClaimsInfo:
      description: Claims acknowledgement data is required if trademark claims exist for requested domain. This data is obtained from a [Domain Claims Check](/api/v1/reference/domain-info/check-domain-claims) response and includes the claim identifier and validity dates.
      type: object
      properties:
        claimId:
          type: string
          description: The claim identifier from TMCH (Trademark Clearinghouse)
          example: 8c3027d30000000000382500785
        notBefore:
          type: string
          format: date-time
          description: The date before which the claim acknowledgment is not valid
          example: '2024-01-15T10:30:00Z'
        notAfter:
          type: string
          format: date-time
          description: The date after which the claim acknowledgment expires
          example: '2024-01-15T10:30:00Z'
    CreateDomainRequest:
      description: |-
        CreateDomainRequest has the information that is needed to create a domain with the CreateDomain function.
        See the [Domain pricing guide](/guides/domain-pricing) for which endpoints supply create pricing (Search/Check Availability vs Get Pricing) for each `purchaseType`.
      properties:
        domain:
          $ref: '#/components/schemas/DomainCreatePayload'
        purchasePrice:
          description: PurchasePrice is the price in USD for purchasing this domain for the minimum time period (typically 1 year). PurchasePrice is required if purchaseType is not "registration" or if it is a premium domain. Whois Privacy is free and does not affect purchasePrice. If privacyEnabled is omitted, the account default from account settings is used. If VAT tax applies, it will also be added automatically.
          format: double
          type: number
        purchaseType:
          description: PurchaseType indicates what kind of purchase this domain create is for. Defaults to `registration` if omitted. **Recommended:** Use `registration` unless you support acquisition types (aftermarket, expiring, backorder) — see the [Domain purchase pricing guide](/guides/domain-pricing). This value should be copied from the [Search](/api/v1/reference/domains/search) or [Check Availability](/api/v1/reference/domains/check-availability) result. The value `registration` covers both standard and **registry premium** domains — use the `premium` flag from the discovery result to tell them apart. Aftermarket, expiring, and backorder types use flat acquisition fees from Search or Check Availability; see the [Domain pricing guide](/guides/domain-pricing).
          type: string
        tldRequirements:
          additionalProperties:
            type: string
          description: |-
            TLDRequirements is a way to pass additional data that is required by some registries. You can check before registration by using the [Domain Info](/api/v1/reference/domain-info/get-specific-tld-requirements) API.
            As these requirements vary wildly between registries and TLDs, we are not attempting to document them here.
            #### IDN Domains
            This parameter is required for registering domains that contain non-ASCII characters.  The value should be the specific code for the character set, such as `ES` for Spanish, or `CYRL` for Cyrillic. These abbreviations can vary between TLDs, and it is highly recommended that you use [Domain Info](/api/v1/reference/domain-info/get-specific-tld-requirements) API to ensure that the TLD allows for the specific IDN table, as well as the correct abbreviation.
          type: object
        claims:
          $ref: '#/components/schemas/DomainClaimsInfo'
        years:
          description: 'Years specifies the registration term in years. **Only affects price and registration length for `purchaseType: registration`.** Defaults to each TLD''s minimum if omitted (usually 1; 2 for `.ai`). Must be a supported registration term for the TLD when `purchaseType` is `registration` (commonly 1–10 years). For `purchaseType: registration` when `purchasePrice` is required, call [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) with the same `years` value. For aftermarket, expiring, and backorder types: pass the TLD default — it does **not** multiply `purchasePrice` and does **not** guarantee a multi-year registration. Check `domain.expireDate` in the create response for actual expiry. To add registration time after acquisition, use [Renew Domain](/api/v1/reference/domains/renew-domain).'
          format: int32
          type: integer
          example: 1
        promoCode:
          description: PromoCode is an optional promotional code to apply to the domain purchase. Only one promo code can be applied per request. Promo codes specify eligibility criteria, including duration. If the supplied promo applies no discount, the request fails with `400` and `"Promo code does not apply a discount to this purchase"`. The order is not created.
          type: string
          minLength: 1
      type: object
      required:
        - domain
    CreateDomainResponse:
      description: CreateDomainResponse contains the domain info as well as the order info for the created domain.
      properties:
        domain:
          $ref: '#/components/schemas/DomainResponsePayload'
        order:
          description: Order is an identifier for this purchase.
          format: int32
          type: integer
        totalPaid:
          description: TotalPaid is the total amount paid, including VAT when applicable. Whois Privacy is free and is not included in this amount.
          format: double
          type: number
      type: object
      required:
        - order
        - totalPaid
        - domain
    PaymentRequired402:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: A human-readable message providing more details about the error
          example: Payment failed
        details:
          type:
            - string
            - 'null'
          description: Additional context or information about the error
          example: Insufficient Funds
    NotFound404:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: A human-readable message providing more details about the error
          example: Not Found
        details:
          type:
            - string
            - 'null'
          description: Additional context or information about the error
          example: The requested domain does not exist.
    UnprocessableEntity422:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: A human-readable message providing more details about the error
          example: Unprocessable Entity
        details:
          type: string
          description: Additional context or information about the pricing error
          example: The pricing information required to process this request is temporarily unavailable. This is an internal system error. Please try again in a few minutes or contact support if the issue persists.
    UnavailableForLegal451:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: A human-readable message explaining why the resource is unavailable for legal reasons
          example: Unavailable for Legal Reasons
        details:
          type: string
          description: Additional context or information about the legal restriction
          example: This domain registration is restricted due to legal requirements in your jurisdiction.
    GenericError501:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: A human-readable message providing more details about the error
          example: Unimplemented
        details:
          type:
            - string
            - 'null'
          description: Additional context or information about the error
          example: Requested feature is not yet implemented
    GenericConflict409:
      type: object
      description: A conflict error response.
      required:
        - message
      properties:
        message:
          type: string
          description: A human-readable error message describing the conflict
          example: Object already exists.
        details:
          type:
            - string
            - 'null'
          description: Additional context or information about the error
          example: Cannot create multiple objects under same key.
    DNSSEC:
      description: DNSSEC contains all the data required to create a DS record at the registry.
      properties:
        algorithm:
          format: int32
          title: 'Algorithm is an integer identifying the algorithm used for signing. Valid values can be found here: https://www.iana.org/assignments/dns-sec-alg-numbers/dns-sec-alg-numbers.xhtml'
          type: integer
        digest:
          description: Digest is a digest of the DNSKEY RR that is registered with the registry.
          type: string
          minLength: 1
        digestType:
          format: int32
          title: 'DigestType is an integer identifying the algorithm used to create the digest. Valid values can be found here: https://www.iana.org/assignments/ds-rr-types/ds-rr-types.xhtml'
          type: integer
        domainName:
          description: DomainName is the domain name.
          type: string
          minLength: 1
        keyTag:
          format: int32
          title: 'KeyTag contains the key tag value of the DNSKEY RR that validates this signature. The algorithm to generate it is here: https://tools.ietf.org/html/rfc4034#appendix-B'
          type: integer
      type: object
      required:
        - domainName
        - keyTag
        - digest
        - digestType
        - algorithm
    ListDNSSECsResponse:
      description: ListDNSSECsResponse contains the list of DS records at the registry.
      properties:
        dnssec:
          description: Dnssec is the list of registered DNSSEC keys.
          items:
            $ref: '#/components/schemas/DNSSEC'
          type: array
      type: object
      required:
        - dnssec
    CreateDNSSECBody:
      description: Request body for creating a DNSSEC DS record.
      type: object
      required:
        - algorithm
        - digest
        - digestType
        - keyTag
      properties:
        algorithm:
          format: int32
          title: 'Algorithm is an integer identifying the algorithm used for signing. Valid values can be found here: https://www.iana.org/assignments/dns-sec-alg-numbers/dns-sec-alg-numbers.xhtml'
          type: integer
        digest:
          description: Digest is a digest of the DNSKEY RR that is registered with the registry.
          type: string
          minLength: 1
        digestType:
          format: int32
          title: 'DigestType is an integer identifying the algorithm used to create the digest. Valid values can be found here: https://www.iana.org/assignments/ds-rr-types/ds-rr-types.xhtml'
          type: integer
        keyTag:
          format: int32
          title: 'KeyTag contains the key tag value of the DNSKEY RR that validates this signature. The algorithm to generate it is here: https://tools.ietf.org/html/rfc4034#appendix-B'
          type: integer
    EmailForwarding:
      description: EmailForwarding contains all the information for an email forwarding entry.
      properties:
        domainName:
          description: DomainName is the domain part of the email address to forward.
          type: string
          example: example.com
          minLength: 1
        emailBox:
          description: EmailBox is the user portion of the email address to forward.
          type: string
          example: admin
          minLength: 1
        emailTo:
          description: EmailTo is the entire email address to forward email to.
          type: string
          example: webmaster@example.com
          format: email
      type: object
      required:
        - domainName
        - emailBox
        - emailTo
    ListEmailForwardingsResponse:
      description: ListEmailForwardingsResponse returns the list of email forwarding entries as well as the pagination information.
      properties:
        emailForwarding:
          description: EmailForwarding is the list of forwarded email boxes.
          items:
            $ref: '#/components/schemas/EmailForwarding'
          type: array
        lastPage:
          description: LastPage is the identifier for the final page of results. It is only populated if there is another page of results after the current page.
          format: int32
          type: integer
        nextPage:
          description: NextPage is the identifier for the next page of results. It is only populated if there is another page of results after the current page.
          format: int32
          type: integer
      type: object
      required:
        - emailForwarding
    CreateEmailForwardingRequest:
      description: EmailForwarding contains all the information for an email forwarding entry.
      properties:
        emailBox:
          description: EmailBox is the user portion of the email address to forward. If your email is "admin@example.com", it would just be "admin". Wildcard and catch-all values (such as "*") are not supported.
          type: string
          example: admin
          minLength: 1
        emailTo:
          description: EmailTo is the entire email address to forward email to.
          type: string
          format: email
          example: webmaster@example.com
          minLength: 1
      type: object
      required:
        - emailBox
        - emailTo
    EmailForwardingsUpdateEmailForwardingBody:
      description: EmailForwarding contains all the information for an email forwarding entry.
      properties:
        emailTo:
          description: EmailTo is the entire email address to forward email to.
          type: string
          minLength: 1
      type: object
      required:
        - emailTo
    Record:
      description: Record is an individual DNS resource record.
      type: object
      properties:
        answer:
          description: |-
            Answer is either the IP address for A or AAAA records; the target for ANAME, CNAME, MX, or NS records; the text for TXT records.
            For SRV records, answer has the following format: "{weight} {port} {target}" e.g. "1 5061 sip.example.org".
          type: string
        domainName:
          description: DomainName is the zone that the record belongs to.
          type: string
        fqdn:
          description: FQDN is the Fully Qualified Domain Name. It is the combination of the host and the domain name. It always ends in a ".". FQDN is ignored in CreateRecord, specify via the Host field instead.
          type: string
          readOnly: true
        host:
          description: |-
            Host is the hostname relative to the zone: e.g. for a record for blog.example.org, domain would be "example.org" and host would be "blog".
            An apex record would be specified by either an empty host "" or "@".
            A SRV record would be specified by "_{service}._{protocol}.{host}": e.g. "_sip._tcp.phone" for _sip._tcp.phone.example.org.
          type:
            - string
            - 'null'
        id:
          description: Unique record id. Value is ignored on Create, and must match the URI on Update.
          format: int32
          type: integer
          readOnly: true
        priority:
          description: Priority is only required for MX and SRV records, it is ignored for all others.
          format: int64
          type: integer
        ttl:
          description: TTL is the time this record can be cached for in seconds. name.com allows a minimum TTL of 300, or 5 minutes.
          format: int64
          type: integer
        type:
          description: 'Type is one of the following: A, AAAA, ANAME, CNAME, MX, NS, SRV, or TXT.'
          type:
            - string
            - 'null'
      required:
        - type
        - ttl
    ListRecordsResponse:
      description: ListRecordsResponse is the response for the ListRecords function.
      properties:
        lastPage:
          description: LastPage is the identifier for the final page of results. It is only populated if there is another page of results after the current page.
          format: int32
          type: integer
        nextPage:
          description: NextPage is the identifier for the next page of results. It is only populated if there is another page of results after the current page.
          format: int32
          type: integer
        totalCount:
          description: TotalCount is total number of results.
          format: int32
          type: integer
        from:
          description: From specifies starting record number on current page.
          format: int32
          type: integer
        to:
          description: To specifies ending record number on current page.
          format: int32
          type: integer
        records:
          items:
            $ref: '#/components/schemas/Record'
          title: Records contains the records in the zone
          type: array
      type: object
      required:
        - records
        - to
        - from
        - totalCount
    DNSCreateRecordBody:
      description: Record is an individual DNS resource record.
      type: object
      properties:
        answer:
          description: |-
            Answer is either the IP address for A or AAAA records; the target for ANAME, CNAME, MX, or NS records; the text for TXT records.
            For SRV records, answer has the following format: "{weight} {port} {target}" e.g. "1 5061 sip.example.org".
          type: string
          minLength: 1
        fqdn:
          description: FQDN is the Fully Qualified Domain Name. It is the combination of the host and the domain name. It always ends in a ".". FQDN is ignored in CreateRecord, specify via the Host field instead.
          type: string
        host:
          description: |-
            Host is the hostname relative to the zone: e.g. for a record for blog.example.org, domain would be "example.org" and host would be "blog".
            An apex record would be specified by either an empty host "" or "@".
            A SRV record would be specified by "_{service}._{protocol}.{host}": e.g. "_sip._tcp.phone" for _sip._tcp.phone.example.org.
          type: string
        id:
          description: Unique record id. Value is ignored on Create, and must match the URI on Update.
          format: int32
          type: integer
        priority:
          description: Priority is only required for MX and SRV records, it is ignored for all others.
          format: int64
          type: integer
        ttl:
          description: TTL is the time this record can be cached for in seconds. name.com allows a minimum TTL of 300, or 5 minutes.
          format: int64
          type: integer
        type:
          description: 'Type is one of the following: A, AAAA, ANAME, CNAME, MX, NS, SRV, or TXT.'
          type: string
          enum:
            - A
            - AAAA
            - ANAME
            - CNAME
            - MX
            - NS
            - SRV
            - TXT
      required:
        - type
        - host
        - answer
    DNSUpdateRecordBody:
      description: Record is an individual DNS resource record.
      type: object
      properties:
        answer:
          description: |-
            Answer is either the IP address for A or AAAA records; the target for ANAME, CNAME, MX, or NS records; the text for TXT records.
            For SRV records, answer has the following format: "{weight} {port} {target}" e.g. "1 5061 sip.example.org".
          type: string
          minLength: 1
        fqdn:
          description: FQDN is the Fully Qualified Domain Name. It is the combination of the host and the domain name. It always ends in a ".". FQDN is ignored in CreateRecord, specify via the Host field instead.
          type: string
        host:
          description: |-
            Host is the hostname relative to the zone: e.g. for a record for blog.example.org, domain would be "example.org" and host would be "blog".
            An apex record would be specified by either an empty host "" or "@".
            A SRV record would be specified by "_{service}._{protocol}.{host}": e.g. "_sip._tcp.phone" for _sip._tcp.phone.example.org.
          type: string
        priority:
          description: Priority is only required for MX and SRV records, it is ignored for all others.
          format: int64
          type: integer
        ttl:
          description: TTL is the time this record can be cached for in seconds. name.com allows a minimum TTL of 300, or 5 minutes.
          format: int64
          type: integer
        type:
          description: 'Type is one of the following: A, AAAA, ANAME, CNAME, MX, NS, SRV, or TXT.'
          type: string
          enum:
            - A
            - AAAA
            - ANAME
            - CNAME
            - MX
            - NS
            - SRV
            - TXT
      required:
        - type
        - answer
    URLForwarding:
      description: URLForwarding represents a URL forwarding entry, allowing a domain to redirect to another URL using different forwarding methods.
      type: object
      required:
        - host
        - forwardsTo
        - type
      properties:
        domainName:
          description: The domain name (without subdomains) that is being forwarded.
          type: string
          format: hostname
          example: example.org
        forwardsTo:
          description: The destination URL to which this hostname will be forwarded.
          type: string
          format: uri
          example: https://destination-site.com
        host:
          title: The subdomain portion of the hostname
          description: The subdomain portion of the hostname that is being forwarded.
          type: string
          example: www
        meta:
          description: |
            Meta tags to include in the HTML page when using "masked" forwarding.
            Ignored for other forwarding types.
            Example: `<meta name='keywords' content='fish, denver, platte'>`
          type:
            - string
            - 'null'
          example: <meta name='keywords' content='website, forwarding, masked'>
        title:
          description: |
            The title to be used for the HTML page when using "masked" forwarding.
            Ignored for other forwarding types.
          type:
            - string
            - 'null'
          example: Welcome to my forwarded website
        type:
          description: |
            The type of URL forwarding. Valid values:
              - `masked`: Retains the original domain in the address bar, preventing the user from seeing the actual destination URL. Sometimes called iframe forwarding.
              - `redirect`: Uses a standard HTTP redirect (301), which changes the address bar to the destination URL.
              - `302`: Uses a temporary HTTP redirect (302), which changes the address bar to the destination URL but indicates the resource is temporarily located elsewhere.
          type: string
          enum:
            - masked
            - redirect
            - '302'
          example: redirect
    URLForwardingResponse:
      description: URLForwarding represents a URL forwarding entry response, allowing a domain to redirect to another URL using different forwarding methods.
      allOf:
        - $ref: '#/components/schemas/URLForwarding'
        - type: object
          properties:
            id:
              description: Server-assigned unique identifier for the URL forwarding record. Use this ID with the URL Forwarding by-ID endpoints to get, update, or delete records.
              type: integer
              format: int32
              example: 12345
            host:
              title: The subdomain portion of the hostname
              description: The subdomain portion of the hostname that is being forwarded.
              type: string
              example: www
    ListURLForwardingsResponse:
      description: ListURLForwardingsResponse is the response for the ListURLForwardings function.
      type: object
      properties:
        lastPage:
          description: LastPage is the identifier for the final page of results. It is only populated if there is another page of results after the current page.
          format: int32
          type:
            - integer
            - 'null'
          example: 5
          minimum: 0
        nextPage:
          description: NextPage is the identifier for the next page of results. It is only populated if there is another page of results after the current page.
          format: int32
          type:
            - integer
            - 'null'
          example: 2
          minimum: 0
        urlForwarding:
          description: URLForwarding is the list of URL forwarding entries.
          items:
            $ref: '#/components/schemas/URLForwardingResponse'
          type: array
          example: []
          minItems: 0
      required:
        - urlForwarding
    URLForwardingInput:
      description: 'Fields for creating a URL forwarding entry. '
      type: object
      required:
        - host
        - forwardsTo
        - type
      properties:
        forwardsTo:
          description: The destination URL to which this hostname will be forwarded.
          type: string
          format: uri
          example: https://destination-site.com
        host:
          title: The subdomain portion of the hostname
          description: The subdomain portion of the hostname that is being forwarded. Use an empty string for the apex.
          type: string
          example: www
        meta:
          description: |
            Meta tags to include in the HTML page when using "masked" forwarding.
            Ignored for other forwarding types.
            Example: `<meta name='keywords' content='fish, denver, platte'>`
          type:
            - string
            - 'null'
          example: <meta name='keywords' content='website, forwarding, masked'>
        title:
          description: |
            The title to be used for the HTML page when using "masked" forwarding.
            Ignored for other forwarding types.
          type:
            - string
            - 'null'
          example: Welcome to my forwarded website
        type:
          description: |
            The type of URL forwarding. Valid values:
              - `masked`: Retains the original domain in the address bar, preventing the user from seeing the actual destination URL. Sometimes called iframe forwarding.
              - `redirect`: Uses a standard HTTP redirect (301), which changes the address bar to the destination URL.
              - `302`: Uses a temporary HTTP redirect (302), which changes the address bar to the destination URL but indicates the resource is temporarily located elsewhere.
          type: string
          enum:
            - masked
            - redirect
            - '302'
          example: redirect
    URLForwardingUpdate:
      description: Fields for updating a URL forwarding entry. Omit a property to leave it unchanged. An empty `host` string is the apex, not "unchanged". At least one property must be present; an empty body is rejected.
      type: object
      minProperties: 1
      properties:
        forwardsTo:
          description: The destination URL to which this hostname will be forwarded.
          type: string
          format: uri
          example: https://destination-site.com
        host:
          title: The subdomain portion of the hostname
          description: The subdomain portion of the hostname that is being forwarded. Omit this field to keep the existing host. Send an empty string to move the forwarding to the apex.
          type: string
          example: www
        meta:
          description: |
            Meta tags to include in the HTML page when using "masked" forwarding.
            Ignored for other forwarding types.
            Example: `<meta name='keywords' content='fish, denver, platte'>`
          type:
            - string
            - 'null'
          example: <meta name='keywords' content='website, forwarding, masked'>
        title:
          description: |
            The title to be used for the HTML page when using "masked" forwarding.
            Ignored for other forwarding types.
          type:
            - string
            - 'null'
          example: Welcome to my forwarded website
        type:
          description: |
            The type of URL forwarding. Valid values:
              - `masked`: Retains the original domain in the address bar, preventing the user from seeing the actual destination URL. Sometimes called iframe forwarding.
              - `redirect`: Uses a standard HTTP redirect (301), which changes the address bar to the destination URL.
              - `302`: Uses a temporary HTTP redirect (302), which changes the address bar to the destination URL but indicates the resource is temporarily located elsewhere.
          type: string
          enum:
            - masked
            - redirect
            - '302'
          example: redirect
    VanityNameserver:
      description: VanityNameserver represents a custom nameserver associated with a domain, including its hostname and a list of IP addresses for glue records.
      properties:
        domainName:
          description: DomainName is the root domain for which this vanity nameserver is created. For example, if the hostname is 'ns1.example.com', the domainName would be 'example.com'.
          type: string
          format: hostname
          example: example.com
        hostname:
          description: Hostname is the fully qualified domain name (FQDN) of the vanity nameserver. It must be a subdomain of the domain specified in 'domainName'.
          type: string
          format: hostname
          example: ns1.example.com
        ips:
          description: IPs is a list of IP addresses that are used for glue records for this vanity nameserver. These should be valid IPv4 or IPv6 addresses.
          type: array
          items:
            type: string
            format: ip
          example:
            - 192.168.1.1
            - 2001:0db8:85a3:0000:0000:8a2e:0370:7334
          minItems: 1
      type: object
      required:
        - domainName
        - hostname
        - ips
    VanityNameserverResponse:
      description: VanityNameserver response schema with full hostname
      allOf:
        - $ref: '#/components/schemas/VanityNameserver'
        - type: object
          properties:
            hostname:
              description: Hostname is the fully qualified domain name (FQDN) of the vanity nameserver. It must be a subdomain of the domain specified in 'domainName'.
              type: string
              format: hostname
              example: ns1.example.com
    ListVanityNameserversResponse:
      description: ListVanityNameserversResponse returns the list of vanity nameservers for the domain.
      properties:
        lastPage:
          description: LastPage is the identifier for the final page of results. It is only populated if there is another page of results after the current page. If no further pages exist, this field will be null.
          type:
            - integer
            - 'null'
          format: int32
          minimum: 1
          example: 5
        nextPage:
          description: NextPage is the identifier for the next page of results. It is only populated if there is another page of results after the current page. If no further pages exist, this field will be null.
          type:
            - integer
            - 'null'
          format: int32
          minimum: 1
          example: 2
        vanityNameservers:
          description: VanityNameservers is the list of vanity nameservers associated with the domain. If no vanity nameservers are configured, this will be an empty array.
          type: array
          items:
            $ref: '#/components/schemas/VanityNameserverResponse'
          example: []
      type: object
      required:
        - vanityNameservers
    CreateVanityNameserverBody:
      description: VanityNameserver contains the hostname as well as the list of IP addresses for nameservers.
      properties:
        hostname:
          description: The subdomain portion of the nameserver hostname. The domain portion will be  taken from the URL path. For example, to create 'ns1.example.com', specify 'ns1'  when calling the endpoint for the domain 'example.com'.
          type: string
          example: ns1
        ips:
          description: IPs is a list of IP addresses that are used for glue records for this nameserver. These should be valid IPv4 or IPv6 addresses.
          type: array
          items:
            type: string
            format: ip
          example:
            - 192.168.1.10
            - 2001:0db8:85a3:0000:0000:8a2e:0370:7334
          minItems: 1
      type: object
      required:
        - hostname
        - ips
    UpdateVanityNameserverBody:
      description: UpdateVanityNameserverBody contains the list of IP addresses to update for a vanity nameserver.
      properties:
        ips:
          description: IPs is the updated list of IP addresses to be used for glue records for this vanity nameserver. Providing an empty array will remove all existing IPs.
          type: array
          items:
            type: string
            format: ip
          example:
            - 192.168.1.10
            - 2001:0db8:85a3:0000:0000:8a2e:0370:7334
      type: object
      required:
        - ips
    EmptyObject:
      type: object
      properties: {}
      additionalProperties: false
      description: 'Empty JSON object. This operation does not accept a payload; clients must still send `Content-Type: application/json` with body `{}`.'
      example: {}
    AuthCodeResponse:
      description: "This endpoint retrieves the transfer authorization code (EPP code) for qualifying domains. Locks may exist on a domain that can prevent the initiation of a transfer request, despite an auth code being returned by the API.\_ Use the [Get Domain](/api/v1/reference/domains/get-domain) API to check the lock status of a domain. A Create Transfer request for a locked domain will return an error."
      properties:
        authCode:
          description: AuthCode is the authorization code needed to transfer a domain to another registrar. If you are storing auth codes, be sure to store them in a secure manner.
          type: string
      type: object
      required:
        - authCode
    GenericError500:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: A human-readable message providing more details about the error.
          example: Internal Server Error
        details:
          type:
            - string
            - 'null'
          description: Additional context or information about the error.
          example: Something went wrong.
    PricingResponse:
      description: |-
        PricingResponse returns the Pricing related information from the GetPricingForDomain endpoint.
        Covers standard and registry-premium **registration** pricing, plus renewal and transfer. Not a discovery endpoint — does not return `purchaseType`. Does not return aftermarket, expiring, or backorder acquisition prices. See the [Domain pricing guide](/guides/domain-pricing).
      properties:
        premium:
          description: Premium indicates whether this registration pricing result is for a registry premium or other non-standard registration. Reflects registration pricing only — may differ from discovery `premium` for aftermarket, expiring, or backorder results. When `true`, `purchasePrice` must be passed on [Create Domain](/api/v1/reference/domains/create-domain), [Renew Domain](/api/v1/reference/domains/renew-domain), or [Create Transfer](/api/v1/reference/transfers/create-transfer), requests.
          type: boolean
        purchasePrice:
          description: 'PurchasePrice is the total standard or registry-premium registration cost for the requested `years` query parameter — not a one-year component. Does not include aftermarket, expiring, or backorder acquisition prices. If `null`, name.com is not currently accepting registrations for this domain/term combination. For registry premium create (`purchaseType: registration`), pass this value with the same `years`. For aftermarket, expiring, or backorder types, use `purchasePrice` from Search/Check Availability instead.'
          format: double
          type:
            - number
            - 'null'
          example: 24.99
        renewalPrice:
          description: RenewalPrice is the total renewal cost for the requested `years`. If `null`, name.com is not currently accepting renewals for this domain/term combination. Pass as `purchasePrice` on [Renew Domain](/api/v1/reference/domains/renew-domain) for premium renewals. Do not use for computing Create Domain `purchasePrice` or multi-year create totals.
          format: double
          type:
            - number
            - 'null'
          example: 24.99
        transferPrice:
          description: TransferPrice is the inbound transfer cost for this domain. The `years` query parameter does not affect this value. Pricing uses the TLD's minimum transfer/registration term (typically 1 year; for TLDs with a higher minimum, e.g. `.ai`, the total will reflect that minimum). If `null`, transfers are not accepted for this domain/term combination. Pass to [Create Transfer](/api/v1/reference/transfers/create-transfer) as `purchasePrice` when transfer price validation applies (required for premium transfers).
          format: double
          type:
            - number
            - 'null'
          example: 24.99
      type: object
      required:
        - premium
        - purchasePrice
        - transferPrice
        - renewalPrice
    DomainsPurchasePrivacyBody:
      description: Request body for enabling or extending WHOIS privacy on a domain.
      properties:
        purchasePrice:
          description: WHOIS privacy is free for API users. This field does not add a privacy fee.
          format: double
          type: number
        years:
          description: Years is the number of years to enable or extend Whois Privacy for. Years defaults to 1 and cannot be more then the domain expiration date.
          format: int32
          type: integer
          default: 1
      type: object
    PrivacyResponse:
      description: PrivacyResponse contains the updated domain info as well as the order info for the Whois Privacy that was enabled or extended.
      properties:
        domain:
          $ref: '#/components/schemas/DomainResponsePayload'
        order:
          description: Order is an identifier for this purchase.
          format: int32
          type: integer
        totalPaid:
          description: TotalPaid is the total amount paid, including VAT when applicable. Whois Privacy is free and is not included in this amount.
          format: double
          type: number
          example: 0
      type: object
      required:
        - order
        - totalPaid
    Conflict409:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: A human-readable message providing more details about the error
          example: Conflict
        details:
          type: string
          description: Additional context or information about the pricing error
          example: You are attempting to subscribe to an event you have already subscribed to.
    DomainsRenewDomainBody:
      description: |-
        RenewDomainRequest passes the domain name and purchase parameters to the RenewDomain function.
        See the [Domain pricing guide](/guides/domain-pricing) for how `purchasePrice` relates to Get Pricing `renewalPrice`.
      properties:
        purchasePrice:
          description: PurchasePrice is the total USD renewal cost for the requested `years`, before VAT. VAT is applied when applicable and must not be included here. If sent, must match Get Pricing `renewalPrice` exactly. **Omit** for standard (non-premium) renewals. **Required** for premium renewals — use `renewalPrice` from [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) with matching `years`.
          format: double
          type: number
          example: 10.99
        years:
          description: Years specifies the renewal term in years. Defaults to each TLD's minimum registration term if omitted — usually 1 year (2 for `.ai`). Must be a supported registration term for the TLD (commonly 1–10 years). For premium renewals, call [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) with the same `years` value.
          format: int32
          type: integer
          example: 3
      type: object
    RenewDomainResponse:
      description: RenewDomainResponse contains the updated domain info as well as the order info for the renewed domain.
      properties:
        domain:
          $ref: '#/components/schemas/Domain'
        order:
          format: int32
          title: Order is an identifier for this purchase
          type: integer
        totalPaid:
          description: TotalPaid is the total amount paid, including VAT.
          format: double
          type: number
          example: 5.95
      type: object
    DomainsSetContactsBody:
      description: SetContactsRequest passes the contact info for each role to the SetContacts function.
      properties:
        contacts:
          $ref: '#/components/schemas/ContactsRequest'
      type: object
      required:
        - contacts
    DomainsSetNameserversBody:
      description: SetNameserversRequest passes the list of nameservers to set for the SetNameserver function.
      properties:
        nameservers:
          description: Nameservers is a list of the nameservers to set. Nameservers should already be set up and hosting the zone properly as some registries will verify before allowing the change.
          items:
            type: string
            example: ns1.name.com
            minItems: 1
          type: array
      required:
        - nameservers
      type: object
      example:
        nameservers:
          - ns1.name.com
          - ns2.name.com
    SearchPurchaseType:
      description: |
        Purchase Type indicates what kind of purchase a discovery result represents.
        Returned by [Search](/api/v1/reference/domains/search) and [Check Availability](/api/v1/reference/domains/check-availability) — not [Zone Check](/api/v1/reference/domains/zone-check).

        Copy the value to [Create Domain](/api/v1/reference/domains/create-domain) as `purchaseType`.

        **Recommendation:** Pass `registration` on Search and Check Availability unless you choose to support acquisition inventory. Other values are supported but add integration complexity.

        **Pricing by type:**

        - `registration` — Standard or registry premium. Check the `premium` flag: when `false`, omit `purchasePrice` on create (Get Pricing with matching `years` is optional for preview only); when `true`, `purchasePrice` is required from Get Pricing with matching `years`. `years` controls price and registration length.
        - `aftermarket_s`, `aftermarket_b`, `aftermarket_i` — Flat acquisition fee from Search or Check Availability; `purchasePrice` required. `years` does not multiply price or guarantee registration length — omit or pass TLD default.
        - `expiring`, `backorder` — Flat acquisition fee from Search or Check Availability; `purchasePrice` required. Get Pricing does not return these prices. `years` does not multiply price or guarantee registration length — omit or pass TLD default. Renew after acquisition to extend registration.

        See the [Domain pricing guide](/guides/domain-pricing).
      type: string
      enum:
        - registration
        - aftermarket_i
        - expiring
        - backorder
        - aftermarket_s
        - aftermarket_b
    AvailabilityRequest:
      description: 'Checks if one or more domain names are available for registration (up to 50 domains). Important: Do not encode the `:` in the path. Use `/core/v1/domains:checkAvailability`, not `/core/v1/domains%3AcheckAvailability`.'
      properties:
        domainNames:
          description: DomainNames is the list of domains to check if they are available.
          items:
            type: string
            minLength: 1
          type: array
          maxItems: 50
          minItems: 1
        purchaseType:
          description: 'Optional filter. **Recommended:** `registration` for most integrations — omit only if you support acquisition types. Non-matching domains are returned with `purchasable: false` (Search omits them instead). See the [Domain purchase pricing guide](/guides/domain-pricing).'
          allOf:
            - $ref: '#/components/schemas/SearchPurchaseType'
      type: object
      required:
        - domainNames
    SearchResult:
      description: SearchResult is returned by the CheckAvailability and Search endpoints.
      properties:
        domainName:
          description: DomainName is the punycode encoding of the result domain name.
          type: string
          example: example.com
        premium:
          description: 'Premium indicates whether this discovery result has premium or non-standard pricing. Only returned for purchasable domains. When `true` with `purchaseType: registration` → registry premium (use [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) for multi-year totals). When `true` with aftermarket, expiring, or backorder `purchaseType` values → flat acquisition fee (use discovery `purchasePrice`; `years` on create does not multiply price or guarantee registration length). When `true`, `purchasePrice` must be passed on Create Domain.'
          type: boolean
          example: true
        purchasable:
          description: Purchasable indicates whether the search result is available for purchase.
          type: boolean
          example: true
        purchasePrice:
          description: 'PurchasePrice is the minimum-term list or flat acquisition price from discovery, in USD. Only returned for purchasable domains. For `purchaseType: registration` when `purchasePrice` is required on create, use [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) with matching `years` instead. For aftermarket, expiring, and backorder types, pass this flat acquisition fee on Create Domain — not affected by `years`. Get Pricing does not return these acquisition prices. Recommended to re-check with Check Availability immediately before create for all types — prices can change.'
          format: double
          type: number
          example: 10.99
        purchaseType:
          description: 'PurchaseType indicates what kind of purchase this discovery result is for. Only returned for purchasable domains. Pass to Create Domain as `purchaseType`. See [SearchPurchaseType](#/components/schemas/SearchPurchaseType) for pricing behavior per value. When `premium: true` or the type is not `registration`, follow the [Domain pricing guide](/guides/domain-pricing).'
          allOf:
            - $ref: '#/components/schemas/SearchPurchaseType'
        renewalPrice:
          description: RenewalPrice is the minimum-term renewal total for this domain (typically 1 year; varies by TLD). Only returned for purchasable domains. Informational for standard [Renew Domain](/api/v1/reference/domains/renew-domain) flows — do **not** use to calculate Create Domain `purchasePrice` or multi-year create totals. For premium renewals, use `renewalPrice` from [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) with matching `years`, not this discovery value.
          format: double
          type: number
          example: 10.99
        sld:
          description: SLD is first portion of the domain_name.
          type: string
          example: example
        tld:
          description: TLD is the rest of the domain_name after the SLD.
          type: string
          example: com
        reason:
          description: Reason provides additional context when unavailable (e.g. registry is in maintenance).
          type: string
      type: object
      required:
        - domainName
        - sld
        - tld
        - purchasable
    SearchResponse:
      description: SearchResponse returns a list of search results.
      properties:
        results:
          description: Results of the search are returned here, the order should not be relied upon.
          items:
            $ref: '#/components/schemas/SearchResult'
          type: array
      type: object
    SearchRequest:
      description: SearchRequest is used to specify the search parameters.
      properties:
        keyword:
          description: Keyword is the search term to search for. It can be just a word, or a whole domain name.
          type: string
          example: mydomain
        timeout:
          description: |-
            Timeout is a value in milliseconds on how long to perform the search for. Valid timeouts are between 500ms to 12,000ms. If not specified, timeout defaults to 12,000ms.
            Since some additional processing is performed on the results, a response may take longer then the timeout.
          format: int32
          type: integer
          example: 2500
        tldFilter:
          description: TLDFilter will limit results to only contain the specified TLDs. There is a maximum of 50 TLDs that can be used in this filter
          items:
            type: string
          type: array
          maxItems: 50
          example:
            - com
            - net
            - org
        purchaseType:
          description: Optional. Limits results to the given `purchaseType`. **Recommended:** `registration` for most integrations — omit only if you choose to support acquisition types. See the [Domain purchase pricing guide](/guides/domain-pricing).
          allOf:
            - $ref: '#/components/schemas/SearchPurchaseType'
      type: object
      required:
        - keyword
    HelloResponse:
      properties:
        motd:
          description: Motd is a message of the day. It might provide some useful information.
          type: string
        serverName:
          description: ServerName is an identfier for which server is being accessed.
          type: string
        serverTime:
          description: ServerTime is the current date/time at the server.
          type: string
        username:
          description: Username is the account name you are currently logged into.
          type: string
      title: HelloResponse is the response from the HelloFunc command
      type: object
      required:
        - motd
        - serverName
        - serverTime
        - username
    SubscriptionRecord:
      properties:
        active:
          title: Whether or not the subscription is active
          type: boolean
        createDate:
          title: Date the subscription record was created (Date you subscribed)
          type: string
        eventName:
          title: The name of the event you have subscribed to
          type: string
        id:
          format: int32
          title: The ID of the event record. Used for updating and canceling
          type: integer
        updateDate:
          title: Date the subscription record was updated (Date you made changes)
          type:
            - string
            - 'null'
        url:
          title: The URL we will send a POST request to with the notification message
          type: string
      required:
        - active
        - id
        - createDate
        - eventName
        - url
        - updateDate
      title: |-
        *
        The record for each notification you have subscribed to
      type: object
    ListSubscribedWebhooksResponse:
      properties:
        subscriptions:
          items:
            description: Array of subscription objects. One for each event you have subscribed to.
            $ref: '#/components/schemas/SubscriptionRecord'
          type: array
      title: The response from listing all of the notifications you have subscribed to
      type: object
    AvailableWebhooks:
      description: The list of configured webhooks you can subscribe to
      type: string
      enum:
        - account.credit.balance_change
        - account.domain.removal
        - domain.lock.status_change
        - domain.transfer.status_change
        - domain.transfer_out.status_change
        - contact.verification.status_change
        - domain.transfer.internal_in
        - domain.transfer.internal_out
        - domain.registry.rejection
        - domain.registry.compliance_notice
        - domain.expiration
    SubscribeToNotification:
      description: Request to subscribe to a specific webhook notification
      properties:
        eventName:
          $ref: '#/components/schemas/AvailableWebhooks'
        url:
          type: string
          description: The URL we will send the notification data to
          example: https://example.com
        active:
          type: boolean
          description: If the webhook should be active. This allows a webhook to be deactivated in our system. It may be useful to deactivate a webhook if the server that receives the POST request is undergoing scheduled maintenance, for example.
      required:
        - eventName
        - url
        - active
    SubscribeToNotificationResponse:
      properties:
        subscription:
          $ref: '#/components/schemas/SubscriptionRecord'
      title: Response from subscribing to a notification
      type: object
    ModifySubscriptionResponse:
      properties:
        subscription:
          $ref: '#/components/schemas/SubscriptionRecord'
      type: object
    OrderItem:
      description: OrderItem contains all the order item data.
      properties:
        duration:
          description: Duration is the number of intervals.
          format: int32
          type: integer
        id:
          format: int32
          type: integer
          title: Id is the unique identifier of the order item.
        interval:
          description: Interval is the  unit of time ("year", "month"). May be null for items that have no applicable interval.
          type:
            - string
            - 'null'
        name:
          description: Name is name of the item ('example.ninja').
          type:
            - string
            - 'null'
        originalPrice:
          description: OriginalPrice is the original price of the item before discounts.
          format: float
          type:
            - number
            - 'null'
        price:
          description: Price is the final price of the item.
          format: float
          type: number
        priceNonUsd:
          description: PriceNonUsd is the price of the item if order has non-usd currency.
          format: float
          type: number
        quantity:
          description: Quantity is the number of items.
          format: int32
          type: integer
        status:
          description: Status indicates state of the order ('success', 'failed', 'refunded').
          type: string
        taxAmount:
          description: TaxAmount is the tax charged for this item, if applicable.
          format: float
          type:
            - number
            - 'null'
        tld:
          description: Tld is (optional) tld of domain name, if applicable ('ninja').
          type:
            - string
            - 'null'
        type:
          description: Type is type of  the item ('registration', 'whois_privacy').
          type: string
        isRefundable:
          description: IsRefundable indicates whether the item in your order is currently eligible for a refund through the refund endpoint based on name.com's refund rules. These refunds are only applicable for invalid or fraudulent orders within a few days or registration (usually 5).
          type: boolean
          example: true
          default: false
      type: object
      required:
        - duration
        - id
        - interval
        - name
        - originalPrice
        - price
        - quantity
        - status
        - type
        - isRefundable
    Order:
      description: Order contains all the data for an order.
      properties:
        authAmount:
          description: AuthAmount is the amount authorized to complete the order purchase.
          format: float
          type: number
        createDate:
          description: CreateDate is the date the order was placed.
          type: string
        currency:
          description: Currency indicates currency of the order ('USD', 'CNY').
          type: string
        currencyRate:
          description: CurrencyRate is the conversion rate from USD to order's currency.  This field is only populated if order's currency is non-USD.
          format: float
          type: number
        finalAmount:
          description: FinalAmount is the final amount of the order, after discounts and refunds.
          type: number
          format: float
        id:
          format: int32
          type: integer
          title: Id is the unique identifier of the order.
        orderItems:
          description: OrderItems is the collection of 1 or more items in the order.
          items:
            $ref: '#/components/schemas/OrderItem'
          type: array
        registrar:
          description: Registrar is registrar with which order is placed.
          type: string
        status:
          description: Status indicates the state of the order ('success', 'failed').
          type: string
        totalCapture:
          description: TotalCapture is the amount captured.
          format: float
          type: number
          example: 10.95
        totalRefund:
          description: TotalRefund is the amount, if any, refunded. Default is 0.00.
          format: float
          type: number
          example: 10.95
      type: object
    ListOrdersResponse:
      description: ListOrdersResponse is the response from a list request, it contains the paginated list of Orders.
      properties:
        lastPage:
          description: LastPage is the identifier for the final page of results. It is only populated if there is another page of results after the current page.
          format: int32
          type: integer
        nextPage:
          description: NextPage is the identifier for the next page of results. It is only populated if there is another page of results after the current page.
          format: int32
          type: integer
        totalCount:
          description: TotalCount is total number of results.
          format: int32
          type: integer
        from:
          description: From specifies starting record number on current page.
          format: int32
          type: integer
        to:
          description: To specifies ending record number on current page.
          format: int32
          type: integer
        orders:
          items:
            $ref: '#/components/schemas/Order'
          description: Orders is the collection of orders, if any, in the requesting account.
          type: array
        parentAccountId:
          description: ParentAccountId field is populated when requesting account has a parent account id.
          format: int32
          type: integer
      type: object
      required:
        - orders
        - to
        - from
        - totalCount
    RefundRequest:
      description: RefundRequest contains the order and order items to be refunded. Only domain registrations and security products purchased within the Add Grace Period (AGP) are eligible for refunds.
      type: object
      required:
        - orderId
        - orderItemIds
      properties:
        orderId:
          type: integer
          format: int32
          description: The unique identifier of the order containing the item(s) to be refunded. Use the List Orders endpoint to retrieve order IDs.
          example: 123456
        orderItemIds:
          type: array
          items:
            type: integer
            format: int32
          minItems: 1
          description: |
            An array of order item IDs to be refunded. All items must belong to the specified order. Use the List Orders endpoint to retrieve order item IDs.
          example:
            - 987654
            - 987655
    RefundItemResult:
      description: RefundItemResult contains the result of a refund operation for a single order item.
      type: object
      required:
        - orderId
        - orderItemId
        - orderItemStatus
        - refundAmount
      properties:
        orderId:
          type: integer
          format: int32
          description: The unique identifier of the Order that was processed.
          example: 987654
        orderItemId:
          type: integer
          format: int32
          description: The unique identifier of the Order Item that was processed.
          example: 987654
        orderItemStatus:
          type: string
          description: The status of the refund operation for this item.
          enum:
            - refunded
            - failed
            - initialized
            - canceled
          example: refunded
        refundAmount:
          type: number
          format: float
          description: The amount refunded for this order item in USD.
          example: 10.99
        message:
          type:
            - string
            - 'null'
          description: Additional information about the refund result, especially useful for failed items.
          example: Domain successfully deleted and refund processed.
    RefundResponse:
      description: |
        RefundResponse contains the results of a refund operation, including the individual order item results.
        Refunds are issued to the original payment method on file. If the original payment method is unavailable, the refund will be credited to the account balance.
      type: object
      required:
        - results
        - totalRefundAmount
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/RefundItemResult'
          description: An array of refund results for each order item that was processed.
          minItems: 1
        totalRefundAmount:
          type: number
          format: float
          description: The total amount refunded across all order items in USD.
          example: 21.98
    Locked423:
      type: object
      description: Error response returned when a resource is locked and cannot be modified. Used when the Add Grace Period (AGP) deletion window has expired.
      required:
        - message
      properties:
        message:
          type: string
          description: A human-readable message providing more details about the error
          example: Resource Locked
        details:
          type:
            - string
            - 'null'
          description: Additional context or information about the error
          example: The Add Grace Period (AGP) deletion window has expired for this domain.
    BadGateway502:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: A human-readable message providing more details about the error
          example: Registry Connection Unavailable
    TransferStatus:
      type: string
      description: |
        Terminal (finished; will not change):
        - **completed**: Completed.
        - **failed**: Failed.
        - **canceled**: Canceled by the user.
        - **canceled_pending_refund**: Canceled; refund processing.

        Non-terminal (in progress; may change):
        - **pending**: Requested.
        - **submitting_transfer**: Being submitted to the registry.
        - **pending_new_auth_code**: New auth code required.
        - **pending_unlock**: Waiting for losing registrar unlock.
        - **pending_registry_unlock**: Waiting for registry unlock.
        - **pending_transfer**: Pending at the registry.
        - **pending_insert**: Transfer complete; domain will be added to the account.
        - **rejected**: Rejected at the losing registrar.
      enum:
        - canceled
        - canceled_pending_refund
        - completed
        - failed
        - pending
        - pending_insert
        - pending_new_auth_code
        - pending_registry_unlock
        - pending_transfer
        - pending_unlock
        - rejected
        - submitting_transfer
      example: pending_transfer
    Transfer:
      description: Transfer contains all relevant data for a domain transfer to name.com.
      type: object
      properties:
        domainName:
          description: DomainName is the domain to be transfered to name.com.
          type: string
          example: example.com
        email:
          description: Email is the email address that the approval email was sent to. Not every TLD requries an approval email. This is usually pulled from Whois.
          type: string
          format: email
          example: admin@example.com
        status:
          $ref: '#/components/schemas/TransferStatus'
      required:
        - domainName
        - status
    ListTransfersResponse:
      description: ListTransfersResponse returns the list of pending transfers as well as the pagination information if relevant.
      type: object
      properties:
        lastPage:
          description: LastPage is the identifier for the final page of results. It is only populated if there is another page of results after the current page.
          format: int32
          type: integer
        nextPage:
          description: NextPage is the identifier for the next page of results. It is only populated if there is another page of results after the current page.
          format: int32
          type: integer
        totalCount:
          description: TotalCount is total number of results.
          format: int32
          type: integer
        from:
          description: From specifies starting record number on current page.
          format: int32
          type: integer
        to:
          description: To specifies ending record number on current page.
          format: int32
          type: integer
        transfers:
          items:
            $ref: '#/components/schemas/Transfer'
          description: Transfers is a list of pending transfers
          type: array
      required:
        - transfers
        - to
        - from
        - totalCount
    CreateTransferRequest:
      description: |-
        CreateTransferRequest passes the required transfer info to the CreateTransfer function.
        See the [Domain pricing guide](/guides/domain-pricing) for how `purchasePrice` relates to [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) `transferPrice`.
      properties:
        authCode:
          description: AuthCode is the authorization code for the transfer. Not all TLDs require authorization codes, but most do.
          type: string
          example: ABC123
          minLength: 1
        domainName:
          description: DomainName is the domain you want to transfer to name.com.
          type: string
          example: example.com
          minLength: 1
        privacyEnabled:
          description: Whether to include Whois Privacy with the transfer. Whois Privacy is free. If omitted, the account default from account settings is used. Privacy is only added when the TLD supports it.
          type: boolean
          example: true
        purchasePrice:
          description: PurchasePrice is the USD inbound transfer fee, before VAT. VAT is applied when applicable and must not be included here. If sent, must match Get Pricing `transferPrice` exactly or the request will fail.. **Omit** for standard (non-premium) transfers. **Required** for premium transfers — use `transferPrice` from [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain).
          format: double
          type: number
          example: 12.99
        contacts:
          description: WHOIS contacts to apply when the domain lands in the account. If omitted, the gaining account's default contacts are applied. If provided, include any roles to override; omitted roles use the gaining account's default contacts. Each supplied role must include complete contact fields. A registrar contact-change transfer lock may apply according to the gaining account's settings.
          allOf:
            - $ref: '#/components/schemas/ContactsRequest'
      type: object
      required:
        - domainName
        - authCode
    CreateTransferResponse:
      description: CreateTransferResponse returns the newly created transfer resource as well as the order information.
      properties:
        order:
          description: Order is an identifier for this purchase.
          format: int32
          type: integer
          example: 12345
        totalPaid:
          description: TotalPaid is the total amount paid, including VAT when applicable. Whois Privacy is free and is not included in this amount.
          format: double
          type: number
          example: 12.99
        transfer:
          $ref: '#/components/schemas/Transfer'
        warnings:
          description: Optional transfer warnings surfaced by the API when non-blocking registry statuses are detected.
          type: object
          properties:
            message:
              type: string
              description: Brief guidance for resolving potential transfer issues.
              example: Domain has registry statuses that may prevent a successful transfer. Please ensure the domain is unlocked and eligible at the losing registrar.
            statuses:
              type: array
              description: Registry status values that triggered the warning.
              items:
                type: string
              example:
                - clientTransferProhibited
                - clientUpdateProhibited
      type: object
      required:
        - order
        - totalPaid
        - transfer
    GatewayTimeout504:
      type: object
      properties:
        message:
          type: string
          description: A human-readable message providing more details about the error
          example: Unable to retrieve domain status
    CancelTransferOutResponse:
      type: object
      description: Response after successfully canceling a domain transfer out request.
      required:
        - domainName
        - status
      properties:
        domainName:
          type: string
          description: The punycode-encoded domain name.
          example: example.com
        status:
          type: string
          description: The transfer-out status after the operation (e.g. canceled when the cancel succeeded).
          enum:
            - canceled
          example: canceled
    CreateInternalTransferInRequest:
      description: Request body for transferring a domain from another name.com account into the authenticated reseller (gaining) account.
      properties:
        domainName:
          description: Fully qualified domain name to transfer in. The domain must be registered in another name.com account (the losing account).
          type: string
          example: example.com
          minLength: 1
        authCode:
          description: Transfer authorization code (EPP/auth code) for the domain. The losing account holder must obtain this code from the [name.com](https://www.name.com) dashboard; it is not exposed by this API for the losing account.
          type: string
          example: ABC123
          minLength: 1
        contacts:
          description: WHOIS contacts to apply after the transfer. If omitted, the gaining account's default contacts are applied. If provided, include any roles to override; omitted roles use the gaining account's default contacts. Each supplied role must include complete contact fields. A registrar contact-change transfer lock may apply according to the gaining account's settings, consistent with the Set Contacts endpoint.
          allOf:
            - $ref: '#/components/schemas/ContactsRequest'
      required:
        - domainName
        - authCode
      type: object
    TransferEligibilityResponse:
      description: Result of a transfer eligibility check. Indicates whether the domain is currently registered at name.com (in any account) and whether the TLD supports internal transfer between name.com accounts.
      type: object
      required:
        - domainName
        - atName
        - supportsInternalTransfer
      properties:
        domainName:
          description: The domain that was checked, in its canonical (ASCII / punycode) form.
          type: string
          example: example.com
        atName:
          description: Whether the domain is currently registered at name.com (in any account).
          type: boolean
          example: true
        supportsInternalTransfer:
          description: Whether the TLD supports internal transfer between name.com accounts. Mirrors the TLD-level flag returned by Get Tld Requirements. Does not reflect per-account allowlist eligibility for the internal transfer-in API.
          type: boolean
          example: true
    ResellerTldInfo:
      description: General information about a TLD and it's various requirements. This is not a comprehensive list of all information related to a TLD.
      type: object
      properties:
        tld:
          description: The TLD this information relates to.
          type: string
          example: .fr
        ccTld:
          description: Whether the TLD is a Country Code TLD.
          type: boolean
          example: true
        supportsTransferLock:
          description: Whether the TLD supports implementing a Transfer Lock.
          type: boolean
          example: true
        supportsDnssec:
          description: Whether the TLD supports DNSSEC.
          type: boolean
          example: true
        supportsPremium:
          description: Whether there are premium domains for this TLD.
          type: boolean
          example: true
        supportsPrivacy:
          description: Whether the TLD supports WHOIS Privacy.
          type: boolean
          example: true
        supportsInternalTransfer:
          description: Whether the TLD supports internal transfer between reseller accounts.
          type: boolean
          example: true
        requiresPreDelegation:
          description: Whether this TLD requires pre-delegation. If this is true, these domains must be added to the name servers before the domain creation is completed.
          type: boolean
          example: true
        expirationGracePeriod:
          description: The number of days you have to renew your domain after it has expired, but before it is removed from your account.
          type: integer
          format: int32
          example: 25
        allowedRegistrationYears:
          description: The years that a domain is allowed to be registered for.
          type: array
          items:
            type: integer
          example:
            - 1
            - 3
            - 5
            - 8
            - 10
        idnLanguages:
          description: The IND Languages that the TLD supports (if any).
          type: object
          additionalProperties:
            type: string
          example:
            DE: German
            DK: Danish
            ES: Spanish
            IT: Italian
            JP: Japanese
        hsts:
          description: The entire TLD namespace has been added to the HSTS Preload list. As such, all second-level domains under .TLD will only load on modern browsers if a valid SSL certificate has been configured and the webserver is serving HTTPS.
          type: boolean
          example: true
        minDomainLength:
          description: The minimum allowed length for the second level domain (SLD) for a given TLD. The SLD would be the `example` part of `example.com`. Attempts to register a domain with a shorter length than allowed will result in a failure of a Create Domain request.
          type: integer
          format: int32
          example: 3
        minIdnDomainLength:
          description: The minimum allowed length for the second level domain (SLD) that utilizes an IDN character for a given TLD.  The SLD would be the `èxample` part of `èxample.com`. Attempts to register a domain with a shorter length than allowed will result in a failure of a Create Domain request. This value will often be different from the `minDomainLength` for non-IDN registrations.  This parameter will return as `null` for any TLDs that do not support IDN registrations.
          type:
            - integer
            - 'null'
          format: int32
          example: 5
        registryOperator:
          description: The registry that operates the given TLD.
          type: string
          example: verisign
        claimsCheckRequired:
          description: Array of valid purchase types if claims check is required for this TLD for current date/time.  If claims checking is required, returns an array of valid purchase types (e.g., ["registration", "landrush_eap"]).  If claims checking is not required, returns an empty array [].
          type: array
          items:
            type: string
            enum:
              - registration
              - landrush_eap
              - landrush_auction_a
              - landrush_reserve_a
          example:
            - registration
        requireIdnSld:
          description: When true, the TLD only accepts IDN (punycode) second-level domain names in the required script. ASCII/Latin SLDs are not valid for registration.
          type: boolean
          example: false
      required:
        - tld
        - ccTld
        - supportsTransferLock
        - supportsDnssec
        - supportsPremium
        - supportsPrivacy
        - supportsInternalTransfer
        - requiresPreDelegation
        - expirationGracePeriod
        - idnLanguages
        - allowedRegistrationYears
        - hsts
        - minDomainLength
        - minIdnDomainLength
        - registryOperator
        - claimsCheckRequired
        - requireIdnSld
    RequirementField:
      description: A field definition for TLD registration requirements, including validation rules, conditional logic, and nested field structures.
      type: object
      required:
        - type
        - required
      properties:
        description:
          description: A detailed description of what this field is for and any specific requirements or constraints.
          type: string
          example: First name of registrant
        type:
          description: |
            The requirement type of this field. Each requirement type has different information.

            Possible values and their details:

              - **`string`**: These are open string fields that cannot be submitted as empty. They will always have a label. A description is optional as the label may convey all of the required information the user would need to submit.
                  Note: Some string fields may have a required format (i.e. date format of YYYY/MM/DD). The format will be listed in the "validation" parameter if required.
                  Example TLDs: abogado, law, com.br (and more)

              - **`notice`**: These field types will just have a description, and contain information that must be displayed to the user prior to registration. There is no data that will be required to be submitted, so all notice type fields will have a "required" value of `false`.
                  Example TLDs: at (notice only), ca (1 notice field)

              - **`acknowledgement`**: These field types will have a description, label and value. The description must be displayed to the user, the label is the required label for the acknowledgement, and the value is what must be submitted.
                  Example TLDs: security, ngo, music (and more)

              - **`enum`**: The field types have a list of predefined options that the user must choose from in order to submit. Only the values returned in the "options" array will be allowed, or the request will fail validation. Options MAY include dependent fields, as some registries required additional information depending on what was chosen for the "parent" option. All dependent fields will follow the same field patterns as the parent fields.
                  Options: These are the predefined options for the enum type fields. They will always have a label and a value. The value is what must be submitted. The options MAY include a description, but will mostly only have a label parameter.
                  Note: There may be a single option returned for an enum. This is because that is the ONLY OPTION ALLOWED by the registry.
                  Example TLDs with simple lists: ca, es (and more)
                  Example TLDs with dependent fields: fr, se, com.br

              - **`boolean`**: Boolean fields for simple true/false acknowledgements or selections.
                  Example TLDs: security
          enum:
            - string
            - notice
            - acknowledgement
            - enum
            - boolean
          example: string
        required:
          description: Whether this field is mandatory for domain registration. If true, the field must be provided.
          oneOf:
            - type: boolean
              example: true
            - type: string
              example: 'true'
          example: true
        label:
          description: A user-friendly label for this field that can be used in UI forms.
          type: string
          example: First Name
        validation:
          description: Validation rule to apply to this field. Common validations include 'valid_email', 'valid_phone', etc.
          type:
            - string
            - 'null'
          example: valid_email
        options:
          description: For fields with predefined choices, this can be either an array of complex option objects, a simple array of string values, or null if no options are available.
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/RequirementFieldOption'
              minItems: 0
            - type: array
              items:
                type: string
              minItems: 0
              example:
                - English
                - French
            - type: 'null'
        required_when:
          description: For conditional fields, specifies when this field becomes required (e.g., when a parent option has a specific value).
          type:
            - string
            - 'null'
          example: FR
        fields:
          description: For complex fields or when options are selected, contains nested field definitions that become relevant.
          type:
            - object
            - 'null'
          additionalProperties:
            $ref: '#/components/schemas/RequirementField'
        value:
          description: For acknowledgement fields, this is the value that must be submitted when the user acknowledges the requirement.
          type:
            - string
            - 'null'
          example: accepted
    RequirementFieldOption:
      description: An option within a field that has predefined choices, including the option value, label, and any nested fields that become relevant when this option is selected.
      type: object
      required:
        - value
      properties:
        value:
          description: The actual value of this option. This is what must be submitted when this option is selected.
          type: string
          example: 'no'
        label:
          description: A user-friendly label for this option that can be displayed in UI forms.
          type: string
          example: I am an individual
        fields:
          description: When this option is selected, these nested fields become relevant and may be required. This allows for conditional field logic.
          type:
            - object
            - 'null'
          additionalProperties:
            $ref: '#/components/schemas/RequirementField'
          example:
            X-FR-BIRTHDATE:
              description: DOB in format yy/mm/dd
              type: string
              required: true
            X-FR-BIRTHPLACE:
              required: true
              description: Nation of Birth
              type: enum
              options:
                - FR
                - GB
                - USA
    ContactsRequirement:
      description: ContactsRequirement defines the registration requirements for contact fields for a specific TLD, including required fields, validation rules, and conditional logic. This follows the RequirementField structure with contact roles as nested fields.
      type: object
      required:
        - type
        - required
      properties:
        description:
          description: A detailed description of the contact requirements for this TLD, including eligibility criteria, restrictions, and important notes.
          type: string
          example: The contacts required to be submitted for registration
        type:
          description: The requirement type, which will be "string" for contacts.
          type: string
          example: string
        required:
          description: Whether contact information is mandatory for domain registration.
          oneOf:
            - type: boolean
              example: true
            - type: string
              example: 'true'
          example: true
        label:
          description: A user-friendly label for the contacts field.
          type: string
          example: contacts
        fields:
          description: An object containing contact roles (registrant, tech, admin, etc.) with their individual field requirements.
          type: object
          additionalProperties:
            type: object
            description: Contact role requirements (e.g., registrant, tech, admin)
            properties:
              description:
                description: Description of the contact role requirements.
                type: string
              type:
                description: The requirement type for this contact role.
                type: string
                example: string
              required:
                description: Whether this contact role is required.
                oneOf:
                  - type: boolean
                  - type: string
                example: true
              fields:
                description: Individual contact fields for this role, following RequirementField structure.
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/RequirementField'
    Requirement:
      description: Requirement defines the registration requirements for a specific TLD, including required fields, validation rules, and conditional logic.
      type: object
      properties:
        description:
          description: A detailed description of the registration requirements for this TLD, including eligibility criteria, restrictions, and important notes.
          type: string
          example: Required fields to register an .fr domain
        fields:
          description: An object containing all required and optional fields for domain registration, with their validation rules and conditional logic.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RequirementField'
    GetRequirementResponse:
      description: GetRequirementResponse has TLD Info and registration requirements for the specified TLD. The requirements field will always be present but may be an empty object when no specific requirements exist for the TLD.
      type: object
      properties:
        tldInfo:
          description: General information about a specific TLD. These are not registration requirements, but contain useful information for domain reseller and domain registrants in general.
          $ref: '#/components/schemas/ResellerTldInfo'
        contacts:
          description: |-
            The registration requirements for the contacts for this TLD, including required fields, validation rules, and conditional logic.  This field will always be present but may be an empty object when no specific requirements exist for the TLD.
            Only a few CC Tlds have specific contact requirements. These contacts must be submitted as part of the domain object when registering a domain, and not part of the `tldRequirements` parameter.
            Please check the contact requirements carefully, as different fields may be required for different roles, and there may be additional validation rules that must be followed.
          $ref: '#/components/schemas/ContactsRequirement'
        requirements:
          description: The registration requirements for this TLD, including required fields, validation rules, and conditional logic. This field will always be present but may be an empty object when no specific requirements exist for the TLD.
          $ref: '#/components/schemas/Requirement'
      required:
        - requirements
        - tldInfo
        - contacts
    DomainClaimsCheckRequest:
      type: object
      description: Request parameters for domain claims checking
      properties:
        purchaseType:
          type: string
          description: The type of purchase/registration for which to check claims. Defaults to 'registration'. Other values like 'landrush_eap', 'landrush_auction_a', 'landrush_reserve_a' may be used during new gTLD launches.
          default: registration
          enum:
            - registration
            - landrush_eap
            - landrush_auction_a
            - landrush_reserve_a
          example: registration
    TrademarkClaim:
      type: object
      description: Information about a specific trademark claim
      required:
        - trademark
        - holder
      properties:
        trademark:
          type: string
          description: The trademark text that matches the domain
          example: TikTok
        holder:
          type: string
          description: The entity that holds the trademark
          example: ByteDance Ltd.
        jurisdiction:
          type: string
          description: The jurisdiction where the trademark is registered
          example: US
        registrationNumber:
          type: string
          description: The trademark registration number
          example: US123456789
        description:
          type: string
          description: Additional description of the trademark
          example: Social media platform trademark
        noticeHtml:
          type: string
          description: HTML content to display about this specific trademark claim
          example: <div class='trademark-notice'>This domain may infringe on the TikTok trademark held by ByteDance Ltd.</div>
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Confidence score for the trademark match (0.0 to 1.0)
          example: 0.95
    DomainClaimsCheckResponse:
      type: object
      description: Response containing domain-specific claims data and trademark information
      required:
        - domain
        - claims
      properties:
        domain:
          type: string
          description: The domain name that was checked for claims
          example: tiktok.page
        claims:
          type: array
          description: List of trademark claims found against this domain
          items:
            $ref: '#/components/schemas/TrademarkClaim'
        claimsProcessActive:
          type: boolean
          description: Whether the TLD of this domain requires claims checking
          example: true
        claimId:
          type:
            - string
            - 'null'
          description: The claim identifier from TMCH (null if no claims found)
          example: 8c3027d30000000000382500785
        notBefore:
          type:
            - string
            - 'null'
          format: date-time
          description: The date before which the claim acknowledgment is not valid (null if no claims found)
          example: '2024-01-15T10:30:00Z'
        notAfter:
          type:
            - string
            - 'null'
          format: date-time
          description: The date after which the claim acknowledgment expires (null if no claims found)
          example: '2024-01-15T10:30:00Z'
        claimsNotice:
          type: string
          description: Markdown content to display about this specific trademark claim
          example: '**This domain may infringe on a trademark claim. Proceeding with registration acknowledges that you have received notice of this claim.**'
    TldPriceListEntry:
      description: |
        The pricing for an individual TLD.

        Please note that if `null` is returned for any of the prices, it means that particular product is unavailable at name.com.

        For example, if `registrationPrice` returns as `null` in the response, it means that name.com is not currently accepting registrations for that TLD.
      properties:
        tld:
          description: The TLD the pricing applies to. For IDN TLDs, this will be the unicode representation of the TLD.
          type: string
          example: com
        duration:
          description: The number of years this pricing is for
          type: integer
          format: int32
          example: 1
        registrationPrice:
          description: This is your account level price in US Dollars (USD) and is the price you pay for non-premium registrations. It includes applicable rebates, promotions and/or account-level discounts.
          type:
            - number
            - 'null'
          format: double
          example: 9.99
        registrationRetailPrice:
          description: This is the current retail price on name.com in US Dollars (USD) after including rebates, promotions and/or sales for registering non-premium domains.
          type:
            - number
            - 'null'
          format: double
          example: 10.99
        registrationOriginalPrice:
          description: This is name.com's suggested retail price (MSRP) in US Dollars (USD) before any discounts for registering non-premium domains.
          type:
            - number
            - 'null'
          format: double
          example: 11.99
        renewalPrice:
          description: This is your account level price in US Dollars (USD) and is the price you pay for non-premium renewals. It includes applicable rebates, promotions and/or account-level discounts.
          type:
            - number
            - 'null'
          format: double
          example: 9.99
        renewalRetailPrice:
          description: This is the current retail price on name.com in US Dollars (USD) after including rebates, promotions and/or sales for renewals of non-premium domains.
          type:
            - number
            - 'null'
          format: double
          example: 10.99
        renewalOriginalPrice:
          description: This is name.com's suggested retail price (MSRP) in US Dollars (USD) before any discounts for renewals of non-premium domains.
          type:
            - number
            - 'null'
          format: double
          example: 11.99
        domainRestorationPrice:
          description: This is your account level price in US Dollars (USD) and is the price you pay for non-premium restorations. It includes applicable rebates, promotions and/or account-level discounts.
          type:
            - number
            - 'null'
          format: double
          example: 120.99
        domainRestorationRetailPrice:
          description: This is the current retail price on name.com in US Dollars (USD) after including rebates, promotions and/or sales for restorations of non-premium domains.
          type:
            - number
            - 'null'
          format: double
          example: 130.99
        domainRestorationOriginalPrice:
          description: This is name.com's suggested retail price (MSRP) in US Dollars (USD) before any discounts for restoration of non-premium domains.
          type:
            - number
            - 'null'
          format: double
          example: 140.99
        transferInPrice:
          description: This is your account level price in US Dollars (USD) and is the price you pay for non-premium transfers. It includes applicable rebates, promotions and/or account-level discounts.
          type:
            - number
            - 'null'
          format: double
          example: 19.99
        transferInRetailPrice:
          description: This is the current retail price on name.com in US Dollars (USD) after including rebates, promotions and/or sales for transfers of non-premium domains.
          type:
            - number
            - 'null'
          format: double
          example: 20.99
        transferInOriginalPrice:
          description: This is name.com's suggested retail price (MSRP) in US Dollars (USD) before any discounts for transfer of non-premium domains.
          type:
            - number
            - 'null'
          format: double
          example: 21.99
      required:
        - tld
        - duration
        - registrationPrice
        - registrationRetailPrice
        - registrationOriginalPrice
        - renewalPrice
        - renewalRetailPrice
        - renewalOriginalPrice
        - domainRestorationPrice
        - domainRestorationRetailPrice
        - domainRestorationOriginalPrice
        - transferInPrice
        - transferInRetailPrice
        - transferInOriginalPrice
    TldPriceListResponse:
      properties:
        lastPage:
          description: LastPage is the identifier for the final page of results. It is only populated if there is another page of results after the current page.
          format: int32
          type: integer
        nextPage:
          description: NextPage is the identifier for the next page of results. It is only populated if there is another page of results after the current page.
          format: int32
          type:
            - integer
            - 'null'
        totalCount:
          description: TotalCount is total number of results.
          format: int32
          type: integer
        from:
          description: From specifies starting record number on current page.
          format: int32
          type: integer
        to:
          description: To specifies ending record number on current page.
          format: int32
          type: integer
        pricing:
          type: array
          items:
            $ref: '#/components/schemas/TldPriceListEntry'
      type: object
      required:
        - lastPage
        - nextPage
        - totalCount
        - from
        - to
        - pricing
    ZoneCheckRequest:
      description: ZoneCheck request checks DNS zone files for the availability of the specified domains.
      type: object
      properties:
        domainNames:
          description: |-
            Array of domain names to check. Each entry is normalized and validated before zone check runs. Entries that are not valid domain strings,  that use unsupported TLDs for this service, or that fail other pre-validation rules are omitted from the check; the response `removed` field  reports how many were omitted (not which values).

            **Valid domain string (after normalization)** — for reliable results and to avoid errors once all entries are removed:

            - **Allowed characters:** ASCII letters (`a`–`z`), digits (`0`–`9`), and hyphens (`-`).

            - **Hyphen rules:** A domain (the part between dots) must not start or end with a hyphen (for example, `-test.com` and `test-.com` are invalid).

            - **Domain length:** Each domain must be between 1 and 63 characters.

            - **Internationalized domains (IDNs):** Non-ASCII characters (for example `ö` or `ñ`) should be submitted as Punycode (`xn--...`) for  consistent registry resolution.
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
          maxItems: 500
          examples:
            - - example.com
              - example.net
              - example.org
            - - test.net
      required:
        - domainNames
    ZoneCheckResult:
      description: Result for checking and individual domain's presense in DNS zone files.
      type: object
      properties:
        domainName:
          description: The domain name that was checked
          type: string
          example: example.com
        available:
          description: If the domain is potentially available for purchase after checking for it's presense in the DNZ zone files.
          type:
            - boolean
            - 'null'
          examples:
            - true
            - false
            - null
      required:
        - domainName
        - available
    ZoneCheckResponse:
      description: Response for checking domain availability via DNS zone checks.
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ZoneCheckResult'
            minLength: 0
        total:
          description: Total number of records checked
          type: integer
          format: int32
          example: 5
        removed:
          description: Number of domain strings removed during pre-validation (invalid format, unsupported TLD for this service, etc.). This is a count only;  the response does not list which strings were removed.
          type: integer
          format: int32
          example: 1
      required:
        - results
        - total
    PremiumDomainsDownloadResponse:
      type: object
      properties:
        downloadUrl:
          type: string
          format: uri
          description: The pre-signed URL to use to download the list.
          example: https://name-ote-downloads/PremiumList_123456.zip
          readOnly: true
        expireDate:
          description: The timestamp that the URL will expire.
          type: string
          format: date-time
          example: '2025-09-04T16:45:00Z'
          readOnly: true
      required:
        - downloadUrl
        - expireDate
    UnverifiedContact:
      type: object
      description: The pertinent information used to identifiy a domain contact that requires verification as per ICANN requirements.
      properties:
        verificationId:
          description: The id of the verification record for the contact. Please note, this is different than the `contact_id` that may be returned in other API contexts. This id specifically relates to the verification record and will be different than a `contact_id` for the same contact record in other contexts.
          type: integer
          format: int64
          example: 4897668
        createDate:
          description: The date the record requiring verification was created.
          type: string
          format: date-time
          example: '2025-01-01T15:35:06Z'
          readOnly: true
        verifyBy:
          description: The date/time that the contact record **must** be verified by.  If the contact record is not verified by this date, the domain may become locked by the registry. This is typically 15 days from the creation date of the verification record, but may vary by TLD and registry.
          type: string
          format: date-time
          example: '2025-01-16T15:35:06Z'
          readOnly: true
        email:
          description: The email address of the contact to be verified. This is the primary identifier used for verification.
          type: string
          format: email
          example: admin@example.com
          readOnly: true
        domains:
          description: A list of the domains that the contact verification record is applied to.
          type: array
          items:
            type: string
            format: hostname
          minItems: 1
      required:
        - verificationId
        - createDate
        - verifyBy
        - email
        - domains
    UnverifiedContactsResponse:
      description: A list of unverified contacts that relate to your account.
      type: object
      properties:
        unverifiedContacts:
          type: array
          items:
            $ref: '#/components/schemas/UnverifiedContact'
        from:
          description: From is the starting record for the current page.
          type: integer
          format: int32
          example: 1
        to:
          description: To is the ending record for the current page.
          type: integer
          format: int32
          example: 25
        lastPage:
          description: LastPage is the identifier for the final page of results. This value will be null if there is not a previous result page.
          type: integer
          format: int32
        nextPage:
          description: NextPage is the identifier for the next page of results. This value will be null if there is not a next page of results.
          type:
            - integer
            - 'null'
          format: int32
        totalCount:
          description: TotalCount is total number of domains returned for request.
          type: integer
          format: int32
      required:
        - unverifiedContacts
        - from
        - to
        - lastPage
        - nextPage
        - totalCount
    ContactVerificationResendResponse:
      description: Response for resending a contact verification email.
      type: object
      properties:
        sent:
          type: boolean
          description: Whether a verification email was sent as a result of this request.
          example: true
        verificationId:
          type: integer
          format: int32
          description: The verificationId for the contact verification record.
          example: 98752463
        nextEligibleAt:
          type: string
          format: date-time
          description: When the client can attempt to resend again, as an RFC3339/ISO-8601 UTC timestamp. This field is always returned, including when throttling applies.
          example: '2026-01-14T12:15:00Z'
      required:
        - sent
        - verificationId
        - nextEligibleAt
    TldInfoJsonSchema:
      description: A JSON Schema Draft 7 definition for tldInfo that wraps ResellerTldInfo with readOnly metadata. This schema can be referenced in JSON Schema documents using $ref.
      type: object
      allOf:
        - $ref: '#/components/schemas/ResellerTldInfo'
      readOnly: true
    RequirementsJsonSchema:
      description: |-
        A JSON Schema Draft 7 document that describes the registration requirements for a TLD. This schema follows the JSON Schema Draft 7 specification (http://json-schema.org/draft-07/schema#) and can be used directly by form generation and validation libraries that consume JSON Schema.
        The schema structure includes: - A `tldInfo` property containing general TLD information (read-only, always present) - A `contacts` property containing contact field requirements (e.g., registrant, admin, tech) - A `tldRequirements` property containing TLD-specific registration fields
        The `contacts` and `tldRequirements` properties may be empty objects, while `tldInfo` will always contain data. The exact structure varies by TLD, as different TLDs have different registration requirements.
      type: object
      properties:
        $schema:
          description: The JSON Schema version identifier, should be "http://json-schema.org/draft-07/schema#"
          type: string
          example: http://json-schema.org/draft-07/schema#
        type:
          description: The JSON Schema type, typically "object" for requirement schemas
          type: string
          example: object
        title:
          description: A human-readable title for the schema
          type: string
          example: .it Domain Registration Requirements Schema
        description:
          description: A detailed description of the registration requirements
          type: string
          example: Registration requirements for .it domains
        properties:
          description: 'An object containing the schema properties. Includes: - `tldInfo`: An object containing general TLD information (read-only) - `contacts`: An object defining contact field requirements - `tldRequirements`: An object defining TLD-specific registration fields'
          type: object
          properties:
            tldInfo:
              description: 'General information about a TLD and it''s various requirements. This is not a comprehensive list of all information related to a TLD.  The structure matches ResellerTldInfo schema. In JSON Schema document examples, this property will contain a schema definition object  with `allOf` referencing ResellerTldInfo and `readOnly: true`.'
              allOf:
                - $ref: '#/components/schemas/TldInfoJsonSchema'
            contacts:
              description: An object defining contact field requirements. May be an empty object if no contact requirements exist for the TLD.
              type: object
              additionalProperties: true
            tldRequirements:
              description: An object defining TLD-specific registration fields. May be an empty object if no TLD-specific requirements exist.
              type: object
              additionalProperties: true
          additionalProperties: false
        required:
          description: An array of required property names
          type: array
          items:
            type: string
          example:
            - tldInfo
            - contacts
            - tldRequirements
        allOf:
          description: An array of schema objects that must all be valid. Used for conditional validation with multiple conditions.
          type: array
          items:
            type: object
            additionalProperties: true
        if:
          description: The condition schema for conditional validation. When this condition is true, the 'then' schema applies.
          type:
            - object
            - 'null'
          additionalProperties: true
        then:
          description: The schema to apply when the 'if' condition is true.
          type:
            - object
            - 'null'
          additionalProperties: true
        else:
          description: The schema to apply when the 'if' condition is false (optional).
          type:
            - object
            - 'null'
          additionalProperties: true
      example:
        $schema: http://json-schema.org/draft-07/schema#
        type: object
        title: .it Domain Registration Requirements Schema
        description: Registration requirements for .it domains
        properties:
          tldInfo:
            tld: .it
            ccTld: true
            supportsTransferLock: true
            supportsDnssec: true
            supportsPremium: false
            supportsPrivacy: false
            supportsInternalTransfer: true
            requiresPreDelegation: false
            expirationGracePeriod: 25
            allowedRegistrationYears:
              - 1
              - 3
              - 5
              - 8
              - 10
            idnLanguages:
              IT: Italian
            hsts: false
            minDomainLength: 3
            minIdnDomainLength: 5
            registryOperator: nic.it
            claimsCheckRequired: []
            requireIdnSld: false
            readOnly: true
          contacts:
            type: object
            properties:
              registrant:
                type: object
                properties:
                  firstName:
                    type: string
                    title: First Name
                    description: First name of registrant contact
                  email:
                    type: string
                    format: email
                    title: Email
                    description: Email address of registrant contact
                required:
                  - firstName
                  - email
            required:
              - registrant
          tldRequirements:
            type: object
            properties:
              X-IT-ENTITY-TYPE:
                type: string
                title: Registrant Entity Type
                enum:
                  - '1'
                  - '2'
                  - '3'
                  - '4'
                  - '5'
                  - '6'
                  - '7'
              X-IT-PIN:
                type: string
                title: .IT PIN number
                description: 16 alphanumeric characters (tax code) for natural persons or 11 digits (VAT number) for organizations
        required:
          - tldInfo
          - contacts
          - tldRequirements
    AccountCreditBalanceChange:
      type: object
      properties:
        eventName:
          type: string
          enum:
            - account.credit.balance_change
          description: The name of the subscription event
        accountId:
          type: integer
          format: int64
          description: The account ID the subscription is for
        balance:
          type: number
          format: double
          description: The remaining balance of account credit
    AccountDomainRemoval:
      type: object
      required:
        - eventName
        - domainName
        - reason
        - expireDate
      description: Payload sent when a domain is removed from the subscribing account.
      properties:
        eventName:
          type: string
          enum:
            - account.domain.removal
          description: The name of the subscription event
        domainName:
          type: string
          description: The name of the domain that was removed
          example: example.com
        reason:
          type: string
          description: 'Why the domain left inventory: `expiration` (registry delete / post-expiry inventory loss), `agp_refund` (AGP refund delete), or `administrative` (ops/support removal).'
          enum:
            - expiration
            - agp_refund
            - administrative
          example: expiration
        expireDate:
          type: string
          format: date-time
          description: The date and time when the domain expired
          example: '2026-08-15T00:00:00Z'
    DomainLockStatusChange:
      type: object
      required:
        - eventName
        - domainName
        - action
        - lockType
        - registryStatuses
      properties:
        eventName:
          type: string
          enum:
            - domain.lock.status_change
        domainName:
          type: string
          description: Fully-qualified domain name
          example: example.org
        action:
          type: string
          enum:
            - added
            - removed
        lockType:
          type: string
          description: The lock type affected by this event (added or removed)
          enum:
            - RegistrarLock
            - TransferLock
            - AccountLock
            - ClientHold
            - VerificationClientHold
            - VerificationHold
            - PrivacyLock
            - ExpirationClientHold
        registryStatuses:
          type: array
          description: Current registry statuses after the change
          items:
            type: string
          example:
            - clientHold
            - clientTransferProhibited
            - clientUpdateProhibited
    DomainTransferStatusChange:
      type: object
      description: |
        Payload sent when a domain transfer IN to name.com is processing. This schema represents transfer-in events where name.com is the gaining registrar.
      properties:
        eventName:
          type: string
          enum:
            - domain.transfer.status_change
          description: The name of the subscription event
        domainName:
          type: string
          description: The domain that the transfer status has changed for
          example: example.com
        status:
          $ref: '#/components/schemas/TransferStatus'
        warning:
          type: string
          description: Included only when `status` is `completed` and one or more submitted contacts could not be applied and were replaced by account default contacts.  Omitted otherwise.
          example: One or more submitted contacts could not be applied and were replaced with the account default contacts. Call Set Contacts to update them with the end-user contacts.
      required:
        - eventName
        - domainName
        - status
    DomainTransferOutStatusChange:
      type: object
      description: Payload for `domain.transfer_out.status_change`. `completed` means the domain left name.com. `canceled` means the outbound transfer is no longer pending at the registry.
      required:
        - eventName
        - domainName
        - status
      properties:
        eventName:
          type: string
          enum:
            - domain.transfer_out.status_change
          description: The name of the subscription event.
        domainName:
          type: string
          description: The domain whose outbound transfer status changed. For `completed`, the domain has left name.com; for `initiated` and `canceled`, it remains on the losing account.
          example: example.com
        status:
          type: string
          description: '`initiated` (pending out started), `completed` (domain removed), or `canceled` (no longer pending at the registry).'
          enum:
            - initiated
            - completed
            - canceled
          example: completed
        registryClientId:
          type:
            - string
            - 'null'
          description: |
            The registry client ID associated with the domain at the time of transfer out, when available. This can help identify the gaining registrar at the registry.
          example: NAMECOM-123
    ContactVerificationStatusChange:
      type: object
      required:
        - eventName
        - domains
        - verificationId
        - verification
      properties:
        eventName:
          type: string
          enum:
            - contact.verification.status_change
        domains:
          type: array
          items:
            type: string
        verificationId:
          description: The id of the verification record for the contact. Please note, this is different than the `contact_id` that may be returned in other API contexts. This id specifically relates to the verification and will be different than an `contact_id` for the same contact record in other contexts.
          type: integer
          format: int64
          example: 4897668
        verification:
          discriminator:
            propertyName: status
          oneOf:
            - type: object
              required:
                - status
              properties:
                status:
                  type: string
                  enum:
                    - verified
            - type: object
              required:
                - status
                - verifyBy
              properties:
                status:
                  type: string
                  enum:
                    - unverified
                verifyBy:
                  description: The date when the contact should be verified by.
                  type: string
                  format: date-time
                  example: '2023-04-01T12:00:00Z'
    DomainTransferInternalInStatusChange:
      type: object
      required:
        - eventName
        - sourceAccountId
        - destinationAccountId
        - status
        - occurredAt
        - domain
      description: Payload sent when a domain transfers IN to the webhook subscribers account from another name.com account.
      properties:
        eventName:
          type: string
          enum:
            - domain.transfer.internal_in
          description: The name of the subscription event.
        sourceAccountId:
          description: The account id that previously owned the domain.
          format: int32
          type: integer
          example: 12345
        destinationAccountId:
          description: The account id that now owns the domain.
          format: int32
          type: integer
          example: 12345
        status:
          type: string
          enum:
            - completed
        occurredAt:
          description: When the domain transfer in occurred.
          type: string
          format: date-time
          example: '2023-04-01T12:00:00Z'
        domain:
          $ref: '#/components/schemas/DomainResponsePayload'
    DomainTransferInternalOutStatusChange:
      type: object
      required:
        - eventName
        - sourceAccountId
        - destinationAccountId
        - status
        - occurredAt
        - domain
      description: Payload sent when a domain transfers OUT from the webhook subscriber's account to another name.com account.
      properties:
        eventName:
          type: string
          enum:
            - domain.transfer.internal_out
          description: The name of the subscription event.
        transferId:
          description: The internal transfer ID for this move, when available. Omitted when no transfer ID has been assigned for the event.
          format: int32
          type: integer
          example: 67890
        sourceAccountId:
          description: The account id that previously owned the domain (the losing account).
          format: int32
          type: integer
          example: 12345
        destinationAccountId:
          description: The account id that now owns the domain (the gaining account).
          format: int32
          type: integer
          example: 54321
        status:
          type: string
          enum:
            - completed
        occurredAt:
          description: When the domain transfer out occurred.
          type: string
          format: date-time
          example: '2023-04-01T12:00:00Z'
        domain:
          $ref: '#/components/schemas/DomainResponsePayload'
    DomainRegistryRejection:
      type: object
      required:
        - eventName
        - domainName
        - occurredAt
        - orderId
        - orderItemId
      description: Payload sent when a domain create request fails after asynchronous registry processing. Most domain creates succeed immediately; this event covers the case where the registry initially accepts processing but later rejects or fails the registration.
      properties:
        eventName:
          type: string
          enum:
            - domain.registry.rejection
          description: The name of the subscription event.
        domainName:
          type: string
          description: The domain name that failed to register.
          example: example.com
        orderId:
          type: integer
          format: int32
          description: The unique identifier of the order for the failed domain create. Use the List Orders endpoint to retrieve order details.
          example: 123456
        orderItemId:
          type: integer
          format: int32
          description: The unique identifier of the order line item for the failed domain create. Use the List Orders endpoint to retrieve order item details.
          example: 987654
        occurredAt:
          description: When the asynchronous registration failure was recorded.
          type: string
          format: date-time
          example: '2023-04-01T12:00:00Z'
        reason:
          type: string
          description: Optional human-readable or registry-provided detail about the failure, when available.
          example: Registry policy violation
    DomainRegistryComplianceNotice:
      type: object
      required:
        - eventName
        - domainName
        - policy
        - policyName
        - policyUrl
        - registryName
        - issueDescription
        - remediationInstructions
        - agreementReminder
        - noncomplianceConsequences
        - contactInstructions
        - complianceDeadline
        - remediationPeriodDays
      description: Payload sent when a registry reports that a domain must remediate a policy compliance issue before a deadline. By default, name.com emails the registrant; subscribing replaces that email so you can notify the end user from these fields. If you have signed an addendum to assume all email responsibility, name.com does not send the email and this webhook is the only delivery path. Whitelabeled branding is applied to the email when your account has it configured.
      properties:
        eventName:
          type: string
          enum:
            - domain.registry.compliance_notice
          description: The name of the subscription event.
        domainName:
          type: string
          description: The domain subject to the registry compliance notice.
          example: example.new
        policy:
          type: string
          enum:
            - new_resolves_within_100_days
            - new_used_for_action
            - new_account_for_review
          description: Stable, namespaced identifier for the registry policy requiring remediation. Branch on this value rather than any human-readable field.
        policyName:
          type: string
          description: Human-readable name of the registration policy associated with the compliance requirement.
          example: .NEW Domain Registration Policy
        policyUrl:
          type: string
          format: uri
          description: URL of the registration policy associated with the compliance requirement.
          example: https://www.registry.google/policies/registration/new/#!/
        registryName:
          type: string
          description: Human-readable name of the registry that issued the compliance notice.
          example: Example Registry
        registryEmail:
          type: string
          format: email
          description: Registry mailbox for evidence and questions, when the registry publishes one. Include it in the message body when notifying the registrant. Omitted when the registry does not publish a contact address.
          example: compliance@registry.example
        originalMessageId:
          type: string
          description: RFC 5322 Message-ID of the registry's original notice, when available. Omitted when the registry notice had no Message-ID.
          example: <notice-12345@registry.example>
        issueDescription:
          type: string
          description: Human-readable explanation of the compliance issue identified by the registry. Suitable for forwarding to the registrant. The wording may change; do not branch on this text.
          example: The registry determined that the domain does not resolve to an action within 100 days of registration.
        remediationInstructions:
          type: string
          description: Human-readable instructions for resolving the compliance issue. Suitable for forwarding to the registrant. The wording may change; do not branch on this text.
          example: Configure the domain to launch an online creation or action-generation flow, and ensure the website is accessible using an active SSL certificate.
        agreementReminder:
          type: string
          description: Human-readable reminder that the registrant agreed to the applicable registration policy. Suitable for forwarding to the registrant. The wording may change; do not branch on this text.
          example: As a reminder, when you registered this domain, you agreed to the .NEW Domain Registration Policy, which includes this requirement.
        noncomplianceConsequences:
          type: string
          description: Human-readable explanation of what the registry may do if the issue is not remediated by `complianceDeadline`. Suitable for forwarding to the registrant.
          example: If the website is still not compliant by the deadline, the registry may suspend or cancel the domain. Suspended domains do not resolve and cannot be transferred or deleted.
        contactInstructions:
          type: string
          description: Human-readable instruction for the registrant to contact the registry (not the registrar) if they believe the domain is compliant or need to submit evidence. Suitable for forwarding.
          example: If you believe the domain is compliant or need to submit evidence, contact the registry.
        complianceDeadline:
          type: string
          format: date-time
          description: The deadline by which the compliance issue must be remediated.
          example: '2026-10-25T15:30:00+00:00'
        remediationPeriodDays:
          type: integer
          minimum: 0
          description: The remediation period supplied by the registry, in days.
          example: 45
    DomainExpiration:
      type: object
      required:
        - eventName
        - domainName
        - expirationDate
      description: Payload sent when a domain in the subscribing account expires and the grace period starts. This event is informational; it is separate from lock, removal, and transfer-out events.
      properties:
        eventName:
          type: string
          enum:
            - domain.expiration
          description: The name of the subscription event.
        domainName:
          type: string
          description: The name of the expired domain.
          example: example.com
        expirationDate:
          type: string
          format: date-time
          description: The date and time when the domain expired.
          example: '2026-08-15T00:00:00Z'