Recent searches

in
Developer ReferenceAPI

Base Domains

On this page

  1. GETGet a Base Domain
  2. PUTUpdate a Base Domain's minimum TLS version or fallback redirect status
  3. DELETEDelete a Base Domain
  4. GETGet a Base Domain's DNS status
  5. POSTEnable DNS management for a Base Domain
  6. DELETEDisable DNS management for a Base Domain
  7. POSTCheck a Base Domain's nameservers now, and on External DNS its wildcard record and its wildcard certificate's TXT records. At most once a minute.
  8. GETList a Base Domain's nameserver checks, most recent first. Back-to-back checks with the same result share one entry, from its created_at to its updated_at.
  9. POSTMark a Base Domain's nameservers as updated at the registrar and check them now (at most once a minute)
  10. GETList a Base Domain's DNS records
  11. POSTCreate a Base Domain's DNS record
  12. PUTUpdate a Base Domain's DNS record
  13. DELETEDelete a Base Domain's DNS record
  14. POSTRetry DNS setup for a Base Domain
  15. GETValidate a Base Domain's DNS
  16. POSTTell CloudCannon the optional wildcard record was added at the DNS Provider, so it checks hourly for 7 days. Checks it now, at most once a minute.
  17. POSTTell CloudCannon the wildcard certificate's TXT records were added, so it checks hourly for 7 days. Refreshes the certificate now, at most once a minute.
  18. PUTMigrate a Base Domain to Cloudflare
  19. GETList a Base Domain's Subdomains
  20. POSTAdd a Subdomain to a Base Domain
  21. GETGet a Subdomain. A certificate awaiting validation is refreshed first, at most once an hour.
  22. PUTUpdate a Subdomain's hosting, HTTPS, redirect target or redirect status
  23. DELETEDelete a Subdomain. Its Sites keep their testing domains.
  24. GETList a Subdomain's DNS checks
  25. POSTCheck a Subdomain's DNS now, and refresh its certificate if it isn't active yet. At most once a minute.
  26. POSTReplace or remove the records in CloudCannon DNS that stop a Subdomain reaching CloudCannon
  27. POSTTell CloudCannon a Subdomain's DNS record was changed, so it checks more often until it's found
  28. POSTSend visitors to unknown subdomains of the Base Domain to this Subdomain
  29. POSTRedirect every visitor on a Subdomain to another domain
  30. POSTServe Sites on a Subdomain instead of redirecting
  31. POSTServe a Site on a Subdomain, at its root or under a path
  32. PUTChange the path a Site is served at on a Subdomain
  33. DELETEStop serving a Site on a Subdomain
  34. PUTReplace the Site at a path on a Subdomain in one step
  35. POSTRetry issuing a Subdomain's certificate. At most once a minute.

Get a Base Domain#

GET/api/v0/base-domains/{base_domain_uuid}
Path parameters:
base_domain_uuidUUID | integerRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid} \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "base_domain": "string",
  "uses_dns": true,
  "in_cloudflare_beta": true,
  "cloudflare_dns_migrated": true,
  "cloudflare_zone_id": "string",
  "cloudflare_zone_create_error": "string",
  "cloudflare_zone_create_error_from_cloudflare": true,
  "mx_record": "string",
  "spf_record": "string",
  "minimum_tls_version": "string",
  "fallback_redirect_status": 0,
  "nameservers_updated_at": "2024-01-01T00:00:00Z",
  "dns_live_at": "2024-01-01T00:00:00Z",
  "nameservers_changed_at": "2024-01-01T00:00:00Z",
  "nameserver_nudge_sent_at": "2024-01-01T00:00:00Z",
  "wildcard_record_checked_at": "2024-01-01T00:00:00Z",
  "wildcard_record_found": true,
  "wildcard_record_updated_at": "2024-01-01T00:00:00Z",
  "site_count": 0,
  "subdomain_count": 0,
  "fallback_domain": "string",
  "organisation_uuid": "00000000-0000-0000-0000-000000000000",
  "dns_setup_stage": "external",
  "found_name_servers": [
    "string"
  ],
  "name_servers_checked_at": "2024-01-01T00:00:00Z",
  "name_server_check_failed_at": "2024-01-01T00:00:00Z",
  "missing_mx_records": true,
  "disconnect_blockers": [
    "string"
  ],
  "wildcard_certificate": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "status": "string",
    "ssl_status": "string",
    "validation_method": "string",
    "expires_at": "2024-01-01T00:00:00Z",
    "wildcard": true,
    "checked_at": "2024-01-01T00:00:00Z",
    "dns_updated_at": "2024-01-01T00:00:00Z",
    "dcv_delegation": {
      "name": "string",
      "type": "CNAME",
      "value": "string"
    },
    "dcv_delegated_at": "2024-01-01T00:00:00Z",
    "validation_records": [
      {
        "txt_name": "string",
        "txt_value": "string",
        "found": [],
        "status": "connected"
      }
    ]
  },
  "name_server_checks": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "id": 0,
      "base_domain": "string",
      "base_domain_uuid": "string",
      "found_name_servers": [
        "string"
      ],
      "conclusive": true
    }
  ]
}
Response
401Unauthorized
JSON
Copied to clipboard
{
  "error": "string"
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response

Update a Base Domain's minimum TLS version or fallback redirect status#

PUT/api/v0/base-domains/{base_domain_uuid}
Path parameters:
base_domain_uuidUUID | integerRequired#
Request body:
minimum_tls_versionenum#

The minimum TLS version to enforce. Raising it raises every Subdomain below it; lowering it leaves Subdomains as they are unless lower_subdomains is true.

Allowed values: 1.2 1.3

lower_subdomainsboolean#

When lowering minimum_tls_version, also lower every Subdomain above it, and the wildcard certificate for subdomains that are not set up, to the new minimum.

fallback_redirect_statusenum#

The status code the fallback redirect responds with.

Allowed values: 301 302 307 308

Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid} \
  -X PUT \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "minimum_tls_version": "1.2",
    "lower_subdomains": true,
    "fallback_redirect_status": 301
  }'
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "uuid": "00000000-0000-0000-0000-000000000000",
  "id": 0,
  "base_domain": "string",
  "uses_dns": true,
  "in_cloudflare_beta": true,
  "cloudflare_dns_migrated": true,
  "cloudflare_zone_id": "string",
  "cloudflare_zone_create_error": "string",
  "cloudflare_zone_create_error_from_cloudflare": true,
  "mx_record": "string",
  "spf_record": "string",
  "minimum_tls_version": "string",
  "fallback_redirect_status": 0,
  "cloudflare_name_servers": [
    "string"
  ],
  "name_servers": [
    "string"
  ],
  "cloudflare_dns_migration": [
    {}
  ],
  "a_record": [
    {
      "subdomain": "string",
      "target": "string"
    }
  ],
  "cname_record": [
    {
      "subdomain": "string",
      "target": "string"
    }
  ],
  "txt_record": [
    {
      "subdomain": "string",
      "target": "string"
    }
  ]
}
Response
401Unauthorized
JSON
Copied to clipboard
{
  "error": "string"
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Delete a Base Domain#

DELETE/api/v0/base-domains/{base_domain_uuid}
Path parameters:
base_domain_uuidUUID | integerRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid} \
  -X DELETE \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
