domainee-dev Domain purchases API

openapi: 3.2.0
info:
  title: Domainee Domain purchases API
  version: 1.0.0
  summary: Custom domains, domain registration, and DNS diagnostics for SaaS products.
  description: 'Domainee lets your product attach your customers'' own domains to their accounts:

    one call to connect a hostname, automatic SSL issuance and renewal, DNS health

    monitoring, webhooks, and domain registration across 500+ TLDs.


    ## Authentication


    Every `/v1` endpoint except `/v1/tools/*` takes a Bearer token in the

    `Authorization` header. Two kinds work interchangeably:


    - **API keys** (`sk_live_…`), created at https://domainee.dev/developers

    - **OAuth access tokens** (`dmn_oat_…`), issued by the flow described in

    the `/.well-known/oauth-authorization-server` document.


    Both are workspace-scoped: a token only ever sees its own workspace''s data.


    ## Rate limits


    Authenticated endpoints allow 60 requests per minute per key and answer `429`

    with `{"error":"rate_limited"}` beyond that. The free tools are limited per IP

    at 30/minute and 500/day.


    ## Idempotency


    Send an `Idempotency-Key` header on any POST to make a retry safe: the first

    response for a given key is replayed instead of performing the work twice.


    ## Errors


    Failures return the same envelope at every status code:

    `{ "error": "not_found", "message": "Domain not found" }`.


    Full guides: https://domainee.dev/docs. Machine-readable index: https://domainee.dev/llms.txt.'
  termsOfService: https://domainee.dev/terms
  contact:
    name: Domainee support
    email: hello@domainee.dev
    url: https://domainee.dev/contact
servers:
- url: https://api.domainee.dev
  description: Production
security:
- bearerAuth: []
tags:
- name: Domain purchases
  description: Search, register, renew, and manage domains bought through Domainee.
