Cloudflare DNS Records API

openapi: 3.2.0
info:
  title: Cloudflare DNS DNS Records API
  description: The Cloudflare DNS API allows developers to programmatically manage DNS records for their zones, including creating, listing, updating, and deleting records. It also supports batch operations, DNS record scanning, BIND config import and export, DNSSEC configuration, and DNS analytics.
  version: '4.0'
  contact:
    name: Cloudflare Support
    url: https://support.cloudflare.com/
  termsOfService: https://www.cloudflare.com/terms/
servers:
- url: https://api.cloudflare.com/client/v4
  description: Cloudflare API v4 Production Server
security:
- bearerAuth: []
tags:
- name: DNS Records
  description: Manage DNS records for a zone including A, AAAA, CNAME, MX, TXT, SRV, and other record types.
paths:
  /zones/{zone_id}/dns_records:
    get:
      operationId: listDnsRecords
      summary: Cloudflare List Dns Records
      description: List, search, sort, and filter a zone's DNS records. Returns a paginated list of DNS records for the specified zone.
      tags:
      - DNS Records
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      - name: type
        in: query
        description: DNS record type to filter by.
        schema:
          $ref: '#/components/schemas/RecordType'
        example: example_value
      - name: name
        in: query
        description: DNS record name to filter by.
        schema:
          type: string
        example: Example Title
      - name: content
        in: query
        description: DNS record content to filter by.
        schema:
          type: string
        example: example_value
      - name: page
        in: query
        description: Page number of paginated results.
        schema:
          type: integer
          minimum: 1
          default: 1
        example: 10
      - name: per_page
        in: query
        description: Number of records per page.
        schema:
          type: integer
          minimum: 5
          maximum: 50000
          default: 100
        example: 10
      responses:
        '200':
          description: Successful response with a list of DNS records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DnsRecordListResponse'
              examples:
                Listdnsrecords200Example:
                  summary: Default listDnsRecords 200 response
                  x-microcks-default: true
                  value:
                    result:
                    - id: abc123
                      zone_id: '500123'
                      zone_name: example_value
                      name: Example Title
                      content: example_value
                      ttl: 10
                      proxied: true
                      proxiable: true
                      locked: true
                      comment: example_value
                      tags: {}
                      created_on: '2026-01-15T10:30:00Z'
                      modified_on: '2026-01-15T10:30:00Z'
                    success: true
                    errors:
                    - {}
                    messages:
                    - {}
                    result_info:
                      page: 10
                      per_page: 10
                      count: 10
                      total_count: 10
                      total_pages: 10
        '400':
          description: Bad request due to invalid parameters.
        '401':
          description: Unauthorized due to missing or invalid authentication.
        '403':
          description: Forbidden due to insufficient permissions.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createDnsRecord
      summary: Cloudflare Create Dns Record
      description: Create a new DNS record for a zone. A/AAAA records cannot coexist with CNAME records on the same name, and NS records cannot share names with other record types.
      tags:
      - DNS Records
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DnsRecordInput'
            examples:
              CreatednsrecordRequestExample:
                summary: Default createDnsRecord request
                x-microcks-default: true
                value:
                  type: A
                  name: Example Title
                  content: example_value
                  ttl: 10
                  priority: 10
                  proxied: true
                  comment: example_value
                  tags:
                  - example_value
      responses:
        '200':
          description: DNS record created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DnsRecordResponse'
              examples:
                Creatednsrecord200Example:
                  summary: Default createDnsRecord 200 response
                  x-microcks-default: true
                  value:
                    result:
                      id: abc123
                      zone_id: '500123'
                      zone_name: example_value
                      name: Example Title
                      content: example_value
                      ttl: 10
                      proxied: true
                      proxiable: true
                      locked: true
                      comment: example_value
                      tags:
                      - {}
                      created_on: '2026-01-15T10:30:00Z'
                      modified_on: '2026-01-15T10:30:00Z'
                    success: true
                    errors:
                    - {}
                    messages:
                    - {}
        '400':
          description: Bad request due to invalid record data.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /zones/{zone_id}/dns_records/{dns_record_id}:
    get:
      operationId: getDnsRecord
      summary: Cloudflare Get Dns Record Details
      description: Retrieve the details of a specific DNS record by its identifier.
      tags:
      - DNS Records
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      - $ref: '#/components/parameters/DnsRecordId'
      responses:
        '200':
          description: Successful response with DNS record details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DnsRecordResponse'
              examples:
                Getdnsrecord200Example:
                  summary: Default getDnsRecord 200 response
                  x-microcks-default: true
                  value:
                    result:
                      id: abc123
                      zone_id: '500123'
                      zone_name: example_value
                      name: Example Title
                      content: example_value
                      ttl: 10
                      proxied: true
                      proxiable: true
                      locked: true
                      comment: example_value
                      tags:
                      - {}
                      created_on: '2026-01-15T10:30:00Z'
                      modified_on: '2026-01-15T10:30:00Z'
                    success: true
                    errors:
                    - {}
                    messages:
                    - {}
        '401':
          description: Unauthorized.
        '404':
          description: DNS record not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateDnsRecord
      summary: Cloudflare Update Dns Record
      description: Partially update a DNS record. Only the fields provided in the request body will be updated.
      tags:
      - DNS Records
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      - $ref: '#/components/parameters/DnsRecordId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DnsRecordInput'
            examples:
              UpdatednsrecordRequestExample:
                summary: Default updateDnsRecord request
                x-microcks-default: true
                value:
                  type: A
                  name: Example Title
                  content: example_value
                  ttl: 10
                  priority: 10
                  proxied: true
                  comment: example_value
                  tags:
                  - example_value
      responses:
        '200':
          description: DNS record updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DnsRecordResponse'
              examples:
                Updatednsrecord200Example:
                  summary: Default updateDnsRecord 200 response
                  x-microcks-default: true
                  value:
                    result:
                      id: abc123
                      zone_id: '500123'
                      zone_name: example_value
                      name: Example Title
                      content: example_value
                      ttl: 10
                      proxied: true
                      proxiable: true
                      locked: true
                      comment: example_value
                      tags:
                      - {}
                      created_on: '2026-01-15T10:30:00Z'
                      modified_on: '2026-01-15T10:30:00Z'
                    success: true
                    errors:
                    - {}
                    messages:
                    - {}
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
        '404':
          description: DNS record not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: overwriteDnsRecord
      summary: Cloudflare Overwrite Dns Record
      description: Completely replace a DNS record with the provided data. All fields must be provided.
      tags:
      - DNS Records
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      - $ref: '#/components/parameters/DnsRecordId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DnsRecordInput'
            examples:
              OverwritednsrecordRequestExample:
                summary: Default overwriteDnsRecord request
                x-microcks-default: true
                value:
                  type: A
                  name: Example Title
                  content: example_value
                  ttl: 10
                  priority: 10
                  proxied: true
                  comment: example_value
                  tags:
                  - example_value
      responses:
        '200':
          description: DNS record overwritten successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DnsRecordResponse'
              examples:
                Overwritednsrecord200Example:
                  summary: Default overwriteDnsRecord 200 response
                  x-microcks-default: true
                  value:
                    result:
                      id: abc123
                      zone_id: '500123'
                      zone_name: example_value
                      name: Example Title
                      content: example_value
                      ttl: 10
                      proxied: true
                      proxiable: true
                      locked: true
                      comment: example_value
                      tags:
                      - {}
                      created_on: '2026-01-15T10:30:00Z'
                      modified_on: '2026-01-15T10:30:00Z'
                    success: true
                    errors:
                    - {}
                    messages:
                    - {}
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
        '404':
          description: DNS record not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteDnsRecord
      summary: Cloudflare Delete Dns Record
      description: Delete a specific DNS record from the zone.
      tags:
      - DNS Records
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      - $ref: '#/components/parameters/DnsRecordId'
      responses:
        '200':
          description: DNS record deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The identifier of the deleted DNS record.
                  success:
                    type: boolean
              examples:
                Deletednsrecord200Example:
                  summary: Default deleteDnsRecord 200 response
                  x-microcks-default: true
                  value:
                    result:
                      id: abc123
                    success: true
        '401':
          description: Unauthorized.
        '404':
          description: DNS record not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    DnsRecordListResponse:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/DnsRecord'
          example: []
        success:
          type: boolean
          example: true
        errors:
          type: array
          items:
            type: object
          example: []
        messages:
          type: array
          items:
            type: object
          example: []
        result_info:
          type: object
          properties:
            page:
              type: integer
            per_page:
              type: integer
            count:
              type: integer
            total_count:
              type: integer
            total_pages:
              type: integer
          example: example_value
    DnsRecordResponse:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/DnsRecord'
        success:
          type: boolean
          example: true
        errors:
          type: array
          items:
            type: object
          example: []
        messages:
          type: array
          items:
            type: object
          example: []
    DnsRecord:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the DNS record.
          example: abc123
        zone_id:
          type: string
          description: The zone identifier.
          example: '500123'
        zone_name:
          type: string
          description: The zone name.
          example: example_value
        type:
          $ref: '#/components/schemas/RecordType'
        name:
          type: string
          description: The DNS record name.
          example: Example Title
        content:
          type: string
          description: The DNS record content.
          example: example_value
        ttl:
          type: integer
          description: Time to live in seconds.
          example: 10
        proxied:
          type: boolean
          description: Whether the record is proxied through Cloudflare.
          example: true
        proxiable:
          type: boolean
          description: Whether the record can be proxied.
          example: true
        locked:
          type: boolean
          description: Whether the record is locked.
          example: true
        comment:
          type: string
          description: A comment about the DNS record.
          example: example_value
        tags:
          type: array
          items:
            type: string
          description: Custom tags for the DNS record.
          example: []
        created_on:
          type: string
          format: date-time
          description: When the record was created.
          example: '2026-01-15T10:30:00Z'
        modified_on:
          type: string
          format: date-time
          description: When the record was last modified.
          example: '2026-01-15T10:30:00Z'
    DnsRecordInput:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/RecordType'
        name:
          type: string
          description: The DNS record name, e.g. example.com.
          example: Example Title
        content:
          type: string
          description: The DNS record content value.
          example: example_value
        ttl:
          type: integer
          description: Time to live in seconds. A value of 1 indicates automatic TTL.
          minimum: 1
          maximum: 86400
          example: 10
        priority:
          type: integer
          description: Required for MX, SRV, and URI records. Record priority.
          minimum: 0
          maximum: 65535
          example: 10
        proxied:
          type: boolean
          description: Whether the record is receiving Cloudflare proxy services.
          example: true
        comment:
          type: string
          description: A comment about the DNS record.
          example: example_value
        tags:
          type: array
          items:
            type: string
          description: Custom tags for the DNS record.
          example: []
    RecordType:
      type: string
      description: The type of DNS record.
      enum:
      - A
      - AAAA
      - CAA
      - CERT
      - CNAME
      - DNSKEY
      - DS
      - HTTPS
      - LOC
      - MX
      - NAPTR
      - NS
      - PTR
      - SMIMEA
      - SRV
      - SSHFP
      - SVCB
      - TLSA
      - TXT
      - URI
  parameters:
    DnsRecordId:
      name: dns_record_id
      in: path
      required: true
      description: The unique identifier of the DNS record.
      schema:
        type: string
    ZoneId:
      name: zone_id
      in: path
      required: true
      description: The unique identifier of the zone.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API token authentication. Generate a token from the Cloudflare dashboard with appropriate permissions.
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Auth-Key
      description: Global API key paired with X-Auth-Email header for authentication.
externalDocs:
  description: Cloudflare DNS API Documentation
  url: https://developers.cloudflare.com/api/resources/dns/