204Deleted
401Unauthorized
JSON
Copied to clipboard
{
  "error": "string"
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Get a Base Domain's DNS status#

GET/api/v0/base-domains/{base_domain_uuid}/dns
Path parameters:
base_domain_uuidUUID | integerRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/dns \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "success": true,
  "status": 0,
  "answers": [
    "string"
  ],
  "error_message": "string"
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response

Enable DNS management for a Base Domain#

POST/api/v0/base-domains/{base_domain_uuid}/dns
Path parameters:
base_domain_uuidUUIDRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/dns \
  -X POST \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
201Created
JSON
Copied to clipboard
{
  "base_domain": "string",
  "uses_dns": true,
  "in_cloudflare_beta": true,
  "cloudflare_dns_migrated": true,
  "cloudflare_zone_id": "string",
  "cloudflare_zone_create_error": "string",
  "cloudflare_zone_create_error_from_cloudflare": true,
  "mx_record": "string",
  "spf_record": "string",
  "minimum_tls_version": "string",
  "fallback_redirect_status": 0,
  "nameservers_updated_at": "2024-01-01T00:00:00Z",
  "dns_live_at": "2024-01-01T00:00:00Z",
  "nameservers_changed_at": "2024-01-01T00:00:00Z",
  "nameserver_nudge_sent_at": "2024-01-01T00:00:00Z",
  "wildcard_record_checked_at": "2024-01-01T00:00:00Z",
  "wildcard_record_found": true,
  "wildcard_record_updated_at": "2024-01-01T00:00:00Z",
  "site_count": 0,
  "subdomain_count": 0,
  "fallback_domain": "string",
  "organisation_uuid": "00000000-0000-0000-0000-000000000000",
  "dns_setup_stage": "external",
  "found_name_servers": [
    "string"
  ],
  "name_servers_checked_at": "2024-01-01T00:00:00Z",
  "name_server_check_failed_at": "2024-01-01T00:00:00Z",
  "missing_mx_records": true,
  "disconnect_blockers": [
    "string"
  ],
  "wildcard_certificate": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "status": "string",
    "ssl_status": "string",
    "validation_method": "string",
    "expires_at": "2024-01-01T00:00:00Z",
    "wildcard": true,
    "checked_at": "2024-01-01T00:00:00Z",
    "dns_updated_at": "2024-01-01T00:00:00Z",
    "dcv_delegation": {
      "name": "string",
      "type": "CNAME",
      "value": "string"
    },
    "dcv_delegated_at": "2024-01-01T00:00:00Z",
    "validation_records": [
      {
        "txt_name": "string",
        "txt_value": "string",
        "found": [],
        "status": "connected"
      }
    ]
  },
  "name_server_checks": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "id": 0,
      "base_domain": "string",
      "base_domain_uuid": "string",
      "found_name_servers": [
        "string"
      ],
      "conclusive": true
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Disable DNS management for a Base Domain#

DELETE/api/v0/base-domains/{base_domain_uuid}/dns
Path parameters:
base_domain_uuidUUIDRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/dns \
  -X DELETE \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200Removed
JSON
Copied to clipboard
{
  "base_domain": "string",
  "uses_dns": true,
  "in_cloudflare_beta": true,
  "cloudflare_dns_migrated": true,
  "cloudflare_zone_id": "string",
  "cloudflare_zone_create_error": "string",
  "cloudflare_zone_create_error_from_cloudflare": true,
  "mx_record": "string",
  "spf_record": "string",
  "minimum_tls_version": "string",
  "fallback_redirect_status": 0,
  "nameservers_updated_at": "2024-01-01T00:00:00Z",
  "dns_live_at": "2024-01-01T00:00:00Z",
  "nameservers_changed_at": "2024-01-01T00:00:00Z",
  "nameserver_nudge_sent_at": "2024-01-01T00:00:00Z",
  "wildcard_record_checked_at": "2024-01-01T00:00:00Z",
  "wildcard_record_found": true,
  "wildcard_record_updated_at": "2024-01-01T00:00:00Z",
  "site_count": 0,
  "subdomain_count": 0,
  "fallback_domain": "string",
  "organisation_uuid": "00000000-0000-0000-0000-000000000000",
  "dns_setup_stage": "external",
  "found_name_servers": [
    "string"
  ],
  "name_servers_checked_at": "2024-01-01T00:00:00Z",
  "name_server_check_failed_at": "2024-01-01T00:00:00Z",
  "missing_mx_records": true,
  "disconnect_blockers": [
    "string"
  ],
  "wildcard_certificate": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "status": "string",
    "ssl_status": "string",
    "validation_method": "string",
    "expires_at": "2024-01-01T00:00:00Z",
    "wildcard": true,
    "checked_at": "2024-01-01T00:00:00Z",
    "dns_updated_at": "2024-01-01T00:00:00Z",
    "dcv_delegation": {
      "name": "string",
      "type": "CNAME",
      "value": "string"
    },
    "dcv_delegated_at": "2024-01-01T00:00:00Z",
    "validation_records": [
      {
        "txt_name": "string",
        "txt_value": "string",
        "found": [],
        "status": "connected"
      }
    ]
  },
  "name_server_checks": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "id": 0,
      "base_domain": "string",
      "base_domain_uuid": "string",
      "found_name_servers": [
        "string"
      ],
      "conclusive": true
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Check a Base Domain's nameservers now, and on External DNS its wildcard record and its wildcard certificate's TXT records. At most once a minute.#

POST/api/v0/base-domains/{base_domain_uuid}/dns/check
Path parameters:
base_domain_uuidUUIDRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/dns/check \
  -X POST \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "base_domain": "string",
  "uses_dns": true,
  "in_cloudflare_beta": true,
  "cloudflare_dns_migrated": true,
  "cloudflare_zone_id": "string",
  "cloudflare_zone_create_error": "string",
  "cloudflare_zone_create_error_from_cloudflare": true,
  "mx_record": "string",
  "spf_record": "string",
  "minimum_tls_version": "string",
  "fallback_redirect_status": 0,
  "nameservers_updated_at": "2024-01-01T00:00:00Z",
  "dns_live_at": "2024-01-01T00:00:00Z",
  "nameservers_changed_at": "2024-01-01T00:00:00Z",
  "nameserver_nudge_sent_at": "2024-01-01T00:00:00Z",
  "wildcard_record_checked_at": "2024-01-01T00:00:00Z",
  "wildcard_record_found": true,
  "wildcard_record_updated_at": "2024-01-01T00:00:00Z",
  "site_count": 0,
  "subdomain_count": 0,
  "fallback_domain": "string",
  "organisation_uuid": "00000000-0000-0000-0000-000000000000",
  "dns_setup_stage": "external",
  "found_name_servers": [
    "string"
  ],
  "name_servers_checked_at": "2024-01-01T00:00:00Z",
  "name_server_check_failed_at": "2024-01-01T00:00:00Z",
  "missing_mx_records": true,
  "disconnect_blockers": [
    "string"
  ],
  "wildcard_certificate": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "status": "string",
    "ssl_status": "string",
    "validation_method": "string",
    "expires_at": "2024-01-01T00:00:00Z",
    "wildcard": true,
    "checked_at": "2024-01-01T00:00:00Z",
    "dns_updated_at": "2024-01-01T00:00:00Z",
    "dcv_delegation": {
      "name": "string",
      "type": "CNAME",
      "value": "string"
    },
    "dcv_delegated_at": "2024-01-01T00:00:00Z",
    "validation_records": [
      {
        "txt_name": "string",
        "txt_value": "string",
        "found": [],
        "status": "connected"
      }
    ]
  },
  "name_server_checks": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "id": 0,
      "base_domain": "string",
      "base_domain_uuid": "string",
      "found_name_servers": [
        "string"
      ],
      "conclusive": true
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

