Create a Distribution

Prerequisite: Only contract administrators, owners, and users with accessAndManageCdn privilege can create and manage CDN distributions via the API. You can also set user privileges in the DCD. For more information, see Set User Privileges.

To create a CDN distribution, perform a POST request.

Endpoint

Use the following endpoint to create a CDN distribution: https://cdn.de-fra.ionos.com/distributions.

Request

curl --location \
--request POST 'https://cdn.de-fra.ionos.com/distributions' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiO' \
--header 'Content-Type: application/json' \
--data '{
    "properties": {
        "domain": "example.com",
        "certificateId": "5a029f4a-72e5-11ec-90d6-0242ac120003",
        "routingRules": [
            {
                "scheme": "http/https",
                "prefix": "/api",
                "upstream": {
                    "host": "server.example.com",
                    "caching": true,
                    "waf": true,
                    "geoRestrictions": {
                        "blockList": [
                            "CN",
                            "RU"
                        ]
                    },
                    "rateLimitClass": "R10",
                    "sniMode": "origin"
                }
            }
        ]
    }
}'

Request Body Parameters

Below is the list of mandatory body parameters:

Body Parameters	Type	Description	Example
domain	string	The domain name for the CDN distribution.	example.com
scheme	string	Choose whether to allow http, https, or http/https protocol.	http/https
prefix	string	A prefix to match the beginning segment of the URL path and apply routing rule.	/api
host	string	An upstream host name that handles requests if data not cached in the CDN edge server.	server.example.com
caching	boolean	If enabled, CDN caches the data from the upstream host.	true
waf	boolean	If enabled, protects the upstream host.	true
rateLimitClass	string	Limits the number of incoming requests per IP.	R10
sniMode	string	This field sets the SNI mode for the outgoing connection to the upstream host. Use distribution if the certificate must match the CDN distribution domain. Alternatively, use origin to ensure the certificate matches the upstream hostname.	origin

Request Header Parameters

To make authenticated requests to the API, the following fields are mandatory in the request header:

Header Parameters	Required	Type	Description
Authorization	yes	string	The Bearer token enables requests to authenticate using a JSON Web Token (JWT). From the DCD, Generate authentication token.
Content-Type	yes	string	Set this to application/json.

Response

201 Successful operation

{
  "id": "9ba15778-16c4-543c-8775-e52acf4853f5",
  "type": "distribution",
  "href": "/distributions/9ba15778-16c4-543c-8775-e52acf4853f5",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "publicEndpointIpv4": "1.2.3.4",
    "publicEndpointIpv6": "2001:db8::ff00:42:8329",
    "ownershipTxtFqdn": "_dep_ws_mutex.example.com",
    "ownershipTxtValue": "4b2a9f1e8c7d6053a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9_1720000000000",
    "state": "AVAILABLE",
    "message": "In progress."
  },
  "properties": {
    "domain": "example.com",
    "certificateId": "5a029f4a-72e5-11ec-90d6-0242ac120003",
    "routingRules": [
      {
        "scheme": "http/https",
        "prefix": "/api",
        "upstream": {
          "host": "server.example.com",
          "caching": true,
          "waf": true,
          "geoRestrictions": {
            "blockList": [
              "CN",
              "RU"
            ]
          },
          "rateLimitClass": "R100",
          "sniMode": "origin"
        }
      }
    ]
  }
}

Result: The CDN distribution is successfully created; the id and other details of the created distribution are provided in the response.

Domain ownership verification: The read-only metadata.ownershipTxtFqdn and metadata.ownershipTxtValue fields provide the details for a TXT record you can publish in DNS to claim ownership of the distribution's domain. Create a TXT record using the name from ownershipTxtFqdn and the value from ownershipTxtValue. If another user currently claims the same domain, you must publish this record before the distribution can reach the AVAILABLE state. Keep the TXT record published permanently to retain ownership of the domain.