Cloudflare.DnsRecord (Cloudflare v0.5.0)

Copy Markdown View Source

DNS Records for a Zone

Create DNS Record

POST /zones/{zone_id}/dns_records

Create a new DNS record for a zone.

Notes:

  • A/AAAA records cannot exist on the same name as CNAME records.
  • NS records cannot exist on the same name as any other record type.
  • Domain names are always represented in Punycode, even if Unicode characters were used when creating the record.

Responses

200 Create DNS Record response

Data is at body["result"]

{
  "comment_modified_on": "*string*",
  "created_on": "*string*",
  "id": "*string*",
  "meta": {},
  "modified_on": "*string*",
  "proxiable": "*boolean*",
  "tags_modified_on": "*string*"
}
4XX Create DNS Record response failure
{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "result": {},
  "success": "*boolean*"
}

List DNS Records

GET /zones/{zone_id}/dns_records

List, search, sort, and filter a zones' DNS records.

Responses

200 List DNS Records response

Data is at body["result"]

[
  {
    "comment_modified_on": "*string*",
    "created_on": "*string*",
    "id": "*string*",
    "meta": {},
    "modified_on": "*string*",
    "proxiable": "*boolean*",
    "tags_modified_on": "*string*"
  }
]
4XX List DNS Records response failure
{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "result": {},
  "result_info": {
    "count": "*number*",
    "page": "*number*",
    "per_page": "*number*",
    "total_count": "*number*"
  },
  "success": "*boolean*"
}

Batch DNS Records

POST /zones/{zone_id}/dns_records/batch

Send a Batch of DNS Record API calls to be executed together.

Notes:

  • Although Cloudflare will execute the batched operations in a single database transaction, Cloudflare's distributed KV store must treat each record change as a single key-value pair. This means that the propagation of changes is not atomic. See the documentation for more information.

  • The operations you specify within the /batch request body are always executed in the following order:

    • Deletes
    • Patches
    • Puts
    • Posts

Responses

200 Batch DNS Records response

Data is at body["result"]

{
  "deletes": [
    {
      "comment_modified_on": "*string*",
      "created_on": "*string*",
      "id": "*string*",
      "meta": {},
      "modified_on": "*string*",
      "proxiable": "*boolean*",
      "tags_modified_on": "*string*"
    }
  ],
  "patches": [
    {
      "comment_modified_on": "*string*",
      "created_on": "*string*",
      "id": "*string*",
      "meta": {},
      "modified_on": "*string*",
      "proxiable": "*boolean*",
      "tags_modified_on": "*string*"
    }
  ],
  "posts": [
    {
      "comment_modified_on": "*string*",
      "created_on": "*string*",
      "id": "*string*",
      "meta": {},
      "modified_on": "*string*",
      "proxiable": "*boolean*",
      "tags_modified_on": "*string*"
    }
  ],
  "puts": [
    {
      "comment_modified_on": "*string*",
      "created_on": "*string*",
      "id": "*string*",
      "meta": {},
      "modified_on": "*string*",
      "proxiable": "*boolean*",
      "tags_modified_on": "*string*"
    }
  ]
}
4XX Batch DNS Records response failure
{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "result": {},
  "success": "*boolean*"
}

Export DNS Records

GET /zones/{zone_id}/dns_records/export

You can export your BIND config through this endpoint.

See the documentation for more information.

Responses

200 Export DNS Records response

Data is at body["result"]

4XX Export DNS Records response failure
{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "result": {},
  "success": "*boolean*"
}

Import DNS Records

POST /zones/{zone_id}/dns_records/import

You can upload your BIND config through this endpoint. It assumes that cURL is called from a location with bind_config.txt (valid BIND config) present.

See the documentation for more information.

Responses

200 Import DNS Records response

Data is at body["result"]

{
  "recs_added": "*number*",
  "total_records_parsed": "*number*"
}
4XX Import DNS Records response failure
{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "result": {},
  "success": "*boolean*"
}

Scan DNS Records

POST /zones/{zone_id}/dns_records/scan

Scan for common DNS records on your domain and automatically add them to your zone. Useful if you haven't updated your nameservers yet.

Responses

200 Scan DNS Records response

Data is at body["result"]

{
  "recs_added": "*number*",
  "total_records_parsed": "*number*"
}
4XX Scan DNS Records response failure
{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "result": {},
  "success": "*boolean*"
}

Review Scanned DNS Records

POST /zones/{zone_id}/dns_records/scan/review

Accept or reject DNS records found by the DNS records scan. Accepted records will be permanently added to the zone, while rejected records will be permanently deleted.

Responses

200 Records reviewed successfully

Data is at body["result"]

{
  "accepts": [
    {
      "comment_modified_on": "*string*",
      "created_on": "*string*",
      "id": "*string*",
      "meta": {},
      "modified_on": "*string*",
      "proxiable": "*boolean*",
      "tags_modified_on": "*string*"
    }
  ],
  "rejects": [
    "*string*"
  ]
}
4XX Review failure
{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "result": {},
  "success": "*boolean*"
}

List Scanned DNS Records

GET /zones/{zone_id}/dns_records/scan/review

Retrieves the list of DNS records discovered up to this point by the asynchronous scan. These records are temporary until explicitly accepted or rejected via POST /scan/review. Additional records may be discovered by the scan later.

Responses

200 List of discovered DNS records

Data is at body["result"]

[
  {
    "comment_modified_on": "*string*",
    "created_on": "*string*",
    "id": "*string*",
    "meta": {},
    "modified_on": "*string*",
    "proxiable": "*boolean*",
    "tags_modified_on": "*string*"
  }
]
4XX Scan review failure
{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "result": {},
  "success": "*boolean*"
}