List a Base Domain's nameserver checks, most recent first. Back-to-back checks with the same result share one entry, from its created_at to its updated_at.#

GET/api/v0/base-domains/{base_domain_uuid}/dns/checks
Path parameters:
base_domain_uuidUUID | integerRequired#
Pagination:
pageinteger#

Page number to fetch (1-indexed)

itemsinteger#

Number of items per page

Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/dns/checks \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "id": 0,
    "base_domain": "string",
    "base_domain_uuid": "string",
    "found_name_servers": [
      "string"
    ],
    "conclusive": true
  }
]
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response

Mark a Base Domain's nameservers as updated at the registrar and check them now (at most once a minute)#

POST/api/v0/base-domains/{base_domain_uuid}/dns/nameservers-updated
Path parameters:
base_domain_uuidUUIDRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/dns/nameservers-updated \
  -X POST \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "base_domain": "string",
  "uses_dns": true,
  "in_cloudflare_beta": true,
  "cloudflare_dns_migrated": true,
  "cloudflare_zone_id": "string",
  "cloudflare_zone_create_error": "string",
  "cloudflare_zone_create_error_from_cloudflare": true,
  "mx_record": "string",
  "spf_record": "string",
  "minimum_tls_version": "string",
  "fallback_redirect_status": 0,
  "nameservers_updated_at": "2024-01-01T00:00:00Z",
  "dns_live_at": "2024-01-01T00:00:00Z",
  "nameservers_changed_at": "2024-01-01T00:00:00Z",
  "nameserver_nudge_sent_at": "2024-01-01T00:00:00Z",
  "wildcard_record_checked_at": "2024-01-01T00:00:00Z",
  "wildcard_record_found": true,
  "wildcard_record_updated_at": "2024-01-01T00:00:00Z",
  "site_count": 0,
  "subdomain_count": 0,
  "fallback_domain": "string",
  "organisation_uuid": "00000000-0000-0000-0000-000000000000",
  "dns_setup_stage": "external",
  "found_name_servers": [
    "string"
  ],
  "name_servers_checked_at": "2024-01-01T00:00:00Z",
  "name_server_check_failed_at": "2024-01-01T00:00:00Z",
  "missing_mx_records": true,
  "disconnect_blockers": [
    "string"
  ],
  "wildcard_certificate": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "status": "string",
    "ssl_status": "string",
    "validation_method": "string",
    "expires_at": "2024-01-01T00:00:00Z",
    "wildcard": true,
    "checked_at": "2024-01-01T00:00:00Z",
    "dns_updated_at": "2024-01-01T00:00:00Z",
    "dcv_delegation": {
      "name": "string",
      "type": "CNAME",
      "value": "string"
    },
    "dcv_delegated_at": "2024-01-01T00:00:00Z",
    "validation_records": [
      {
        "txt_name": "string",
        "txt_value": "string",
        "found": [],
        "status": "connected"
      }
    ]
  },
  "name_server_checks": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "id": 0,
      "base_domain": "string",
      "base_domain_uuid": "string",
      "found_name_servers": [
        "string"
      ],
      "conclusive": true
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