paths:
  /v1/domain-purchases/check:
    get:
      operationId: checkDomainAvailability
      summary: Check availability and price before buying
      description: Read-only and free. Nothing is charged and nothing is reserved.
      tags:
      - Domain purchases
      parameters:
      - name: hostname
        in: query
        required: true
        description: Registrable domain to quote, e.g. `acme.com`.
        schema:
          type: string
          example: acme.com
      responses:
        '200':
          description: Availability and the all-in price.
          content:
            application/json:
              schema:
                type: object
                properties:
                  hostname:
                    type: string
                  available:
                    type: boolean
                  totalCents:
                    type: integer
                    description: What POST /v1/domain-purchases would charge for one year.
                  currency:
                    type: string
                    enum:
                    - USD
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/domain-purchases:
    get:
      operationId: listDomainPurchases
      summary: List domain purchases
      tags:
      - Domain purchases
      parameters:
      - name: hostname
        in: query
        required: false
        schema:
          type: string
        description: Exact-match filter.
      - name: status
        in: query
        required: false
        description: Repeat the parameter to filter on several statuses.
        schema:
          type: array
          items:
            type: string
            enum:
            - pending
            - completed
            - failed
            - refunded
        explode: true
      - name: customerReference
        in: query
        required: false
        schema:
          type: string
        description: Whatever you stashed at buy time.
      - name: createdAfter
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Inclusive ISO date.
      - name: createdBefore
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Inclusive ISO date.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      responses:
        '200':
          description: A page of purchases.
          content:
            application/json:
              schema:
                type: object
                properties:
                  purchases:
                    type: array
                    items:
                      $ref: '#/components/schemas/DomainPurchase'
                  nextCursor:
                    type:
                    - string
                    - 'null'
                required:
                - purchases
                - nextCursor
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: purchaseDomain
      summary: Register a domain
      description: 'Charges the workspace and registers the domain in one call. If the registrar

        refuses after the charge clears, the charge is refunded automatically and the

        purchase comes back `failed`.


        Send `maxTotalCents` to refuse the purchase if the price moved since your quote,

        and `autoConnect` to attach the new domain to an origin without a second call.

        Send an `Idempotency-Key` — this endpoint moves money.'
      tags:
      - Domain purchases
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                hostname:
                  type: string
                  minLength: 3
                  maxLength: 253
                  example: acme.com
                years:
                  type: integer
                  minimum: 1
                  maximum: 10
                  default: 1
                registrant:
                  $ref: '#/components/schemas/Registrant'
                enableWhoisPrivacy:
                  type: boolean
                  description: Rejected with a 400 on TLDs that do not support it.
                autoRenew:
                  type: boolean
                maxTotalCents:
                  type: integer
                  minimum: 1
                  description: Abort with `price_changed` if the total would exceed this.
                customerReference:
                  type: string
                  maxLength: 256
                autoConnect:
                  type: object
                  description: Connect the domain to an origin as soon as it registers.
                  properties:
                    originUrl:
                      type: string
                      format: uri
                    keepHost:
                      type: boolean
                  required:
                  - originUrl
              required:
              - hostname
              - registrant
      responses:
        '201':
          $ref: '#/components/responses/PurchaseEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/BillingRequired'
        '409':
          description: '`unavailable` — the domain was taken; `price_changed` — the total exceeded `maxTotalCents`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: The registrar rejected the registration. Any charge was refunded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/domain-purchases/{id}:
    parameters:
    - $ref: '#/components/parameters/PurchaseId'
    get:
      operationId: getDomainPurchase
      summary: Retrieve one purchase
      tags:
      - Domain purchases
      responses:
        '200':
          $ref: '#/components/responses/PurchaseEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: setDomainPurchaseAutoRenew
      summary: Turn auto-renew on or off
      description: 'Setting `autoRenew` to false is how you cancel: the domain simply lapses at `expiresAt`.'
      tags:
      - Domain purchases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                autoRenew:
                  type: boolean
              required:
              - autoRenew
      responses:
        '200':
          $ref: '#/components/responses/PurchaseEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/domain-purchases/{id}/details:
    parameters:
    - $ref: '#/components/parameters/PurchaseId'
    get:
      operationId: getDomainPurchaseDetails
      summary: Retrieve a purchase with live registrar state
      description: Hits the registrar, so it is slower than `getDomainPurchase`. Use it when you need the authoritative expiry, lock, or nameserver state.
      tags:
      - Domain purchases
      responses:
        '200':
          description: The stored purchase plus what the registrar reports right now.
          content:
            application/json:
              schema:
                type: object
                properties:
                  purchase:
                    $ref: '#/components/schemas/DomainPurchase'
                  live:
                    type: object
                    additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/domain-purchases/{id}/dns:
    parameters:
    - $ref: '#/components/parameters/PurchaseId'
    get:
      operationId: listDomainPurchaseDnsRecords
      summary: List the registrar DNS records for a purchased domain
      tags:
      - Domain purchases
      responses:
        '200':
          $ref: '#/components/responses/RegistrarDnsEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: replaceDomainPurchaseDnsRecords
      summary: Replace the registrar DNS records
      description: 'Declarative: the set you send becomes the complete record set. Omitting a record deletes it.'
      tags:
      - Domain purchases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                records:
                  type: array
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/RegistrarDnsRecord'
              required:
              - records
      responses:
        '200':
          $ref: '#/components/responses/RegistrarDnsEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/domain-purchases/{id}/nameservers:
    parameters:
    - $ref: '#/components/parameters/PurchaseId'
    put:
      operationId: setDomainPurchaseNameservers
      summary: Point a purchased domain at custom nameservers
      description: Delegating away from the registrar's nameservers makes the DNS-record endpoints inoperative for that domain.
      tags:
      - Domain purchases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                nameservers:
                  type: array
                  maxItems: 13
                  items:
                    type: string
                    minLength: 1
                    maxLength: 253
                  example:
                  - ns1.cloudflare.com
                  - ns2.cloudflare.com
              required:
              - nameservers
      responses:
        '200':
          description: The nameservers now on file.
          content:
            application/json:
              schema:
                type: object
                properties:
                  hostname:
                    type: string
                  nameservers:
                    type: array
                    items:
                      type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/domain-purchases/{id}/renew:
    parameters:
    - $ref: '#/components/parameters/PurchaseId'
    post:
      operationId: renewDomainPurchase
      summary: Extend a registration
      description: Charges the workspace and pushes `expiresAt` out by `years`.
      tags:
      - Domain purchases
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                years:
                  type: integer
                  minimum: 1
                  maximum: 10
              required:
              - years
      responses:
        '200':
          $ref: '#/components/responses/PurchaseEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/BillingRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The purchase is not in a renewable state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: The registrar refused the renewal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/domain-purchases/{id}/connect:
    parameters:
    - $ref: '#/components/parameters/PurchaseId'
    post:
      operationId: connectDomainPurchase
      summary: Connect a purchased domain to an origin
      description: 'Provisions the domain on Domainee''s edge and writes the DNS records at the registrar in one call. No manual DNS step, because Domainee controls both sides. The DNS write is a merge: it replaces only the routing records at the apex and www, and leaves MX, TXT, SPF, DKIM, DMARC, CAA and subdomain records in place.'
      tags:
      - Domain purchases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                originUrl:
                  type: string
                  format: uri
                keepHost:
                  type: boolean
              required:
              - originUrl
      responses:
        '200':
          $ref: '#/components/responses/PurchaseEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The purchase is not in a connectable state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/domain-purchases/{id}/auth-code:
    parameters:
    - $ref: '#/components/parameters/PurchaseId'
    get:
      operationId: getDomainPurchaseAuthCode
      summary: Get the EPP transfer code
      description: The code a customer needs to move the domain to another registrar.
      tags:
      - Domain purchases
      responses:
        '200':
          description: The transfer authorization code.
          content:
            application/json:
              schema:
                type: object
                properties:
                  hostname:
                    type: string
                  authCode:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: No such object in this workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BillingRequired:
      description: The workspace has no active subscription or the charge failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, malformed, revoked, or expired Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PurchaseEnvelope:
      description: The purchase.
      content:
        application/json:
          schema:
            type: object
            properties:
              purchase:
                $ref: '#/components/schemas/DomainPurchase'
            required:
            - purchase
    RegistrarDnsEnvelope:
      description: The records currently held at the registrar.
      content:
        application/json:
          schema:
            type: object
            properties:
              hostname:
                type: string
              records:
                type: array
                items:
                  $ref: '#/components/schemas/RegistrarDnsRecord'
            required:
            - hostname
            - records
    BadRequest:
      description: The request body or query failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    PurchaseId:
      name: id
      in: path
      required: true
      description: Purchase identifier returned by `purchaseDomain`.
      schema:
        type: string
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: Any unique string. Retrying with the same key replays the first response instead of repeating the work.
      schema:
        type: string
  schemas:
    Registrant:
      type: object
      description: ICANN-required owner contact. Sent to the registrar verbatim.
      properties:
        firstName:
          type: string
          minLength: 1
          maxLength: 64
        lastName:
          type: string
          minLength: 1
          maxLength: 64
        email:
          type: string
          format: email
        phone:
          type: string
          pattern: ^\+\d{1,3}\.\d{4,15}$
          description: E.164 with a dot after the country code.
          example: '+1.5551234567'
        address1:
          type: string
          minLength: 1
          maxLength: 128
        address2:
          type: string
          maxLength: 128
        city:
          type: string
          minLength: 1
          maxLength: 64
        stateOrProvince:
          type: string
          minLength: 1
          maxLength: 64
        postalCode:
          type: string
          minLength: 1
          maxLength: 20
        country:
          type: string
          minLength: 2
          maxLength: 2
          description: ISO 3166-1 alpha-2.
        organization:
          type: string
          maxLength: 128
      required:
      - firstName
      - lastName
      - email
      - phone
      - address1
      - city
      - stateOrProvince
      - postalCode
      - country
    DomainPurchase:
      type: object
      description: A domain registered through Domainee on the customer's behalf.
      properties:
        id:
          type: string
        workspaceId:
          type: string
        hostname:
          type: string
          example: acme.com
        years:
          type: integer
          minimum: 1
          maximum: 10
        wholesaleCents:
          type: integer
          description: Registrar cost at purchase time.
        feeCents:
          type: integer
          description: Domainee's per-purchase fee.
        totalCents:
          type: integer
          description: What the workspace was charged.
        currency:
          type: string
          enum:
          - USD
        registrar:
          type: string
          enum:
          - namecheap
        registrarDomainId:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - pending
          - completed
          - failed
          - refunded
          description: '`pending` means the charge cleared but the registration is not confirmed yet; a failed registration is refunded automatically.'
        errorMessage:
          type:
          - string
          - 'null'
        registrant:
          type: object
          description: Minimal owner snapshot. The registrar remains the source of truth.
          properties:
            firstName:
              type: string
            lastName:
              type: string
            email:
              type: string
              format: email
            country:
              type: string
              description: ISO 3166-1 alpha-2.
        whoisPrivacyEnabled:
          type: boolean
        autoRenew:
          type: boolean
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
        connectedDomainId:
          type:
          - string
          - 'null'
          description: Set when the purchase was auto-connected to a /v1/domains entry.
        customerReference:
          type:
          - string
          - 'null'
          description: Opaque caller-supplied reference, echoed on reads and webhooks.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - workspaceId
      - hostname
      - years
      - status
      - createdAt
    RegistrarDnsRecord:
      type: object
      description: A DNS record held at the registrar for a purchased domain.
      properties:
        type:
          type: string
          enum:
          - A
          - AAAA
          - CNAME
          - MX
          - TXT
          - NS
          - SRV
          - URL
          - URL301
          - FRAME
        name:
          type: string
          maxLength: 255
          description: Subdomain label; `@` for the apex.
          example: '@'
        value:
          type: string
          maxLength: 2048
        ttl:
          type: integer
          minimum: 60
          maximum: 86400
        priority:
          type: integer
          minimum: 0
          maximum: 65535
          description: MX/SRV only.
      required:
      - type
      - name
      - value
    Error:
      type: object
      description: The error envelope used by every authenticated endpoint.
      properties:
        error:
          type: string
          description: Stable machine-readable code.
          example: not_found
        message:
          type: string
          description: Human-readable explanation.
      required:
      - error
      - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (`sk_live_…`) from https://domainee.dev/developers or an OAuth access token (`dmn_oat_…`). Both are workspace-scoped.
externalDocs:
  description: Domainee documentation
  url: https://domainee.dev/docs