Cloudflare API Guide
Last updated
Last updated
Cloudflare's API exposes the entire Cloudflare infrastructure via a standardized programmatic interface. Using Cloudflare's API, you can do just about anything you can do on cloudflare.com via the customer dashboard.
The Cloudflare API is a RESTful API based on HTTPS requests and JSON responses. If you are registered with Cloudflare, you can obtain your API key from the bottom of the "API Tokens" page.
API Tokens provide a new way to authenticate with the Cloudflare API. Cloudflare recommends API Tokens as the preferred way to interact with Cloudflare APIs. You can configure the scope of tokens to limit access to account and zone resources, and you can define the Cloudflare APIs to which the token authorizes access.
For more details on API tokens and the full range of supported options, refer to Creating API tokens:
Point 2 of the section "Customizing the Token" describes the permissions granted to the token. Add the following permissions, they will be needed for the requests of our guide:
The API is accessed by making HTTPS requests to a specific version of endpoint URL, in which GET, POST, PUT, PATCH, and DELETE methods dictate how your interact with the available information. Every endpoint is accessed only via the SSL-enabled HTTPS protocol.
Everything (methods, parameters, etc.) is fixed to a version number, and every call must contain one. The latest version is Version 4.
The stable base URL for all Version 4 HTTPS endpoints is:
Let's first consider a request to get user data. This will help you to understand the mechanics of queries using a simple example.
Launch API Tester and create a new request by tapping on the “plus” icon.
Select the GET request type.
In the screen that opens, enter the following endpoint URL in the address field:
Select OAuth in the Auth section. Enter your the generated token in the Access Token field.
Tap the send request button, the server will return the following response:
You can import this request into API Tester app via these links:
curl -X GET 'https://api.cloudflare.com/client/v4/user' -H 'Content-Type:application/json' -H 'Authorization: Bearer 2FaBkG4gZRw7PWn8Yh30zv3-bjvGR2Dqh-_xsSqN'
If you have recently registered a cloudflare account and have not filled out information about yourself, then you will see a lot of empty fields. Let's change the user details using the API.
Select the PATCH request type.
In the screen that opens, enter the following endpoint URL in the address field:
Select Raw in the Body section. Select the "application/json" value for the Content Type field.
Enter the following code in the Post data tab (You can insert your own values for fields):
Select OAuth in the Auth section. Enter your token in the Access Token field.
Tap the send request button.
The server will return the following response:
You can import this request into API Tester app via these links:
curl -X PATCH 'https://api.cloudflare.com/client/v4/user' -H 'Content-Type:application/json' -d '{
"first_name": "Matthew",
"last_name": "Tdg",
"telephone": "+1 123-123-1234",
"country": "US",
"zipcode": "12345"
}' -H 'Authorization: Bearer 2FaBkG4gZRw7PWn8Yh30zv3-bjvGR2Dqh-_xsSqN'
Now let's look at the list of zones (websites) added to cloudflare. Let's form a GET request. Required endpoint:
Also you will need to add "content-type" header with value "application/json".
Don't forget to insert an access token!
In this case, the server returned information that there are no added zones.
You can import this request into API Tester app via these links:
curl -X GET 'https://api.cloudflare.com/client/v4/zones' -H 'Content-Type:application/json' -H 'Authorization: Bearer FyGM32Sposdo0jI7BWTJ2ItZzc8wU1VRs7dTGzY7'
To add a zone, you need to form a POST request. Follow a few simple steps:
Select the POST request type.
In the screen that opens, enter the following endpoint URL in the address field:
Select Raw in the Body section. Select the application/json value for the Content Type field.
Enter the following code in the Post data field:
You can find your account ID in the address bar on the cloudflare homepage.
Select OAuth in the Auth section. Enter your token in the Access Token field.
Tap the send request button.
If you want to find out which fields are available for modification, read the documentation: https://api.cloudflare.com
The server will return information about the created zone:
You can import this request into API Tester app via these links:
curl -X POST 'https://api.cloudflare.com/client/v4/zones' -H 'Content-Type:application/json' -d '{
"name":"electrik-anapa.ru",
"account":{"id":"798b6608db08642b7f45a7eba6500d04"},
"jump_start":true,
"type":"full"
}' -H 'Authorization: Bearer FyGM32Sposdo0jI7BWTJ2ItZzc8wU1VRs7dTGzY7'
Now let's try to create a new DNS record for the zone by analogy with the creation of the zone.
Endpoint:
Here, after zones, insert the zone ID. You can find this ID in the response from the server in the previous request.
Enter the following code in the Post data field:
The other fields remain as in the previous request. The server will return the data of the created DNS record:
You can import this request into API Tester app via these links:
curl -X POST 'https://api.cloudflare.com/client/v4/zones/8662532b9d531d9fa821b44ef8dac26e/dns_records' -H 'Content-Type:application/json' -d '{
"type":"A",
"name":"example.com",
"content":"127.0.0.1",
"ttl":1,
"priority":0
}' -H 'Authorization: Bearer FyGM32Sposdo0jI7BWTJ2ItZzc8wU1VRs7dTGzY7'
Now we can check whether a DNS record has been created or not with a GET request. The endpoint remains the same as in the previous request. Don't forget to insert an access token!
Indeed, the server returned an array of DNS records that contains the record we created.
You can import this request into API Tester app via these links:
curl -X GET 'https://api.cloudflare.com/client/v4/zones/8662532b9d531d9fa821b44ef8dac26e/dns_records' -H 'Content-Type:application/json' -H 'Authorization: Bearer FyGM32Sposdo0jI7BWTJ2ItZzc8wU1VRs7dTGzY7'
Let's look at an example of a request with DELETE type and delete the newly created record. This request requires the DNS record ID, copy it from the response in the previous request. Insert it into the query string after "dns_records/".
Endpoint:
No additional parameters are required for this request, but don't forget to insert your access token. If successful, the server will return response like this:
You can import this request into API Tester app via these links:
curl -X DELETE 'https://api.cloudflare.com/client/v4/zones/8662532b9d531d9fa821b44ef8dac26e/dns_records/4cf16ce374cd69a421d879d7a352b040' -H 'Authorization: Bearer 9QHNe_YCeqb7CauUOZlNSwMoOr6EM9OWYlW46svl'