List a Base Domain's DNS records#

GET/api/v0/base-domains/{base_domain_uuid}/dns/records
Path parameters:
base_domain_uuidUUID | integerRequired#
Filters:
searchstring#

Filter DNS records by a search term

Pagination:
pageinteger#

Page number to fetch (1-indexed)

itemsinteger#

Number of items per page

Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/dns/records \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
[
  {
    "content": "string",
    "created_on": "2024-01-01T00:00:00Z",
    "id": "string",
    "locked": true,
    "meta": {},
    "modified_on": "2024-01-01T00:00:00Z",
    "name": "string",
    "proxiable": true,
    "proxied": true,
    "ttl": 0,
    "type": "string",
    "zone_id": "string",
    "zone_name": "string"
  }
]
Response
401Unauthorized
JSON
Copied to clipboard
{
  "error": "string"
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Create a Base Domain's DNS record#

POST/api/v0/base-domains/{base_domain_uuid}/dns/records
Path parameters:
base_domain_uuidUUIDRequired#
Request body:
typestring#
namestring#
ttlinteger#
dataobject#
commentstring#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/dns/records \
  -X POST \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "string",
    "name": "string",
    "ttl": 0,
    "data": {
      "comment": "string"
    }
  }'
Terminal
Responses:
201Created
JSON
Copied to clipboard
{
  "content": "string",
  "created_on": "2024-01-01T00:00:00Z",
  "id": "string",
  "locked": true,
  "meta": {},
  "modified_on": "2024-01-01T00:00:00Z",
  "name": "string",
  "proxiable": true,
  "proxied": true,
  "ttl": 0,
  "type": "string",
  "zone_id": "string",
  "zone_name": "string"
}
Response
401Unauthorized
JSON
Copied to clipboard
{
  "error": "string"
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Update a Base Domain's DNS record#

PUT/api/v0/base-domains/{base_domain_uuid}/dns/records/{record_id}
Path parameters:
base_domain_uuidUUIDRequired#
record_idstringRequired#
Request body:
typestring#
namestring#
ttlinteger#
dataobject#
commentstring#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/dns/records/{record_id} \
  -X PUT \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "string",
    "name": "string",
    "ttl": 0,
    "data": {
      "comment": "string"
    }
  }'
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "content": "string",
  "created_on": "2024-01-01T00:00:00Z",
  "id": "string",
  "locked": true,
  "meta": {},
  "modified_on": "2024-01-01T00:00:00Z",
  "name": "string",
  "proxiable": true,
  "proxied": true,
  "ttl": 0,
  "type": "string",
  "zone_id": "string",
  "zone_name": "string"
}
Response
401Unauthorized
JSON
Copied to clipboard
{
  "error": "string"
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Delete a Base Domain's DNS record#

DELETE/api/v0/base-domains/{base_domain_uuid}/dns/records/{record_id}
Path parameters:
base_domain_uuidUUIDRequired#
record_idstringRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/dns/records/{record_id} \
  -X DELETE \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
204Deleted
401Unauthorized
JSON
Copied to clipboard
{
  "error": "string"
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Retry DNS setup for a Base Domain#

POST/api/v0/base-domains/{base_domain_uuid}/dns/retry
Path parameters:
base_domain_uuidUUIDRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/dns/retry \
  -X POST \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "base_domain": "string",
  "uses_dns": true,
  "in_cloudflare_beta": true,
  "cloudflare_dns_migrated": true,
  "cloudflare_zone_id": "string",
  "cloudflare_zone_create_error": "string",
  "cloudflare_zone_create_error_from_cloudflare": true,
  "mx_record": "string",
  "spf_record": "string",
  "minimum_tls_version": "string",
  "fallback_redirect_status": 0,
  "nameservers_updated_at": "2024-01-01T00:00:00Z",
  "dns_live_at": "2024-01-01T00:00:00Z",
  "nameservers_changed_at": "2024-01-01T00:00:00Z",
  "nameserver_nudge_sent_at": "2024-01-01T00:00:00Z",
  "wildcard_record_checked_at": "2024-01-01T00:00:00Z",
  "wildcard_record_found": true,
  "wildcard_record_updated_at": "2024-01-01T00:00:00Z",
  "site_count": 0,
  "subdomain_count": 0,
  "fallback_domain": "string",
  "organisation_uuid": "00000000-0000-0000-0000-000000000000",
  "dns_setup_stage": "external",
  "found_name_servers": [
    "string"
  ],
  "name_servers_checked_at": "2024-01-01T00:00:00Z",
  "name_server_check_failed_at": "2024-01-01T00:00:00Z",
  "missing_mx_records": true,
  "disconnect_blockers": [
    "string"
  ],
  "wildcard_certificate": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "status": "string",
    "ssl_status": "string",
    "validation_method": "string",
    "expires_at": "2024-01-01T00:00:00Z",
    "wildcard": true,
    "checked_at": "2024-01-01T00:00:00Z",
    "dns_updated_at": "2024-01-01T00:00:00Z",
    "dcv_delegation": {
      "name": "string",
      "type": "CNAME",
      "value": "string"
    },
    "dcv_delegated_at": "2024-01-01T00:00:00Z",
    "validation_records": [
      {
        "txt_name": "string",
        "txt_value": "string",
        "found": [],
        "status": "connected"
      }
    ]
  },
  "name_server_checks": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "id": 0,
      "base_domain": "string",
      "base_domain_uuid": "string",
      "found_name_servers": [
        "string"
      ],
      "conclusive": true
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Validate a Base Domain's DNS#

GET/api/v0/base-domains/{base_domain_uuid}/dns/validate
Path parameters:
base_domain_uuidUUIDRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/dns/validate \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "valid": true
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Tell CloudCannon the optional wildcard record was added at the DNS Provider, so it checks hourly for 7 days. Checks it now, at most once a minute.#

POST/api/v0/base-domains/{base_domain_uuid}/dns/wildcard-record-updated
Path parameters:
base_domain_uuidUUIDRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/dns/wildcard-record-updated \
  -X POST \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "base_domain": "string",
  "uses_dns": true,
  "in_cloudflare_beta": true,
  "cloudflare_dns_migrated": true,
  "cloudflare_zone_id": "string",
  "cloudflare_zone_create_error": "string",
  "cloudflare_zone_create_error_from_cloudflare": true,
  "mx_record": "string",
  "spf_record": "string",
  "minimum_tls_version": "string",
  "fallback_redirect_status": 0,
  "nameservers_updated_at": "2024-01-01T00:00:00Z",
  "dns_live_at": "2024-01-01T00:00:00Z",
  "nameservers_changed_at": "2024-01-01T00:00:00Z",
  "nameserver_nudge_sent_at": "2024-01-01T00:00:00Z",
  "wildcard_record_checked_at": "2024-01-01T00:00:00Z",
  "wildcard_record_found": true,
  "wildcard_record_updated_at": "2024-01-01T00:00:00Z",
  "site_count": 0,
  "subdomain_count": 0,
  "fallback_domain": "string",
  "organisation_uuid": "00000000-0000-0000-0000-000000000000",
  "dns_setup_stage": "external",
  "found_name_servers": [
    "string"
  ],
  "name_servers_checked_at": "2024-01-01T00:00:00Z",
  "name_server_check_failed_at": "2024-01-01T00:00:00Z",
  "missing_mx_records": true,
  "disconnect_blockers": [
    "string"
  ],
  "wildcard_certificate": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "status": "string",
    "ssl_status": "string",
    "validation_method": "string",
    "expires_at": "2024-01-01T00:00:00Z",
    "wildcard": true,
    "checked_at": "2024-01-01T00:00:00Z",
    "dns_updated_at": "2024-01-01T00:00:00Z",
    "dcv_delegation": {
      "name": "string",
      "type": "CNAME",
      "value": "string"
    },
    "dcv_delegated_at": "2024-01-01T00:00:00Z",
    "validation_records": [
      {
        "txt_name": "string",
        "txt_value": "string",
        "found": [],
        "status": "connected"
      }
    ]
  },
  "name_server_checks": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "id": 0,
      "base_domain": "string",
      "base_domain_uuid": "string",
      "found_name_servers": [
        "string"
      ],
      "conclusive": true
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Tell CloudCannon the wildcard certificate's TXT records were added, so it checks hourly for 7 days. Refreshes the certificate now, at most once a minute.#

