openapi: 3.0.3
info:
  title: Rackspace Cloud DNS API
  version: '1.0'
  description: >-
    The Rackspace Cloud DNS API (v1.0) provides programmatic management of DNS
    zones and records hosted on the Rackspace Cloud. Operations include
    listing, creating, updating, importing, exporting, and cloning domains,
    plus full CRUD on standard DNS records and reverse DNS PTR records, with
    support for paginated listings, asynchronous job tracking, and per-account
    usage limits.
  contact:
    name: Rackspace Technology
    url: https://www.rackspace.com/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  x-generated-from: documentation
  x-source-url: https://github.com/rackerlabs/docs-cloud-dns
  x-last-validated: '2026-05-05'
servers:
  - url: https://dns.api.rackspacecloud.com/v1.0
    description: Rackspace Cloud DNS production endpoint
security:
  - AuthToken: []
tags:
  - name: Domains
    description: DNS domain (zone) operations.
  - name: Records
    description: DNS record operations within a domain.
  - name: ReverseDNS
    description: Reverse DNS (PTR) record operations.
  - name: Limits
    description: Per-account usage limits and rate caps.
paths:
  /{account}/limits:
    parameters:
      - $ref: '#/components/parameters/AccountId'
    get:
      operationId: listLimits
      summary: List Limits
      description: Provides a list of all applicable limits (rate and absolute) for the specified account.
      tags: [Limits]
      responses:
        '200':
          description: Limits returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Limits'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/limits/types:
    parameters:
      - $ref: '#/components/parameters/AccountId'
    get:
      operationId: listLimitTypes
      summary: List Limit Types
      description: Returns the list of limit types (rate and absolute) supported by the DNS service for this account.
      tags: [Limits]
      responses:
        '200':
          description: Limit types returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitTypes'
        '401': { $ref: '#/components/responses/Unauthorized' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/limits/{type}:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: type
        required: true
        description: The specific limit type to retrieve (for example, RATE_LIMIT or DOMAIN_LIMIT).
        schema: { type: string }
    get:
      operationId: showLimit
      summary: Show Limit
      description: Retrieves details for a single named limit type.
      tags: [Limits]
      responses:
        '200':
          description: Limit details returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Limit'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/domains:
    parameters:
      - $ref: '#/components/parameters/AccountId'
    get:
      operationId: listDomains
      summary: List Domains
      description: >-
        Lists all DNS domains manageable by the specified account. The
        resulting list is flat (subdomains are not nested) and returns by
        default a maximum of 100 items per page; navigate using the limit and
        offset query parameters.
      tags: [Domains]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - in: query
          name: name
          required: false
          description: Filter the listing to domains whose name starts with this string.
          schema: { type: string }
      responses:
        '200':
          description: Domains list returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainList'
              example:
                domains:
                  - id: '2725233'
                    name: example.com
                    accountId: '1234'
                    emailAddress: sample@rackspace.com
                    comment: Optional domain comment.
                    created: '2011-06-24T01:12:51.000+0000'
                    updated: '2011-06-24T01:23:15.000+0000'
                totalEntries: 1
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '413': { $ref: '#/components/responses/OverLimit' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createDomains
      summary: Create Domains
      description: >-
        Creates one or more DNS domains under the specified account. Returns an
        asynchronous 202 response containing a callback URL that can be polled
        for completion status.
      tags: [Domains]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDomainsRequest'
      responses:
        '202': { $ref: '#/components/responses/AsyncJobAccepted' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateDomains
      summary: Update Domains
      description: Updates one or more existing DNS domains under the account.
      tags: [Domains]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDomainsRequest'
      responses:
        '202': { $ref: '#/components/responses/AsyncJobAccepted' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteDomains
      summary: Delete Domains
      description: Deletes one or more DNS domains by ID.
      tags: [Domains]
      parameters:
        - in: query
          name: id
          required: true
          description: One or more domain IDs to delete.
          schema:
            type: array
            items: { type: string }
          style: form
          explode: true
      responses:
        '202': { $ref: '#/components/responses/AsyncJobAccepted' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/domains/search:
    parameters:
      - $ref: '#/components/parameters/AccountId'
    get:
      operationId: searchDomains
      summary: Search Domains
      description: Searches the account's domains by name fragment.
      tags: [Domains]
      parameters:
        - in: query
          name: name
          required: true
          description: Substring of the domain name to match.
          schema: { type: string }
      responses:
        '200':
          description: Matching domains returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/domains/import:
    parameters:
      - $ref: '#/components/parameters/AccountId'
    post:
      operationId: importDomain
      summary: Import Domain
      description: Imports a DNS domain definition supplied as a BIND9-formatted contents block.
      tags: [Domains]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportDomainRequest'
      responses:
        '202': { $ref: '#/components/responses/AsyncJobAccepted' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/domains/{domainId}:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DomainId'
    get:
      operationId: showDomain
      summary: Show Domain
      description: Returns details for the specified domain. Set showRecords or showSubdomains to include nested data.
      tags: [Domains]
      parameters:
        - in: query
          name: showRecords
          required: false
          schema: { type: boolean }
          description: Include this domain's records in the response.
        - in: query
          name: showSubdomains
          required: false
          schema: { type: boolean }
          description: Include this domain's subdomains in the response.
      responses:
        '200':
          description: Domain returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateDomain
      summary: Update Domain
      description: Updates a single existing DNS domain.
      tags: [Domains]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDomainRequest'
      responses:
        '202': { $ref: '#/components/responses/AsyncJobAccepted' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteDomain
      summary: Delete Domain
      description: Deletes a single DNS domain. Use the deleteSubdomains query parameter to also delete its subdomains.
      tags: [Domains]
      parameters:
        - in: query
          name: deleteSubdomains
          required: false
          description: When true, all subdomains are deleted along with the domain.
          schema: { type: boolean, default: false }
      responses:
        '202': { $ref: '#/components/responses/AsyncJobAccepted' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/domains/{domainId}/changes:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DomainId'
    get:
      operationId: showDomainChanges
      summary: Show Domain Changes
      description: Returns a list of changes to the specified domain.
      tags: [Domains]
      parameters:
        - in: query
          name: changes
          required: false
          description: ISO-8601 timestamp filter; only changes since this date are returned.
          schema: { type: string, format: date-time }
      responses:
        '200':
          description: Change history returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainChanges'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/domains/{domainId}/export:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DomainId'
    get:
      operationId: exportDomain
      summary: Export Domain
      description: Exports the BIND9-formatted contents of a domain.
      tags: [Domains]
      responses:
        '202': { $ref: '#/components/responses/AsyncJobAccepted' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/domains/{domainId}/clone:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DomainId'
    post:
      operationId: cloneDomain
      summary: Clone Domain
      description: Clones the specified domain to a new domain name.
      tags: [Domains]
      parameters:
        - in: query
          name: cloneName
          required: true
          description: New name to use for the clone.
          schema: { type: string }
        - in: query
          name: cloneSubdomains
          required: false
          schema: { type: boolean, default: true }
        - in: query
          name: modifyRecordData
          required: false
          schema: { type: boolean, default: true }
        - in: query
          name: modifyEmailAddress
          required: false
          schema: { type: boolean, default: true }
        - in: query
          name: modifyComment
          required: false
          schema: { type: boolean, default: true }
      responses:
        '202': { $ref: '#/components/responses/AsyncJobAccepted' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/domains/{domainId}/subdomains:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DomainId'
    get:
      operationId: listSubdomains
      summary: List Subdomains
      description: Lists subdomains for a domain.
      tags: [Domains]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Subdomains returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/domains/{domainId}/records:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DomainId'
    get:
      operationId: listRecords
      summary: List Records
      description: Lists DNS records for the specified domain. Supports filtering by type, name, and data.
      tags: [Records]
      parameters:
        - in: query
          name: type
          required: false
          description: Filter by record type (A, AAAA, MX, CNAME, NS, TXT, SRV).
          schema: { type: string }
        - in: query
          name: name
          required: false
          schema: { type: string }
        - in: query
          name: data
          required: false
          schema: { type: string }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Records returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: addRecords
      summary: Add Records
      description: Adds one or more DNS records to the specified domain.
      tags: [Records]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddRecordsRequest'
      responses:
        '202': { $ref: '#/components/responses/AsyncJobAccepted' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteRecords
      summary: Delete Records
      description: Deletes multiple DNS records by ID.
      tags: [Records]
      parameters:
        - in: query
          name: id
          required: true
          schema:
            type: array
            items: { type: string }
          style: form
          explode: true
      responses:
        '202': { $ref: '#/components/responses/AsyncJobAccepted' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/domains/{domainId}/records/{recordId}:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DomainId'
      - $ref: '#/components/parameters/RecordId'
    get:
      operationId: showRecord
      summary: Show Record
      description: Returns details for a single DNS record.
      tags: [Records]
      responses:
        '200':
          description: Record returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Record'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteRecord
      summary: Delete Record
      description: Deletes a single DNS record.
      tags: [Records]
      responses:
        '202': { $ref: '#/components/responses/AsyncJobAccepted' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/rdns:
    parameters:
      - $ref: '#/components/parameters/AccountId'
    post:
      operationId: addPtrRecords
      summary: Add PTR Records
      description: Adds reverse DNS (PTR) records for one or more cloud devices (servers, load balancers).
      tags: [ReverseDNS]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddPtrRecordsRequest'
      responses:
        '202': { $ref: '#/components/responses/AsyncJobAccepted' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/rdns/{serviceName}:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: serviceName
        required: true
        description: The cloud service whose PTR records are being managed (cloudServersOpenStack, cloudLoadBalancers).
        schema: { type: string }
    get:
      operationId: listPtrRecords
      summary: List PTR Records
      description: Lists PTR records for the specified service and device.
      tags: [ReverseDNS]
      parameters:
        - in: query
          name: href
          required: true
          description: The fully qualified device URL whose PTR records should be listed.
          schema: { type: string, format: uri }
      responses:
        '200':
          description: PTR records returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deletePtrRecords
      summary: Delete PTR Records
      description: Deletes PTR records for the specified device.
      tags: [ReverseDNS]
      parameters:
        - in: query
          name: href
          required: true
          schema: { type: string, format: uri }
        - in: query
          name: ip
          required: false
          schema: { type: string }
      responses:
        '202': { $ref: '#/components/responses/AsyncJobAccepted' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{account}/rdns/{serviceName}/{recordId}:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: serviceName
        required: true
        schema: { type: string }
      - $ref: '#/components/parameters/RecordId'
    get:
      operationId: showPtrRecord
      summary: Show PTR Record
      description: Returns details for a single PTR record.
      tags: [ReverseDNS]
      responses:
        '200':
          description: PTR record returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Record'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    AuthToken:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: Rackspace Cloud Identity-issued authentication token.
  parameters:
    AccountId:
      in: path
      name: account
      required: true
      description: The Rackspace Cloud account (tenant) ID.
      schema: { type: string }
    DomainId:
      in: path
      name: domainId
      required: true
      description: The Rackspace Cloud DNS domain ID.
      schema: { type: string }
    RecordId:
      in: path
      name: recordId
      required: true
      description: The Rackspace Cloud DNS record ID.
      schema: { type: string }
    Limit:
      in: query
      name: limit
      required: false
      description: Maximum number of items to return (default 100).
      schema: { type: integer, default: 100, minimum: 1, maximum: 100 }
    Offset:
      in: query
      name: offset
      required: false
      description: Zero-based offset into the result set.
      schema: { type: integer, default: 0, minimum: 0 }
  responses:
    BadRequest:
      description: The request is missing one or more elements, or values are invalid.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Fault' }
    Unauthorized:
      description: You are not authorized to complete this operation.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Fault' }
    NotFound:
      description: The requested item was not found.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Fault' }
    OverLimit:
      description: The number of items returned is above the allowed limit.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Fault' }
    ServiceUnavailable:
      description: The DNS service is not available.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Fault' }
    AsyncJobAccepted:
      description: The asynchronous job has been accepted; poll the callbackUrl until status is COMPLETED.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AsyncJob'
  schemas:
    Domain:
      title: Domain
      type: object
      description: A DNS zone manageable by the account.
      properties:
        id: { type: string, description: Domain identifier. }
        accountId: { type: string, description: Tenant identifier that owns the domain. }
        name: { type: string, description: Fully qualified domain name. }
        emailAddress: { type: string, format: email, description: Administrative email contact (used as SOA RNAME). }
        ttl: { type: integer, description: Default record TTL in seconds (>= 300). }
        comment: { type: string, description: Optional administrative comment. }
        nameservers:
          type: array
          items:
            type: object
            properties:
              name: { type: string }
        recordsList:
          $ref: '#/components/schemas/RecordList'
        subdomains:
          $ref: '#/components/schemas/DomainList'
        created: { type: string, format: date-time }
        updated: { type: string, format: date-time }
    DomainList:
      title: DomainList
      type: object
      properties:
        domains:
          type: array
          items: { $ref: '#/components/schemas/Domain' }
        totalEntries: { type: integer }
        links:
          type: array
          items: { $ref: '#/components/schemas/Link' }
    DomainChanges:
      title: DomainChanges
      type: object
      properties:
        from: { type: string, format: date-time }
        to: { type: string, format: date-time }
        totalEntries: { type: integer }
        changes:
          type: array
          items:
            type: object
            properties:
              domain: { type: string }
              action: { type: string }
              targetType: { type: string }
              targetId: { type: string }
              accountId: { type: string }
              changeDetails:
                type: array
                items:
                  type: object
                  properties:
                    field: { type: string }
                    originalValue: { type: string }
                    newValue: { type: string }
    CreateDomainsRequest:
      title: CreateDomainsRequest
      type: object
      required: [domains]
      properties:
        domains:
          type: array
          items:
            type: object
            required: [name, emailAddress]
            properties:
              name: { type: string }
              ttl: { type: integer, minimum: 300 }
              emailAddress: { type: string, format: email }
              comment: { type: string }
              recordsList:
                type: object
                properties:
                  records:
                    type: array
                    items: { $ref: '#/components/schemas/RecordInput' }
              subdomains:
                type: object
                properties:
                  domains:
                    type: array
                    items: { $ref: '#/components/schemas/Domain' }
    UpdateDomainRequest:
      title: UpdateDomainRequest
      type: object
      properties:
        ttl: { type: integer, minimum: 300 }
        emailAddress: { type: string, format: email }
        comment: { type: string }
    UpdateDomainsRequest:
      title: UpdateDomainsRequest
      type: object
      properties:
        domains:
          type: array
          items:
            allOf:
              - type: object
                properties:
                  id: { type: string }
              - $ref: '#/components/schemas/UpdateDomainRequest'
    ImportDomainRequest:
      title: ImportDomainRequest
      type: object
      required: [domains]
      properties:
        domains:
          type: array
          items:
            type: object
            required: [contentType, contents]
            properties:
              contentType: { type: string, enum: [BIND_9] }
              contents: { type: string, description: BIND9-formatted zone file contents. }
    Record:
      title: Record
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        type: { type: string, enum: [A, AAAA, MX, CNAME, NS, TXT, SRV, PTR] }
        data: { type: string }
        ttl: { type: integer, minimum: 300 }
        priority: { type: integer, description: Required for MX and SRV records. }
        comment: { type: string }
        created: { type: string, format: date-time }
        updated: { type: string, format: date-time }
    RecordInput:
      title: RecordInput
      type: object
      required: [type, name, data]
      properties:
        type: { type: string, enum: [A, AAAA, MX, CNAME, NS, TXT, SRV, PTR] }
        name: { type: string }
        data: { type: string }
        ttl: { type: integer, minimum: 300 }
        priority: { type: integer }
        comment: { type: string }
    RecordList:
      title: RecordList
      type: object
      properties:
        records:
          type: array
          items: { $ref: '#/components/schemas/Record' }
        totalEntries: { type: integer }
        links:
          type: array
          items: { $ref: '#/components/schemas/Link' }
    AddRecordsRequest:
      title: AddRecordsRequest
      type: object
      required: [records]
      properties:
        records:
          type: array
          items: { $ref: '#/components/schemas/RecordInput' }
    AddPtrRecordsRequest:
      title: AddPtrRecordsRequest
      type: object
      required: [recordsList, link]
      properties:
        recordsList:
          type: object
          properties:
            records:
              type: array
              items: { $ref: '#/components/schemas/RecordInput' }
        link:
          type: object
          properties:
            content: { type: string }
            href: { type: string, format: uri }
            rel: { type: string }
    Link:
      title: Link
      type: object
      properties:
        rel: { type: string }
        href: { type: string, format: uri }
        content: { type: string }
    Limit:
      title: Limit
      type: object
      properties:
        verb: { type: string }
        URI: { type: string }
        regex: { type: string }
        value: { type: integer }
        remaining: { type: integer }
        unit: { type: string }
        resetTime: { type: integer, format: int64 }
    Limits:
      title: Limits
      type: object
      properties:
        rate:
          type: array
          items:
            type: object
            properties:
              uri: { type: string }
              regex: { type: string }
              limit:
                type: array
                items: { $ref: '#/components/schemas/Limit' }
        absolute:
          type: object
          additionalProperties: { type: integer }
    LimitTypes:
      title: LimitTypes
      type: object
      properties:
        limitTypes:
          type: array
          items: { type: string }
    AsyncJob:
      title: AsyncJob
      type: object
      properties:
        callbackUrl: { type: string, format: uri }
        status: { type: string, enum: [INITIALIZED, RUNNING, COMPLETED, ERROR] }
        requestUrl: { type: string, format: uri }
        verb: { type: string }
        jobId: { type: string }
        response:
          type: object
          additionalProperties: true
    Fault:
      title: Fault
      type: object
      properties:
        code: { type: integer }
        message: { type: string }
        details: { type: string }