Introduction
IBM Cloud Internet Services (CIS), powered by Cloudflare, provides a fast, highly performant, reliable, and secure internet service for customers running their business on IBM Cloud.
IBM CIS gets you going quickly by establishing defaults for you, which you can change easily using the API or UI. Here are some commonly changed parameters:
- DNS settings: you can use IBM CIS to host your DNS or you can create CNAME records.
- Crypto settings (TLS): the default is flexible mode, which encrypts the connection between your host and the IBM CIS edge server, but does not encrypt the communication between the IBM CIS edge server and origin server.
For complete information about establishing and managing an IBM Cloud CIS instance, refer to our customer documentation.
API endpoint
https://api.cis.cloud.ibm.com
Error handling
This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200
response always indicates success. A 400
type response is some sort of failure, and a 500
type response usually indicates an internal system error.
HTTP error code | Description | Recovery |
---|---|---|
200 |
Success | The request was successful. |
400 |
Bad Request | The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request. |
401 |
Unauthorized | You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions. |
403 |
Forbidden | The supplied authentication is not authorized to access '{namespace}'. |
404 |
Not Found | The requested resource could not be found. |
408 |
Request Timeout | The connection to the server timed out. Wait a few minutes, then try again. |
409 |
Conflict | The entity is already in the requested state. |
500 |
Internal Server Error | IBM Cloud Internet Services is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. |
Here are some model code examples for error handling in the IBM Cloud Internet Services API:
Success 200 Example Code
200 The API was completed successfully
{
"success": true,
"errors": [
{}
],
"messages": [
{}
],
"result": {
"zones": [
{
"zone": {
"status": null,
"name": null,
"security": null,
"paused": false
},
"dns_record": {
"count": 0
},
"load_balancer": {
"monitor_count": 0,
"pool_count": 0,
"load_balancer_active_count": 0
},
"caching": {
"edge_cache_ttl": 0,
"cache_browser_ttl": 0,
"development_mode": "off",
"cache_level": "basic"
},
"pagerule": {
"active_count": 0,
"inactive_count": 0
},
"waf": {
"status": null
},
"ssl": {
"mode": null,
"universal_ssl_certificate": "off",
"dedicate_certificate_count": 0,
"custom_upload_certificate_count": 0,
"tls_1_2_only": "on"
},
"plan_details": {
"plan_name": "Standard",
"days_remaining": null
},
"firewall": {
"security_level": "low"
}
}
],
"service_maintenance": {
"start_time": null,
"end_time": null,
"message": null
}
}
}
Methods
purge all files under a specific domain.
All resources in CDN edge servers' cache should be removed. This may have dramatic affects on your origin server load after performing this action.
PUT /v1/{crn}/zones/{zone_id}/purge_cache/purge_all
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full url-encoded cloud resource name (CRN) of resource instance
zone id
curl -X PUT \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/purge_cache/purge_all \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx'
Was the get successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
Example:
62d26b178b67c0eda0613891f3f51b0a
result
Status Code
success
Forbidden! User has no privilege to use IBM Cloud Internet Services
Resource not found
Internal server error
Gateway Timeout! Backend API endpoint did not respond on time
{ "success": true, "errors": [], "messages": [], "result": { "id": "62d26b178b67c0eda0613891f3f51b0a" } }
purge individual files by URLs.
Granularly remove one or more files from CDN edge servers' cache either by specifying URLs.
PUT /v1/{crn}/zones/{zone_id}/purge_cache/purge_by_urls
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full url-encoded cloud resource name (CRN) of resource instance
zone id
An array of URLs that should be removed from cache
Files
curl -X PUT \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/purge_cache/purge_by_urls \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx' -d '{ "files": [ "http://www.example.com/example_01.jpg", "http://www.example.com/example_02.jpg" ] }'
Was the get successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
Example:
62d26b178b67c0eda0613891f3f51b0a
result
Status Code
success
Bad request
Forbidden! User has no privilege to use IBM Cloud Internet Services
Resource not found
Internal server error
Gateway Timeout! Backendendpoint did not respond on time
{ "success": true, "errors": [], "messages": [], "result": { "id": "62d26b178b67c0eda0613891f3f51b0a" } }
Purge files by Cache-Tags.
Granularly remove one or more files from CDN edge servers' cache either by specifying the associated Cache-Tags.
PUT /v1/{crn}/zones/{zone_id}/purge_cache/purge_by_cache_tags
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full url-encoded cloud resource name (CRN) of resource instance
zone id
Any assets served with a Cache-Tag header that matches one of the provided values will be purged from the CDN edge servers' cache.
Tags
curl -X PUT \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/purge_cache/purge_by_cache_tags \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx' -d '{ "tags": [ "cache-tag-01", "cache-tag-02" ] }'
Was the get successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
Example:
62d26b178b67c0eda0613891f3f51b0a
result
Status Code
success
Bad request
Forbidden! User has no privilege to use IBM Cloud Internet Services
Resource not found
Internal server error
Gateway Timeout! Backendendpoint did not respond on time
{ "success": true, "errors": [], "messages": [], "result": { "id": "62d26b178b67c0eda0613891f3f51b0a" } }
purge individual files by hostnames.
Granularly remove one or more files from CDN edge servers' cache either by specifying the hostnames.
PUT /v1/{crn}/zones/{zone_id}/purge_cache/purge_by_hosts
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full url-encoded cloud resource name (CRN) of resource instance
zone id
Any assets at URLs with a host that matches one of the provided values will be purged from the CDN edge servers' cache.
Hosts
curl -X PUT \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/purge_cache/purge_by_hosts \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx' -d '{ "hosts": [ "one.example.com, "two.example.com" ] }'
Was the get successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
Example:
62d26b178b67c0eda0613891f3f51b0a
result
Status Code
success
Bad request
Forbidden! User has no privilege to use IBM Cloud Internet Services
Resource not found
Internal server error
Gateway Timeout! Backendendpoint did not respond on time
{ "success": true, "errors": [], "messages": [], "result": { "id": "62d26b178b67c0eda0613891f3f51b0a" } }
Get cache level setting of a specific zone.
Get cache level setting of a specific zone.
GET /v1/{crn}/zones/{zone_id}/settings/cache_level
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full url-encoded cloud resource name (CRN) of resource instance
zone id
curl -X GET \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/settings/cache_level \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx'
Cache level response
Was the get successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
ID
Example:
cache_level
Value
Example:
aggressive
Editable
Example:
true
Modified date
Example:
2014-01-01T05:20:00.12345Z
result
Status Code
success
Forbidden! User has no privilege to use IBM Cloud Internet Services
Resource not found
Internal server error
Gateway Timeout! Backendendpoint did not respond on time
{ "result": { "id": "cache_level", "value": "basic", "modified_on": null, "editable": true }, "success": true, "errors": [], "messages": [] }
Set cache level setting for a specific zone.
The basic
setting will cache most static resources (i.e., css, images, and JavaScript). The simplified
setting will ignore the query string when delivering a cached resource. The aggressive
setting will cache all static resources, including ones with a query string.
PATCH /v1/{crn}/zones/{zone_id}/settings/cache_level
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full url-encoded cloud resource name (CRN) of resource instance
zone id
The basic
setting will cache most static resources (i.e., css, images, and JavaScript). The simplified
setting will ignore the query string when delivering a cached resource. The aggressive
setting will cache all static resources, including ones with a query string.
Value
Allowable values: [
basic
,simplified
,aggressive
]Example:
aggressive
curl -X PATCH \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/settings/cache_level \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx' -d '{ "value": "aggressive" }'
Cache level response
Was the get successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
ID
Example:
cache_level
Value
Example:
aggressive
Editable
Example:
true
Modified date
Example:
2014-01-01T05:20:00.12345Z
result
Status Code
success
Bad request
Forbidden! User has no privilege to use IBM Cloud Internet Services
Resource not found
Internal server error
Gateway Timeout! Backendendpoint did not respond on time
{ "result": { "id": "cache_level", "value": "aggressive", "modified_on": "2018-10-08T09:40:03.277303Z", "editable": true }, "success": true, "errors": [], "messages": [] }
Get browser cache TTL setting.
Browser Cache TTL (in seconds) specifies how long CDN edge servers cached resources will remain on your visitors' computers.
GET /v1/{crn}/zones/{zone_id}/settings/browser_cache_ttl
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full url-encoded cloud resource name (CRN) of resource instance
zone id
curl -X GET \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/settings/browser_cache_ttl \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx'
Browser TTL response
Was the get successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
ID
Example:
browser_cache_ttl
Value
Example:
1800
Editable
Example:
true
Modified date
Example:
2014-01-01T05:20:00.12345Z
result
Status Code
success
Forbidden! User has no privilege to use IBM Cloud Internet Services
Resource not found
Internal server error
Gateway Timeout! Backendendpoint did not respond on time
{ "result": { "id": "browser_cache_ttl", "value": 14400, "modified_on": null, "editable": true }, "success": true, "errors": [], "messages": [] }
Change browser cache TTL setting.
Browser Cache TTL (in seconds) specifies how long CDN edge servers cached resources will remain on your visitors' computers.
PATCH /v1/{crn}/zones/{zone_id}/settings/browser_cache_ttl
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full url-encoded cloud resource name (CRN) of resource instance
zone id
Default value is 14400. valid values are 0, 30, 60, 300, 1200, 1800, 3600, 7200, 10800, 14400, 18000, 28800, 43200, 57600, 72000, 86400, 172800, 259200, 345600, 432000, 691200, 1382400, 2073600, 2678400, 5356800, 16070400, 31536000. notes! The minimum TTL available depends on the plan level of the zone. Enterprise is 30, Business is 1800, Pro is 1800, Free is 1800, 0 is special value meaning to respect origin header.
Value
Constraints: 0 ≤ value ≤ 31536000
Example:
1800
curl -X PATCH \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/settings/browser_cache_ttl \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx' -d '{ "value": 1800 }'
Browser TTL response
Was the get successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
ID
Example:
browser_cache_ttl
Value
Example:
1800
Editable
Example:
true
Modified date
Example:
2014-01-01T05:20:00.12345Z
result
Status Code
success
Bad request
Forbidden! User has no privilege to use IBM Cloud Internet Services
Resource not found
Internal server error
Gateway Timeout! Backendendpoint did not respond on time
{ "result": { "id": "browser_cache_ttl", "value": 1800, "modified_on": "2018-10-08T09:40:03.277303Z", "editable": true }, "success": true, "errors": [], "messages": [] }
Get development mode setting.
Get development mode setting.
GET /v1/{crn}/zones/{zone_id}/settings/development_mode
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full url-encoded cloud resource name (CRN) of resource instance
zone id
curl -X GET \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/settings/development_mode \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx'
Development mode response
Was the get successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
ID
Example:
development_mode
Value
Editable
Example:
true
Modified date
Example:
2014-01-01T05:20:00.12345Z
result
Status Code
success
Forbidden! User has no privilege to use IBM Cloud Internet Services
Resource not found
Internal server error
Gateway Timeout! Backendendpoint did not respond on time
{ "result": { "id": "development_mode", "value": "off", "modified_on": null, "editable": true }, "success": true, "errors": [], "messages": [] }
Change development mode setting.
Change development mode setting.
PATCH /v1/{crn}/zones/{zone_id}/settings/development_mode
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full url-encoded cloud resource name (CRN) of resource instance
zone id
default value is off
, valid values are on
and off
.
Value
Allowable values: [
on
,off
]Example:
on
curl -X PATCH \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/settings/development_mode \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx' -d '{ "value": "on" }'
Development mode response
Was the get successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
ID
Example:
development_mode
Value
Editable
Example:
true
Modified date
Example:
2014-01-01T05:20:00.12345Z
result
Status Code
success
Bad request
Forbidden! User has no privilege to use IBM Cloud Internet Services
Resource not found
Internal server error
Gateway Timeout! Backendendpoint did not respond on time
{ "result": { "id": "development", "value": "on", "modified_on": "2018-10-08T09:40:03.277303Z", "editable": true }, "success": true, "errors": [], "messages": [] }
Get Enable Query String Sort setting.
Get Enable Query String Sort setting.
GET /v1/{crn}/zones/{zone_id}/settings/sort_query_string_for_cache
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full url-encoded cloud resource name (CRN) of resource instance
zone id
curl -X GET \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/settings/sort_query_string_for_cache \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx'
Enable query string sort
Was the get successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
ID
Example:
sort_query_string_for_cache
Value
Editable
Example:
true
Modified date
Example:
2014-01-01T05:20:00.12345Z
result
Status Code
success
Forbidden! User has no privilege to use IBM Cloud Internet Services
Resource not found
Internal server error
Gateway Timeout! Backendendpoint did not respond on time
{ "result": { "id": "sort_query_string_for_cache", "value": "off", "modified_on": null, "editable": true }, "success": true, "errors": [], "messages": [] }
Change Enable Query String Sort setting.
Change Enable Query String Sort setting.
PATCH /v1/{crn}/zones/{zone_id}/settings/sort_query_string_for_cache
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full url-encoded cloud resource name (CRN) of resource instance
zone id
default value is off
, valid values are on
and off
.
Value
Allowable values: [
on
,off
]Example:
on
curl -X PATCH \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/settings/sort_query_string_for_cache \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx' -d '{ "value": "on" }'
Enable query string sort
Was the get successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
ID
Example:
sort_query_string_for_cache
Value
Editable
Example:
true
Modified date
Example:
2014-01-01T05:20:00.12345Z
result
Status Code
success
Bad request
Forbidden! User has no privilege to use IBM Cloud Internet Services
Resource not found
Internal server error
Gateway Timeout! Backendendpoint did not respond on time
{ "result": { "id": "sort_query_string_for_cache", "value": "on", "modified_on": "2018-10-08T09:40:03.277303Z", "editable": true }, "success": true, "errors": [], "messages": [] }