POST/api/v0/base-domains/{base_domain_uuid}/dns/wildcard-updated
Path parameters:
base_domain_uuidUUIDRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/dns/wildcard-updated \
  -X POST \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "base_domain": "string",
  "uses_dns": true,
  "in_cloudflare_beta": true,
  "cloudflare_dns_migrated": true,
  "cloudflare_zone_id": "string",
  "cloudflare_zone_create_error": "string",
  "cloudflare_zone_create_error_from_cloudflare": true,
  "mx_record": "string",
  "spf_record": "string",
  "minimum_tls_version": "string",
  "fallback_redirect_status": 0,
  "nameservers_updated_at": "2024-01-01T00:00:00Z",
  "dns_live_at": "2024-01-01T00:00:00Z",
  "nameservers_changed_at": "2024-01-01T00:00:00Z",
  "nameserver_nudge_sent_at": "2024-01-01T00:00:00Z",
  "wildcard_record_checked_at": "2024-01-01T00:00:00Z",
  "wildcard_record_found": true,
  "wildcard_record_updated_at": "2024-01-01T00:00:00Z",
  "site_count": 0,
  "subdomain_count": 0,
  "fallback_domain": "string",
  "organisation_uuid": "00000000-0000-0000-0000-000000000000",
  "dns_setup_stage": "external",
  "found_name_servers": [
    "string"
  ],
  "name_servers_checked_at": "2024-01-01T00:00:00Z",
  "name_server_check_failed_at": "2024-01-01T00:00:00Z",
  "missing_mx_records": true,
  "disconnect_blockers": [
    "string"
  ],
  "wildcard_certificate": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "status": "string",
    "ssl_status": "string",
    "validation_method": "string",
    "expires_at": "2024-01-01T00:00:00Z",
    "wildcard": true,
    "checked_at": "2024-01-01T00:00:00Z",
    "dns_updated_at": "2024-01-01T00:00:00Z",
    "dcv_delegation": {
      "name": "string",
      "type": "CNAME",
      "value": "string"
    },
    "dcv_delegated_at": "2024-01-01T00:00:00Z",
    "validation_records": [
      {
        "txt_name": "string",
        "txt_value": "string",
        "found": [],
        "status": "connected"
      }
    ]
  },
  "name_server_checks": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "id": 0,
      "base_domain": "string",
      "base_domain_uuid": "string",
      "found_name_servers": [
        "string"
      ],
      "conclusive": true
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Migrate a Base Domain to Cloudflare#