Trigger DNS Record Scan

POST /zones/{zone_id}/dns_records/scan/trigger

Initiates an asynchronous scan for common DNS records on your domain. Note that this does not automatically add records to your zone. The scan runs in the background, and results can be reviewed later using the /scan/review endpoints. Useful if you haven't updated your nameservers yet.

Responses

200 Trigger DNS Records Scan Response

Data is at body["result"]

{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "success": "*boolean*"
}
4XX Trigger DNS Records Scan response failure
{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "result": {},
  "success": "*boolean*"
}

Get DNS Record Usage

GET /zones/{zone_id}/dns_records/usage

Get the current DNS record usage for a zone, including the number of records and the quota limit.

Responses

200 Get DNS Record Usage response

Data is at body["result"]

{
  "record_quota": "*integer*",
  "record_usage": "*integer*"
}
4XX Get DNS Record Usage response failure
{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "result": {},
  "success": "*boolean*"
}

Overwrite DNS Record

PUT /zones/{zone_id}/dns_records/{dns_record_id}

Overwrite an existing DNS record.

Notes:

  • A/AAAA records cannot exist on the same name as CNAME records.
  • NS records cannot exist on the same name as any other record type.
  • Domain names are always represented in Punycode, even if Unicode characters were used when creating the record.

Responses

200 Update DNS Record response

Data is at body["result"]

{
  "comment_modified_on": "*string*",
  "created_on": "*string*",
  "id": "*string*",
  "meta": {},
  "modified_on": "*string*",
  "proxiable": "*boolean*",
  "tags_modified_on": "*string*"
}
4XX Update DNS Record response failure
{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "result": {},
  "success": "*boolean*"
}

Update DNS Record

PATCH /zones/{zone_id}/dns_records/{dns_record_id}

Update an existing DNS record.

Notes:

  • A/AAAA records cannot exist on the same name as CNAME records.
  • NS records cannot exist on the same name as any other record type.
  • Domain names are always represented in Punycode, even if Unicode characters were used when creating the record.

Responses

200 Patch DNS Record response

Data is at body["result"]

{
  "comment_modified_on": "*string*",
  "created_on": "*string*",
  "id": "*string*",
  "meta": {},
  "modified_on": "*string*",
  "proxiable": "*boolean*",
  "tags_modified_on": "*string*"
}
4XX Patch DNS Record response failure
{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "result": {},
  "success": "*boolean*"
}

DNS Record Details

GET /zones/{zone_id}/dns_records/{dns_record_id}

Responses

200 DNS Record Details response

Data is at body["result"]

{
  "comment_modified_on": "*string*",
  "created_on": "*string*",
  "id": "*string*",
  "meta": {},
  "modified_on": "*string*",
  "proxiable": "*boolean*",
  "tags_modified_on": "*string*"
}
4XX DNS Record Details response failure
{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "result": {},
  "success": "*boolean*"
}

Delete DNS Record

DELETE /zones/{zone_id}/dns_records/{dns_record_id}

Responses

200 Delete DNS Record response

Data is at body["result"]

{
  "id": "*string*"
}
4XX Delete DNS Record response failure
{
  "errors": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "documentation_url": "*string*",
      "message": "*string*",
      "source": {
        "pointer": "*string*"
      }
    }
  ],
  "result": {},
  "success": "*boolean*"
}

Summary

Functions

client(opts \\ [])
create(body, opts \\ [])
create!(body, opts \\ [])
delete(id, opts \\ [])
delete!(id, opts \\ [])
export(opts \\ [])
import(data, opts \\ [])
index(opts \\ [])
index!(opts \\ [])
path_for(id, opts \\ [])
show(id, opts \\ [])
show!(id, opts \\ [])
update(id, body, opts \\ [])
update!(id, body, opts \\ [])

Functions

client(opts \\ [])

@spec client(Restlax.Resource.action_options()) :: module()

create(body, opts \\ [])

@spec create(
  body :: Restlax.Resource.action_body(),
  opts :: Restlax.Resource.action_options()
) ::
  {:ok, map()} | {:error, term()}

create!(body, opts \\ [])

@spec create!(
  body :: Restlax.Resource.action_body(),
  opts :: Restlax.Resource.action_options()
) ::
  map() | no_return()

delete(id, opts \\ [])

@spec delete(id :: term(), opts :: Restlax.Resource.action_options()) ::
  {:ok, map()} | {:error, term()}

delete!(id, opts \\ [])

@spec delete!(id :: term(), opts :: Restlax.Resource.action_options()) ::
  map() | no_return()

export(opts \\ [])

import(data, opts \\ [])

index(opts \\ [])

@spec index(opts :: Restlax.Resource.action_options()) ::
  {:ok, map()} | {:error, term()}

index!(opts \\ [])

@spec index!(opts :: Restlax.Resource.action_options()) :: map() | no_return()

path_for(id, opts \\ [])

@spec path_for(term(), [{:action, String.t()}]) :: String.t()

show(id, opts \\ [])

@spec show(id :: term(), opts :: Restlax.Resource.action_options()) ::
  {:ok, map()} | {:error, term()}

show!(id, opts \\ [])

@spec show!(id :: term(), opts :: Restlax.Resource.action_options()) ::
  map() | no_return()

update(id, body, opts \\ [])

@spec update(
  id :: term(),
  body :: Restlax.Resource.action_body(),
  opts :: Restlax.Resource.action_options()
) :: {:ok, map()} | {:error, term()}

update!(id, body, opts \\ [])

@spec update!(
  id :: term(),
  body :: Restlax.Resource.action_body(),
  opts :: Restlax.Resource.action_options()
) :: map() | no_return()