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

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
    }
  }
}

Failure 401 Example Code

401 Action unauthorized

{
  "trace": "be45687c-57f2-46e8-8717-32b3153a5886",
  "errors": [
    {
      "code": 401,
      "message": "Action is not authorized."
    }
  ]
}

Failure 404 Example:

404 API not found
{
  "trace": "c3c9f6af-a20f-4b73-8e3d-800a9284a07f",
  "errors": [
    {
      "code": null,
      "message": "404 Not Found"
    }
  ]
}

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
Request

Custom Headers

  • X-Auth-User-Token
    string

    IBM Cloud user IAM token

Path Parameters

  • crn
    string

    Full url-encoded cloud resource name (CRN) of resource instance

  • zone_id
    string

    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'
Response

Response Body

purgeAll-response

Status Code

  • 200

    success

  • 403

    Forbidden! User has no privilege to use IBM Cloud Internet Services

  • 404

    Resource not found

  • 500

    Internal server error

  • 504

    Gateway Timeout! Backend API endpoint did not respond on time

Example responses
  • {
  "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
Request

Custom Headers

  • X-Auth-User-Token
    string

    IBM Cloud user IAM token

Path Parameters

  • crn
    string

    Full url-encoded cloud resource name (CRN) of resource instance

  • zone_id
    string

    zone id

Request Body

purge_urls_body

An array of URLs that should be removed from cache

  • 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"
    ]
}'
Response

Response Body

purgeAll-response

Status Code

  • 200

    success

  • 400

    Bad request

  • 403

    Forbidden! User has no privilege to use IBM Cloud Internet Services

  • 404

    Resource not found

  • 500

    Internal server error

  • 504

    Gateway Timeout! Backendendpoint did not respond on time

Example responses
  • {
  "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
Request

Custom Headers

  • X-Auth-User-Token
    string

    IBM Cloud user IAM token

Path Parameters

  • crn
    string

    Full url-encoded cloud resource name (CRN) of resource instance

  • zone_id
    string

    zone id

Request Body

purge_tags_body

Any assets served with a Cache-Tag header that matches one of the provided values will be purged from the CDN edge servers' cache.

  • 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"
    ]
}'
Response

Response Body

purgeAll-response

Status Code

  • 200

    success

  • 400

    Bad request

  • 403

    Forbidden! User has no privilege to use IBM Cloud Internet Services

  • 404

    Resource not found

  • 500

    Internal server error

  • 504

    Gateway Timeout! Backendendpoint did not respond on time

Example responses
  • {
  "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
Request

Custom Headers

  • X-Auth-User-Token
    string

    IBM Cloud user IAM token

Path Parameters

  • crn
    string

    Full url-encoded cloud resource name (CRN) of resource instance

  • zone_id
    string

    zone id

Request Body

purge_hosts_body

Any assets at URLs with a host that matches one of the provided values will be purged from the CDN edge servers' cache.

  • 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"
    ]
}'
Response

Response Body

purgeAll-response

Status Code

  • 200

    success

  • 400

    Bad request

  • 403

    Forbidden! User has no privilege to use IBM Cloud Internet Services

  • 404

    Resource not found

  • 500

    Internal server error

  • 504

    Gateway Timeout! Backendendpoint did not respond on time