PUT/api/v0/base-domains/{base_domain_uuid}/migrate
Path parameters:
base_domain_uuidUUID | integerRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/migrate \
  -X PUT \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "base_domain": "string",
  "uses_dns": true,
  "in_cloudflare_beta": true,
  "cloudflare_dns_migrated": true,
  "cloudflare_zone_id": "string",
  "cloudflare_zone_create_error": "string",
  "cloudflare_zone_create_error_from_cloudflare": true,
  "mx_record": "string",
  "spf_record": "string",
  "minimum_tls_version": "string",
  "fallback_redirect_status": 0,
  "nameservers_updated_at": "2024-01-01T00:00:00Z",
  "dns_live_at": "2024-01-01T00:00:00Z",
  "nameservers_changed_at": "2024-01-01T00:00:00Z",
  "nameserver_nudge_sent_at": "2024-01-01T00:00:00Z",
  "wildcard_record_checked_at": "2024-01-01T00:00:00Z",
  "wildcard_record_found": true,
  "wildcard_record_updated_at": "2024-01-01T00:00:00Z",
  "site_count": 0,
  "subdomain_count": 0,
  "fallback_domain": "string",
  "organisation_uuid": "00000000-0000-0000-0000-000000000000",
  "dns_setup_stage": "external",
  "found_name_servers": [
    "string"
  ],
  "name_servers_checked_at": "2024-01-01T00:00:00Z",
  "name_server_check_failed_at": "2024-01-01T00:00:00Z",
  "missing_mx_records": true,
  "disconnect_blockers": [
    "string"
  ],
  "wildcard_certificate": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "status": "string",
    "ssl_status": "string",
    "validation_method": "string",
    "expires_at": "2024-01-01T00:00:00Z",
    "wildcard": true,
    "checked_at": "2024-01-01T00:00:00Z",
    "dns_updated_at": "2024-01-01T00:00:00Z",
    "dcv_delegation": {
      "name": "string",
      "type": "CNAME",
      "value": "string"
    },
    "dcv_delegated_at": "2024-01-01T00:00:00Z",
    "validation_records": [
      {
        "txt_name": "string",
        "txt_value": "string",
        "found": [],
        "status": "connected"
      }
    ]
  },
  "name_server_checks": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "id": 0,
      "base_domain": "string",
      "base_domain_uuid": "string",
      "found_name_servers": [
        "string"
      ],
      "conclusive": true
    }
  ]
}
Response
401Unauthorized
JSON
Copied to clipboard
{
  "error": "string"
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

List a Base Domain's Subdomains#

GET/api/v0/base-domains/{base_domain_uuid}/subdomains
Path parameters:
base_domain_uuidUUID | integerRequired#
Filters:
searchstring#

Filter Subdomains by a search term

sortstring#

Sort by name, name descending, newest first, or those needing attention first

Allowed values: name -name -created_at attention

serving_modestring#

Comma-separated serving modes: site, redirect

hosting_choicestring#

Comma-separated hosting choices: cloudcannon, cloudflare, origin

https_statestring#

Comma-separated HTTPS states: active, issuing, renewing, expired, failed, none

dns_record_statusstring#

Comma-separated DNS record statuses: connected, not_pointing, no_record, unchecked

attentionstring#

true lists only Subdomains needing attention (a DNS problem, no site, or a certificate problem); false lists the rest

Pagination:
pageinteger#

Page number to fetch (1-indexed)

itemsinteger#

Number of items per page

Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "id": 0,
    "domain_name": "string",
    "serving_mode": "string",
    "ingress": "string",
    "force_ssl": true,
    "auto_generate_ssl": true,
    "auto_generate_ssl_failures": 0,
    "next_ssl_generate_attempt_at": "2024-01-01T00:00:00Z",
    "ssl_certificate_id": 0,
    "min_tls_version": "string",
    "priority_domain_at": "2024-01-01T00:00:00Z",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "dns_updated_at": "2024-01-01T00:00:00Z",
    "dns_live_at": "2024-01-01T00:00:00Z",
    "dns_changed_at": "2024-01-01T00:00:00Z",
    "dns_stuck_sent_at": "2024-01-01T00:00:00Z",
    "dns_reset_at": "2024-01-01T00:00:00Z",
    "redirect_target": "string",
    "redirect_status": 301,
    "hosting_choice": "string",
    "is_fallback": true,
    "ssl_certificate_expires_at": "2024-01-01T00:00:00Z",
    "auto_generate_ssl_max_failures": 0,
    "auto_generate_ssl_error_code": "string",
    "auto_generate_ssl_errored_at": "2024-01-01T00:00:00Z",
    "sites": [
      {
        "uuid": "00000000-0000-0000-0000-000000000000",
        "id": 0,
        "site_name": "string",
        "subpath": "string",
        "project_uuid": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "latest_check": {
      "status": 0,
      "connection_test_status": 0,
      "first_answer": "string",
      "answers": [
        "string"
      ],
      "error_message": "string",
      "checked_at": "2024-01-01T00:00:00Z"
    },
    "meets_minimum_tls": true,
    "dns_record_status": "connected",
    "check_failed_at": "2024-01-01T00:00:00Z",
    "expected_dns_records": [
      {
        "type": "string",
        "content": "string"
      }
    ],
    "found_dns_records": [
      {
        "type": "string",
        "content": "string"
      }
    ],
    "served_by_zone_wildcard": true,
    "ssl_certificate_issued_at": "2024-01-01T00:00:00Z",
    "cloudflare": {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "status": "string",
      "ssl_status": "string",
      "validation_method": "string",
      "expires_at": "2024-01-01T00:00:00Z",
      "wildcard": true,
      "checked_at": "2024-01-01T00:00:00Z",
      "error": "string",
      "ownership_record": {},
      "validation_records": [
        {}
      ],
      "txt_found": {},
      "dcv_delegation": {
        "name": "string",
        "type": "CNAME",
        "value": "string"
      },
      "dcv_delegated_at": "2024-01-01T00:00:00Z",
      "recreated_at": "2024-01-01T00:00:00Z"
    }
  }
]
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response

Add a Subdomain to a Base Domain#

POST/api/v0/base-domains/{base_domain_uuid}/subdomains
Path parameters:
base_domain_uuidUUID | integerRequired#
Request body:
hosting_choiceenum#

Allowed values: cloudcannon cloudflare origin

force_sslboolean#
auto_generate_sslboolean#
ssl_certificate_idintegerNullable#
redirect_targetstring#
redirect_statusenum#

The status code a redirect Subdomain responds with. Defaults to 301.

Allowed values: 301 302 307 308

min_tls_versionenum#

The oldest TLS version the Subdomain accepts, for every hosting_choice. Defaults to, and can't be below, the Base Domain's minimum_tls_version. On the Base Domain itself it also applies to subdomains that are not set up.

Allowed values: 1.2 1.3

domain_namestringRequired#

The full subdomain, e.g. www.example.com, on this Base Domain.

serving_modeenum#

Allowed values: site redirect

site_uuidstring (uuid)#

A Site to serve on the new Subdomain.

subpathstringNullable#
accept_billing_increaseboolean#
previous_thenenum#

When the Site is the last one on the domain it leaves: leave that domain set up without a Site (the default), redirect it to previous_redirect_target, or delete it.

Allowed values: leave redirect delete

previous_redirect_targetstring#

Where to redirect the domain the Site leaves.

previous_delete_redirectsArray<UUID>#

Subdomains that redirect to the domain the Site leaves, to delete with it.

Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains \
  -X POST \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "hosting_choice": "cloudcannon",
    "force_ssl": true,
    "auto_generate_ssl": true,
    "ssl_certificate_id": 0,
    "redirect_target": "string",
    "redirect_status": 301,
    "min_tls_version": "1.2",
    "domain_name": "string",
    "serving_mode": "site",
    "site_uuid": "00000000-0000-0000-0000-000000000000",
    "subpath": "string",
    "accept_billing_increase": true,
    "previous_then": "leave",
    "previous_redirect_target": "string",
    "previous_delete_redirects": [
      "00000000-0000-0000-0000-000000000000"
    ]
  }'
