domainee-dev DNS API

openapi: 3.2.0
info:
  title: Domainee DNS 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: DNS
  description: Verify that DNS records resolve to the expected values.
paths:
  /v1/dns/check-records-exist:
    post:
      operationId: checkDnsRecordsExist
      summary: Check that at least one record matches the expected value
      description: Resolves each name live and reports whether the expected value is among the answers. Use this for records that legitimately have siblings, such as TXT or MX.
      tags:
      - DNS
      requestBody:
        $ref: '#/components/requestBodies/DnsCheck'
      responses:
        '200':
          $ref: '#/components/responses/DnsCheckResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/dns/check-records-match-exactly:
    post:
      operationId: checkDnsRecordsMatchExactly
      summary: Check that every record for a name equals the expected value
      description: 'Stricter than `checkDnsRecordsExist`: a stale extra A record fails the check. Use this for records that must be unique, such as a CNAME.'
      tags:
      - DNS
      requestBody:
        $ref: '#/components/requestBodies/DnsCheck'
      responses:
        '200':
          $ref: '#/components/responses/DnsCheckResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    DnsCheckResult:
      description: One result per submitted record, in the order they were sent.
      content:
        application/json:
          schema:
            type: object
            properties:
              records:
                type: array
                items:
                  type: object
                  properties:
                    address:
                      type: string
                    type:
                      type: string
                    match_against:
                      type: string
                    match:
                      type: boolean
                      description: Whether the check passed.
                    actual_values:
                      type: array
                      items:
                        type: string
                      description: What actually resolved. Empty when the lookup failed.
                  required:
                  - address
                  - type
                  - match_against
                  - match
                  - actual_values
            required:
            - records
    Unauthorized:
      description: Missing, malformed, revoked, or expired Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request body or query failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  requestBodies:
    DnsCheck:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              records:
                type: array
                minItems: 1
                maxItems: 50
                items:
                  type: object
                  properties:
                    address:
                      type: string
                      description: The name to resolve.
                      example: app.acme.com
                    type:
                      type: string
                      enum:
                      - a
                      - aaaa
                      - cname
                      - mx
                      - txt
                      - ns
                      - caa
                    match_against:
                      type: string
                      description: The value you expect. Compared case-insensitively, trailing dot ignored.
                      example: edge.domainee.dev
                  required:
                  - address
                  - type
                  - match_against
            required:
            - records
  schemas:
    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