Example responses
  • {
  "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
Request

Custom Headers

  • X-Auth-User-Token
    string

    IBM Cloud user IAM token

Path Parameters

  • crn
    string

    Full url-encoded cloud resource name (CRN) of resource instance

  • zone_id
    string

    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'
Response

Response Body

cacheLevel-response

Cache level response

Status Code

  • 200

    success

  • 403

    Forbidden! User has no privilege to use IBM Cloud Internet Services

  • 404

    Resource not found

  • 500

    Internal server error

  • 504

    Gateway Timeout! Backendendpoint did not respond on time

Example responses
  • {
  "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
Request

Custom Headers

  • X-Auth-User-Token
    string

    IBM Cloud user IAM token

Path Parameters

  • crn
    string

    Full url-encoded cloud resource name (CRN) of resource instance

  • zone_id
    string

    zone id

Request Body

cacheLevel-body

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.

  • 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"
}'
Response

Response Body

cacheLevel-response

Cache level response

Status Code

  • 200

    success

  • 400

    Bad request

  • 403

    Forbidden! User has no privilege to use IBM Cloud Internet Services

  • 404

    Resource not found

  • 500

    Internal server error

  • 504

    Gateway Timeout! Backendendpoint did not respond on time

Example responses
  • {
  "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
Request

Custom Headers

  • X-Auth-User-Token
    string

    IBM Cloud user IAM token

Path Parameters

  • crn
    string

    Full url-encoded cloud resource name (CRN) of resource instance

  • zone_id
    string

    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'
Response

Response Body

browserTTL-response

Browser TTL response

Status Code

  • 200

    success

  • 403

    Forbidden! User has no privilege to use IBM Cloud Internet Services

  • 404

    Resource not found

  • 500

    Internal server error

  • 504

    Gateway Timeout! Backendendpoint did not respond on time

Example responses
  • {
  "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
Request

Custom Headers

  • X-Auth-User-Token
    string

    IBM Cloud user IAM token

Path Parameters

  • crn
    string

    Full url-encoded cloud resource name (CRN) of resource instance

  • zone_id
    string

    zone id

Request Body

browserTTL-body

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.

  • 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
}'
Response

Response Body

browserTTL-response

Browser TTL response

Status Code

  • 200

    success

  • 400

    Bad request

  • 403

    Forbidden! User has no privilege to use IBM Cloud Internet Services

  • 404

    Resource not found

  • 500

    Internal server error

  • 504

    Gateway Timeout! Backendendpoint did not respond on time

Example responses
  • {
  "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
Request

Custom Headers

  • X-Auth-User-Token
    string

    IBM Cloud user IAM token

Path Parameters

  • crn
    string

    Full url-encoded cloud resource name (CRN) of resource instance

  • zone_id
    string

    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'
Response

Response Body

developmentMode-response

Development mode response

Status Code

  • 200

    success

  • 403

    Forbidden! User has no privilege to use IBM Cloud Internet Services

  • 404

    Resource not found

  • 500

    Internal server error

  • 504

    Gateway Timeout! Backendendpoint did not respond on time

Example responses
  • {
  "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
Request

Custom Headers

  • X-Auth-User-Token
    string

    IBM Cloud user IAM token

Path Parameters

  • crn
    string

    Full url-encoded cloud resource name (CRN) of resource instance

  • zone_id
    string

    zone id

Request Body

developmentMode-body

default value is off, valid values are on and off.

  • 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"
}'
Response

Response Body

developmentMode-response

Development mode response

Status Code

  • 200

    success

  • 400

    Bad request

  • 403

    Forbidden! User has no privilege to use IBM Cloud Internet Services

  • 404

    Resource not found

  • 500

    Internal server error

  • 504

    Gateway Timeout! Backendendpoint did not respond on time

Example responses
  • {
  "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
Request

Custom Headers

  • X-Auth-User-Token
    string

    IBM Cloud user IAM token

Path Parameters

  • crn
    string

    Full url-encoded cloud resource name (CRN) of resource instance

  • zone_id
    string

    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'
Response

Response Body

enableQueryStringSort-response

Enable query string sort

Status Code

  • 200

    success

  • 403

    Forbidden! User has no privilege to use IBM Cloud Internet Services

  • 404

    Resource not found

  • 500

    Internal server error

  • 504

    Gateway Timeout! Backendendpoint did not respond on time

Example responses
  • {
  "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
Request

Custom Headers

  • X-Auth-User-Token
    string

    IBM Cloud user IAM token

Path Parameters

  • crn
    string

    Full url-encoded cloud resource name (CRN) of resource instance

  • zone_id
    string

    zone id

Request Body

enableQueryStringSort-body

default value is off, valid values are on and off.

  • 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"
}'
Response

Response Body

enableQueryStringSort-response

Enable query string sort

Status Code

  • 200

    success

  • 400

    Bad request

  • 403

    Forbidden! User has no privilege to use IBM Cloud Internet Services

  • 404

    Resource not found

  • 500

    Internal server error

  • 504

    Gateway Timeout! Backendendpoint did not respond on time

Example responses
  • {
  "result": {
    "id": "sort_query_string_for_cache",
    "value": "on",
    "modified_on": "2018-10-08T09:40:03.277303Z",
    "editable": true
  },
  "success": true,
  "errors": [],
  "messages": []
}