Terminal
Responses:
201Created
JSON
Copied to clipboard
{
  "redirects_here": [
    "string"
  ],
  "redirects_here_details": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "domain_name": "string",
      "base_domain_uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
Response
402PaymentConfirmRequired
JSON
Copied to clipboard
{
  "errors": {}
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Get a Subdomain. A certificate awaiting validation is refreshed first, at most once an hour.#

GET/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid} \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "redirects_here": [
    "string"
  ],
  "redirects_here_details": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "domain_name": "string",
      "base_domain_uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response

Update a Subdomain's hosting, HTTPS, redirect target or redirect status#

PUT/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
Request body:
hosting_choiceenum#

Allowed values: cloudcannon cloudflare origin

force_sslboolean#
auto_generate_sslboolean#
ssl_certificate_idintegerNullable#
redirect_targetstring#
redirect_statusenum#

The status code a redirect Subdomain responds with. Defaults to 301.

Allowed values: 301 302 307 308

min_tls_versionenum#

The oldest TLS version the Subdomain accepts, for every hosting_choice. Defaults to, and can't be below, the Base Domain's minimum_tls_version. On the Base Domain itself it also applies to subdomains that are not set up.

Allowed values: 1.2 1.3

validation_methodenum#

How Cloudflare validates the certificate. txt validates before DNS points at CloudCannon. The base domain's own wildcard certificate is always txt.

Allowed values: http txt

Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid} \
  -X PUT \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "hosting_choice": "cloudcannon",
    "force_ssl": true,
    "auto_generate_ssl": true,
    "ssl_certificate_id": 0,
    "redirect_target": "string",
    "redirect_status": 301,
    "min_tls_version": "1.2",
    "validation_method": "http"
  }'
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "redirects_here": [
    "string"
  ],
  "redirects_here_details": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "domain_name": "string",
      "base_domain_uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Delete a Subdomain. Its Sites keep their testing domains.#

DELETE/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
Request body:
delete_redirectsArray<UUID>#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid} \
  -X DELETE \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "delete_redirects": [
      "00000000-0000-0000-0000-000000000000"
    ]
  }'
Terminal
Responses:
204No Content
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

List a Subdomain's DNS checks#

GET/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/checks
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
Pagination:
pageinteger#

Page number to fetch (1-indexed)

itemsinteger#

Number of items per page

Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/checks \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "id": 0,
    "status": 0,
    "first_answer": "string",
    "connection_test_status": 0,
    "answers": "string",
    "error_message": "string",
    "domain_name_checked": "string",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "subdomain_uuid": "00000000-0000-0000-0000-000000000000",
    "base_domain_uuid": "00000000-0000-0000-0000-000000000000",
    "conclusive": true,
    "dns_record_status": "connected"
  }
]
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response

Check a Subdomain's DNS now, and refresh its certificate if it isn't active yet. At most once a minute.#

POST/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/checks
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/checks \
  -X POST \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "redirects_here": [
    "string"
  ],
  "redirects_here_details": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "domain_name": "string",
      "base_domain_uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Replace or remove the records in CloudCannon DNS that stop a Subdomain reaching CloudCannon#

POST/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/dns/fix
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/dns/fix \
  -X POST \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "redirects_here": [
    "string"
  ],
  "redirects_here_details": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "domain_name": "string",
      "base_domain_uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Tell CloudCannon a Subdomain's DNS record was changed, so it checks more often until it's found#

POST/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/dns/updated
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/dns/updated \
  -X POST \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "redirects_here": [
    "string"
  ],
  "redirects_here_details": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "domain_name": "string",
      "base_domain_uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response

Send visitors to unknown subdomains of the Base Domain to this Subdomain#

POST/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/fallback
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/fallback \
  -X POST \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "redirects_here": [
    "string"
  ],
  "redirects_here_details": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "domain_name": "string",
      "base_domain_uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Redirect every visitor on a Subdomain to another domain#

