openapi: 3.1.0
info:
  title: Cloudflare DNS 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/
externalDocs:
  description: Cloudflare DNS API Documentation
  url: https://developers.cloudflare.com/api/resources/dns/
servers:
- url: https://api.cloudflare.com/client/v4
  description: Cloudflare API v4 Production Server
tags:
- name: DNS Analytics
  description: >-
    Access DNS query analytics for a zone with aggregated and time-grouped
    metrics.
- name: DNS Batch Operations
  description: >-
    Execute multiple DNS record operations in a single API call.
- name: DNS Record Import/Export
  description: >-
    Import and export DNS records using BIND zone file format.
- name: DNS Record Scanning
  description: >-
    Scan for common DNS records on a domain and review discovered records.
- name: DNS Records
  description: >-
    Manage DNS records for a zone including A, AAAA, CNAME, MX, TXT, SRV,
    and other record types.
- name: DNSSEC
  description: >-
    Manage DNSSEC settings for a zone to protect against DNS spoofing.
security:
- bearerAuth: []
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
  /zones/{zone_id}/dns_records/batch:
    post:
      operationId: batchDnsRecords
      summary: Cloudflare Batch Dns Record Operations
      description: >-
        Send a batch of DNS record API calls to be executed together. Supports
        deletes, patches, puts, and posts executed in order.
      tags:
      - DNS Batch Operations
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                deletes:
                  type: array
                  description: DNS records to delete.
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                patches:
                  type: array
                  description: DNS records to partially update.
                  items:
                    $ref: '#/components/schemas/DnsRecordInput'
                puts:
                  type: array
                  description: DNS records to fully replace.
                  items:
                    $ref: '#/components/schemas/DnsRecordInput'
                posts:
                  type: array
                  description: DNS records to create.
                  items:
                    $ref: '#/components/schemas/DnsRecordInput'
            examples:
              BatchdnsrecordsRequestExample:
                summary: Default batchDnsRecords request
                x-microcks-default: true
                value:
                  deletes:
                  - id: abc123
                  patches:
                  - name: Example Title
                    content: example_value
                    ttl: 10
                    priority: 10
                    proxied: true
                    comment: example_value
                    tags:
                    - {}
                  puts:
                  - name: Example Title
                    content: example_value
                    ttl: 10
                    priority: 10
                    proxied: true
                    comment: example_value
                    tags:
                    - {}
                  posts:
                  - name: Example Title
                    content: example_value
                    ttl: 10
                    priority: 10
                    proxied: true
                    comment: example_value
                    tags:
                    - {}
      responses:
        '200':
          description: Batch operation completed successfully.
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /zones/{zone_id}/dns_records/export:
    get:
      operationId: exportDnsRecords
      summary: Cloudflare Export Dns Records
      description: >-
        Export all DNS records for a zone in BIND zone file format.
      tags:
      - DNS Record Import/Export
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      responses:
        '200':
          description: BIND zone file content.
          content:
            text/plain:
              schema:
                type: string
              examples:
                Exportdnsrecords200Example:
                  summary: Default exportDnsRecords 200 response
                  x-microcks-default: true
                  value: example_value
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /zones/{zone_id}/dns_records/import:
    post:
      operationId: importDnsRecords
      summary: Cloudflare Import Dns Records
      description: >-
        Import DNS records from a BIND zone file. Upload the BIND config to
        create DNS records in the zone.
      tags:
      - DNS Record Import/Export
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: BIND zone file to import.
            examples:
              ImportdnsrecordsRequestExample:
                summary: Default importDnsRecords request
                x-microcks-default: true
                value:
                  file: example_value
      responses:
        '200':
          description: Import completed successfully.
        '400':
          description: Bad request due to invalid BIND config.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /zones/{zone_id}/dns_records/scan/trigger:
    post:
      operationId: triggerDnsRecordScan
      summary: Cloudflare Trigger Dns Record Scan
      description: >-
        Initiate an asynchronous scan for common DNS records on the domain. The
        scan runs in the background and results can be reviewed using the
        scan review endpoints.
      tags:
      - DNS Record Scanning
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      responses:
        '200':
          description: Scan triggered successfully.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /zones/{zone_id}/dns_records/scan/review:
    get:
      operationId: listScannedDnsRecords
      summary: Cloudflare List Scanned Dns Records
      description: >-
        Retrieve the DNS records discovered by the most recent scan for review
        before adding them to the zone.
      tags:
      - DNS Record Scanning
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      responses:
        '200':
          description: List of scanned DNS records.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: reviewScannedDnsRecords
      summary: Cloudflare Accept Scanned Dns Records
      description: >-
        Review and accept scanned DNS records to add them to the zone.
      tags:
      - DNS Record Scanning
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      responses:
        '200':
          description: Scanned records accepted.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /zones/{zone_id}/dns_analytics/report:
    get:
      operationId: getDnsAnalyticsReport
      summary: Cloudflare Get Dns Analytics Report
      description: >-
        Retrieve aggregated DNS analytics metrics for the zone including query
        counts, response codes, and record types.
      tags:
      - DNS Analytics
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      - name: since
        in: query
        description: Start date of the analytics query in ISO 8601 format.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      - name: until
        in: query
        description: End date of the analytics query in ISO 8601 format.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      responses:
        '200':
          description: Aggregated DNS analytics report.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /zones/{zone_id}/dns_analytics/report/bytime:
    get:
      operationId: getDnsAnalyticsByTime
      summary: Cloudflare Get Dns Analytics by Time
      description: >-
        Retrieve time-grouped DNS analytics metrics for the zone.
      tags:
      - DNS Analytics
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      - name: since
        in: query
        description: Start date in ISO 8601 format.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      - name: until
        in: query
        description: End date in ISO 8601 format.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      - name: time_delta
        in: query
        description: Time interval for grouping results.
        schema:
          type: string
          enum:
          - all
          - auto
          - year
          - quarter
          - month
          - week
          - day
          - dekaminute
          - hour
          - minute
        example: all
      responses:
        '200':
          description: Time-grouped DNS analytics report.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /zones/{zone_id}/dnssec:
    get:
      operationId: getDnssecSettings
      summary: Cloudflare Get Dnssec Settings
      description: >-
        Retrieve the current DNSSEC settings for the zone including status,
        algorithm, digest, and DS record details.
      tags:
      - DNSSEC
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      responses:
        '200':
          description: DNSSEC settings retrieved successfully.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateDnssecSettings
      summary: Cloudflare Update Dnssec Settings
      description: >-
        Update DNSSEC configuration for the zone such as enabling or disabling
        DNSSEC.
      tags:
      - DNSSEC
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - active
                  - disabled
                  description: Desired DNSSEC status.
            examples:
              UpdatednssecsettingsRequestExample:
                summary: Default updateDnssecSettings request
                x-microcks-default: true
                value:
                  status: active
      responses:
        '200':
          description: DNSSEC settings updated successfully.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteDnssecSettings
      summary: Cloudflare Delete Dnssec Settings
      description: >-
        Remove DNSSEC configuration from the zone.
      tags:
      - DNSSEC
      parameters:
      - $ref: '#/components/parameters/ZoneId'
      responses:
        '200':
          description: DNSSEC settings deleted successfully.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  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.
  parameters:
    ZoneId:
      name: zone_id
      in: path
      required: true
      description: The unique identifier of the zone.
      schema:
        type: string
    DnsRecordId:
      name: dns_record_id
      in: path
      required: true
      description: The unique identifier of the DNS record.
      schema:
        type: string
  schemas:
    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
    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: []
    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'
    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: []
    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