POST/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/redirect
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
Request body:
redirect_targetstringRequired#
redirect_statusenum#

The status code a redirect Subdomain responds with. Defaults to 301.

Allowed values: 301 302 307 308

Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/redirect \
  -X POST \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_target": "string",
    "redirect_status": 301
  }'
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "redirects_here": [
    "string"
  ],
  "redirects_here_details": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "domain_name": "string",
      "base_domain_uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Serve Sites on a Subdomain instead of redirecting#

POST/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/site
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
Request body:
site_uuidUUID#
subpathstringNullable#
accept_billing_increaseboolean#
previous_thenenum#

When the Site is the last one on the domain it leaves: leave that domain set up without a Site (the default), redirect it to previous_redirect_target, or delete it.

Allowed values: leave redirect delete

previous_redirect_targetstring#

Where to redirect the domain the Site leaves.

previous_delete_redirectsArray<UUID>#

Subdomains that redirect to the domain the Site leaves, to delete with it.

Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/site \
  -X POST \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "site_uuid": "00000000-0000-0000-0000-000000000000",
    "subpath": "string",
    "accept_billing_increase": true,
    "previous_then": "leave",
    "previous_redirect_target": "string",
    "previous_delete_redirects": [
      "00000000-0000-0000-0000-000000000000"
    ]
  }'
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "redirects_here": [
    "string"
  ],
  "redirects_here_details": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "domain_name": "string",
      "base_domain_uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
Response
402PaymentConfirmRequired
JSON
Copied to clipboard
{
  "errors": {}
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Serve a Site on a Subdomain, at its root or under a path#

POST/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/sites
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
Request body:
site_uuidUUIDRequired#
subpathstringNullable#
accept_billing_increaseboolean#
previous_thenenum#

When the Site is the last one on the domain it leaves: leave that domain set up without a Site (the default), redirect it to previous_redirect_target, or delete it.

Allowed values: leave redirect delete

previous_redirect_targetstring#

Where to redirect the domain the Site leaves.

previous_delete_redirectsArray<UUID>#

Subdomains that redirect to the domain the Site leaves, to delete with it.

Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/sites \
  -X POST \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "site_uuid": "00000000-0000-0000-0000-000000000000",
    "subpath": "string",
    "accept_billing_increase": true,
    "previous_then": "leave",
    "previous_redirect_target": "string",
    "previous_delete_redirects": [
      "00000000-0000-0000-0000-000000000000"
    ]
  }'
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "redirects_here": [
    "string"
  ],
  "redirects_here_details": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "domain_name": "string",
      "base_domain_uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
Response
402PaymentConfirmRequired
JSON
Copied to clipboard
{
  "errors": {}
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Change the path a Site is served at on a Subdomain#

PUT/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/sites/{site_uuid}
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
site_uuidUUIDRequired#
Request body:
subpathstringNullable#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/sites/{site_uuid} \
  -X PUT \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "subpath": "string"
  }'
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "redirects_here": [
    "string"
  ],
  "redirects_here_details": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "domain_name": "string",
      "base_domain_uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Stop serving a Site on a Subdomain#

DELETE/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/sites/{site_uuid}
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
site_uuidUUIDRequired#
Request body:
thenenum#

When the Site is the last one on the domain it leaves: leave that domain set up without a Site (the default), redirect it to redirect_target, or delete it.

Allowed values: leave redirect delete

redirect_targetstring#

Where to redirect the domain the Site leaves.

delete_redirectsArray<UUID>#

Subdomains that redirect to the domain the Site leaves, to delete with it.

Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/sites/{site_uuid} \
  -X DELETE \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "then": "leave",
    "redirect_target": "string",
    "delete_redirects": [
      "00000000-0000-0000-0000-000000000000"
    ]
  }'
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "redirects_here": [
    "string"
  ],
  "redirects_here_details": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "domain_name": "string",
      "base_domain_uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
Response
204No Content
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Replace the Site at a path on a Subdomain in one step#

PUT/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/sites/{site_uuid}/swap
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
site_uuidUUIDRequired#
Request body:
replacement_site_uuidUUIDRequired#
previous_thenenum#

When the Site is the last one on the domain it leaves: leave that domain set up without a Site (the default), redirect it to previous_redirect_target, or delete it.

Allowed values: leave redirect delete

previous_redirect_targetstring#

Where to redirect the domain the Site leaves.

previous_delete_redirectsArray<UUID>#

Subdomains that redirect to the domain the Site leaves, to delete with it.

Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/sites/{site_uuid}/swap \
  -X PUT \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "replacement_site_uuid": "00000000-0000-0000-0000-000000000000",
    "previous_then": "leave",
    "previous_redirect_target": "string",
    "previous_delete_redirects": [
      "00000000-0000-0000-0000-000000000000"
    ]
  }'
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "redirects_here": [
    "string"
  ],
  "redirects_here_details": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "domain_name": "string",
      "base_domain_uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response

Retry issuing a Subdomain's certificate. At most once a minute.#

POST/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/ssl/retry
Path parameters:
base_domain_uuidUUID | integerRequired#
subdomain_uuidUUIDRequired#
Example request:
Bash
Copied to clipboard
curl https://app.cloudcannon.com/api/v0/base-domains/{base_domain_uuid}/subdomains/{subdomain_uuid}/ssl/retry \
  -X POST \
  -H "X-API-KEY: <your-api-key>"
Terminal
Responses:
200OK
JSON
Copied to clipboard
{
  "redirects_here": [
    "string"
  ],
  "redirects_here_details": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "domain_name": "string",
      "base_domain_uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
Response
403Forbidden
JSON
Copied to clipboard
{
  "error": "string"
}
Response
422Unprocessable
JSON
Copied to clipboard
{
  "errors": {}
}
Response
Open in a new tab