Learn more:

• Fast Purge

• Akamai CLI for Purge

• Enhanced Content Control Utility API

• Media Services API

• Download this API’s RAML and JSON schema descriptors.

Overview

The Fast Purge API provides a programmatic interface for you to purge edge content. In this version, purge your own set of URLs or ARLs (Akamai resource locators), or any content grouped under a cache tag or content provider (CP) code. Delivery products such as Ion, Adaptive Media Delivery, Dynamic Delivery, and Dynamic Site Accelerator all support Fast Purge. If you’re using a legacy Content Control Utility (CCU) API to purge content, see the migration instructions to convert your API programs to use Fast Purge. To purge streaming or media content, use the Media Services API.

If you’re a developer, website architect, or content administrator, you can also use the Akamai Control Center interface to purge content. For details on how to get started with the Fast Purge interface, see the documentation.

For more information about Fast Purge, see Fast Purge API concepts.

Who should use this API

The Fast Purge API is a simple API that enables purging content at the edge. It allows developers and architects to purge a set of URLs or ARLs, or any content grouped under a cache tag or CP code within approximately five seconds.

The API also comes with a CLI version that you can set up as a task within automation tools such as CircleCI or Jenkins.

For more information on content control using TTL (Time to Live) methods, refer to Time to Live (TTL) in Cache: Methods and Considerations.

Get started

To configure this API for the first time:

• Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

• To enable this API, choose the API service named CCU APIs, and set the access level to READ-WRITE.

• Review Identity and Access Management for details on how to create your API access credentials and authorizations. When creating, adding, and naming clients for API access, do so under CCU APIs, not General APIs. Note that you can select all CP codes when configuring your API credentials. This means all current and future CP codes on the current contract, not all CP codes on the account.

• Get help from the Akamai developer community and provide feedback. You can also contact your Akamai representative for support. Akamai wants to hear from you!

Fast Purge API concepts

This section describes the conceptual objects you deal with when interacting with this API, and provides pointers to where you can learn more.

• Fast Purge. The Fast Purge utility (formerly known as Content Control Utility or CCU) completes purge requests within approximately five seconds. Fast Purge supports requests to invalidate or delete a set of URLs or ARLs, or any content grouped under a cache tag or CP code on Akamai staging and production networks. In general, use invalidate, as it causes the edge server to treat content as though its TTL has expired. Use delete for compliance or copyright-related purge requests, as it completely removes all content from servers.

  • invalidation. Content invalidation, or refresh request, is the default purge action in most cases. An invalidation purge action causes Akamai edge servers to send an If-Modified-Since (IMS) request to the origin on subsequent requests for invalidated content. If the timestamp of the object at the origin is more recent than the one in cache, the latter replaces the new object from the origin. Otherwise, it’s re-validated for the duration of the TTL. If an object doesn’t have a Last-Modified header, a regular GET request is sent to origin.

    NOTE: To avoid serving stale content, ensure the Last-Modified-Timestamp (LMT) value on the origin server is updated to a newer timestamp than the LMT value of the current object.

  • deletion. This purge action removes the object from cache so it’s no longer available to clients. Deleting content results in an expensive GET request to the origin server, and prevents Akamai from serving this content stale if the origin server is down.

• Akamai resource locator (ARL). A string that represents an object in cache such as a cache key. For example, /L/16382/123456/15m/www.example.com/myfile.jpg. The ARL is similar to the URL but the ARL is specifically defined for objects served using the Akamai edge network. You can specify an ARL to purge specific versions of an object that you can’t purge using just the URL. To get the cache key for any URL, pass in a Pragma: akamai-x-get-cache-key request header for the X-Cache-Key response header.

• Cache tag. A label, such as a surrogate key or content tag, that you assign to content from the origin. To deploy a set of cache tags, add a single Edge-Cache-Tag header to your origin content. Use commas to separate case-sensitive cache tag values. Once a set of objects have been cached with a tag, they can be purged together with a single Fast Purge API call. You can apply many tags to any object, allowing you to purge by any overlapping set of classifications you define, such as black-friday, flash-sale, electronics, laptops, tablets. If an object matches any one of the tags in a purge request, then its cache is refreshed.

• Content provider (CP) code. Identifies a set, typically a subset, of content on your origin server. CP codes also provide additional granularity in reports and to track billing. Each contract supports at least one CP code. You cannot apply the same CP code to content under more than one contract. If you’re using Property Manager, use the Property Manager API (PAPI) to get a list of CP codes available for a selected contract and group. PAPI also allows you to generate new CP codes, assign them to properties, and apply them within property rules.

Cache tag constraints and other considerations

When deploying tagged content, apply a single Edge-Cache-Tag response header, otherwise only the first one works. Header values are comma-delimited, with optional whitespace, and limited to 128 bytes. Each tag value, derived from the ABNF token format, may not feature interior whitespace or any of the following punctuation characters: *"(),:;<=>?@\[]{}. This example shows how you might overlap tag categories:

Edge-Cache-Tag: casual, knits, fall-sale

Ordinarily, your end users never receive the Edge-Cache-Tag header. You can use Property Manager’s Cache Tag Visibility behavior to override that for any segment of your content, either always, or on demand. Learn more.

If you use Drupal for content management, the Akamai Drupal 8 module can help you tag content. For information on effective ways to use cache tags to purge content, see best practices.

Logically, consider cache tags as part of the tagged content. Thus, new or changed tags need to be returned with a 200 response from the origin. A 304 response doesn’t update the cache tags. To make sure that tags are assigned to all targeted objects on the Akamai network, wait until they refresh based on their TTL value, or explicitly purge them when adding or changing tags.

Sample code

For sample code that demonstrates how to use this API, see the api-kickstart repository. Sample code is available in Python, Node.js, PHP, Ruby, and Perl. It’s frequently updated with new examples for Akamai APIs.

Rate limiting

This API uses rate controls to limit the number of purge requests that clients within a single account can make for a given time. It also limits the rate of URLs, CP codes, or cache tags that can be submitted. When rate limits are applied, the requests from all clients within the same account are counted together. For the purpose of rate limiting, ARLs are counted as URLs.

This table shows the enforced rate limits for API requests in general and for each type of object. An individual API request can include many URLs, CP codes, or cache tags.

The rate limiting algorithm used for sustained rate and burst follows a token bucket model.

There’s one bucket for requests and a separate bucket for each object type (URLs/ARLs, CP codes, and cache tags). The burst value in the table represents how many tokens the bucket can hold. The buckets start full of tokens. Tokens are constantly added to the bucket based on the sustained rate. Once the bucket is full, no more tokens can be added.

When an API request is made, the request may contain either URLs/ARLs, CP codes, or cache tags. First, the API request bucket is checked for tokens. If a token is available, one token is removed from the bucket. Next, the object type bucket is checked for tokens. The object type bucket needs to contain enough tokens to satisfy all of the objects in the request. If there are enough tokens, they’re removed from the bucket and the request is accepted. If there aren’t enough tokens in the object bucket, no tokens are removed, the API request token is returned to the API request bucket, and the entire request is denied.

For example, the token bucket for cache tags holds 5,000 tokens and refills at a rate of 500 tokens per minute. You can submit a burst of 5,000 cache tags if the token bucket is full, but this completely empties the token bucket. Cache tag tokens are refilled at 500 tokens per minute, so after one minute, the bucket has 500 tokens in it and another request with up to 500 objects can be processed.

You can submit a burst of 5,000 tags every 10 minutes, 1,000 cache tags every 2 minutes, or 500 cache tags every minute. In all cases, the average sustained rate is still 500 cache tags per minute. If you submit a burst of 5,000 cache tags followed immediately by another request for 500 cache tags, the second request for 500 cache tags is denied because there aren’t enough tokens left.

To purge more objects while remaining within defined limits, combine many objects into a single API request and reduce the rate of requests. A single API request may contain many objects of the same type, as long as the request body is smaller than 50,000 bytes.

Rate limit headers

When a request is denied due to rate limiting, the API responds with a 429 error, along with various X-Ratelimit-* HTTP headers and rateLimit* JSON members in the response body.

This table shows the rate limiting response headers returned by the API. These headers appear for both success and failure responses.

Rate limit response body

Rate limit headers are present in success and failure responses, while the rate limit response body members are only present in responses that are denied due to rate limiting.

This table shows the rate limiting response body JSON members for a 429 failure response.

Rate limit response examples

These examples show 429 failure responses when a URL purge request has exceeded an API request rate limit and an object rate limit.

In this first 429 failure response, the Rate Limit exceeded title in the response body shows that the API request rate limit was exceeded. The X-Ratelimit-Remaining header value is 0 and the rateLimitRemaining response member is 0. This means that there were no additional API requests remaining at this moment, and the request was denied.

To stay within the rate limits, you can reduce the API request rate and use the remaining 9904 URL objects, shown in the X-Ratelimit-Remaining-Objects response header, in each purge request. This allows for a comparable purge rate without exceeding the rate limit.

HTTP/1.1 429 Too Many Requests
Date: Tue, 12 Mar 2019 21:14:01 GMT
Content-Length: 239
Content-Type: application/api-problem+json
X-Ratelimit-Remaining: 0
X-Ratelimit-Limit-Per-Second: 50.00
X-Ratelimit-Limit: 100
X-Ratelimit-Remaining-Objects: 9904
X-Ratelimit-Limit-Per-Second-Objects: 200.00
X-Ratelimit-Limit-Objects: 10000

{
  "supportId": "17PY1552425241133633-211776704",
  "title": "Rate Limit exceeded",
  "httpStatus": 429,
  "describedBy": "https://developer.akamai.com/api/core_features/fast_purge/v3.html#httpcodes",
  "rateLimit": 100,
  "rateLimitCurrentRequestSize": 1,
  "rateLimitRemaining": 0
}

In this next 429 failure response, the URL Rate Limit exceeded title in the response body shows that an object URL rate limit was exceeded. Note that the object rate limit for a URL purge request is 200 URLs per second, as shown in the X-Ratelimit-Limit-Per-Second-Objects header. The rateLimitRemaining response member is 94, which was the number of URLs available to purge at that moment. When the purge request was submitted, it contained 110 URLs, as shown in the rateLimitCurrentRequestSize response member. Because the request was 16 URLs over the current limit of 94, it was denied.

To maximize the purge rate without waiting, you can truncate the request to contain 94 URLs, then resubmit it immediately. Alternatively, wait until you can purge all 110 URLs at once, which in this case would only take 80 milliseconds.

HTTP/1.1 429 Too Many Requests
Date: Tue, 12 Mar 2019 21:14:31 GMT
Content-Length: 251
Content-Type: application/api-problem+json
X-Ratelimit-Remaining: 40
X-Ratelimit-Limit-Per-Second: 50.00
X-Ratelimit-Limit: 100
X-Ratelimit-Remaining-Objects: 94
X-Ratelimit-Limit-Per-Second-Objects: 200.00
X-Ratelimit-Limit-Objects: 10000

{
  "supportId": "17PY1552425341153293-211776704",
  "title": "URL Rate Limit exceeded",
  "httpStatus": 429,
  "describedBy": "https://developer.akamai.com/api/core_features/fast_purge/v3.html#httpcodes",
  "rateLimit": 10000,
  "rateLimitCurrentRequestSize": 110,
  "rateLimitRemaining": 94
}

In addition, the API guards against denial of service (DoS) level traffic flows. For example, when a single API client attempts to submit hundreds of requests per second, the API responds with a 400 error for web application firewall (WAF) rate-controlled clients.

HTTP/1.1 400 Bad Request
Content-Length: 427
Date: Thu, 01 Mar 2018 18:46:03 GMT
Connection: close
Content-Type: application/problem+json

{
    "type": "https://problems.purge.akamaiapis.net/-/pep-authn/request-error",
    "title": "Bad request",
    "status": 400,
    "detail": "WAF deny rule IPBLOCK-BURST4-27754",
    "instance": "https://akab-cj2eq2kcsv7cpt75-bi4ae4mdehbj2p4a.purge.akamaiapis.net/ccu/v3/invalidate/url",
    "method": "POST",
    "serverIp": "104.76.97.105",
    "clientIp": "24.2.26.125",
    "requestId": "1dd8d22",
    "requestTime": "2018-03-01T18:46:03Z"
}

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

Invalidate by URL or ARL

Invalidates content on the selected URL or ARL for the selected network. You should consider invalidating content by default. This keeps each object in cache until the version on your origin server is newer. Deletion retrieves the object regardless, which can dramatically increase the load on your origin server and would prevent Akamai from serving the old content if your origin is unreachable. URLs and ARLs can be submitted in the same request. Note that it takes longer to purge ARLs when using the Control Center interface. Use this API to purge them within five seconds.

{
    "objects": [
        "https://foo1.bar.com/some/path",
        "http://foo2.bar.com/some/other/path"
    ]
}

{
    "httpStatus": 201,
    "estimatedSeconds": 5,
    "purgeId": "e535071c-26b2-11e7-94d7-276f2f54d938",
    "supportId": "17PY1492793544958045-219026624",
    "detail": "Request accepted"
}

Invalidate by CP code

Invalidates content on the selected CP code for the selected network. You should consider invalidating content by default. This keeps each object in cache until the version on your origin server is newer. Deletion retrieves the object regardless, which can dramatically increase the load on your origin server and would prevent Akamai from serving the old content if your origin is unreachable.

{
    "objects": [
        12345,
        98765
    ]
}

{
    "httpStatus": 201,
    "estimatedSeconds": 5,
    "purgeId": "e535071c-26b2-11e7-94d7-276f2f54d938",
    "supportId": "17PY1492793544958045-219026624",
    "detail": "Request accepted"
}

Invalidate by cache tag

Invalidates content on the selected set of cache tags for the selected network. You should consider invalidating content by default. This keeps each object in cache until the version on your origin server is newer. Deletion retrieves the object regardless, which can dramatically increase the load on your origin server and would prevent Akamai from serving the old content if your origin is unreachable.

{
    "objects": [
        "black-friday",
        "electronics",
        "laptops",
        "tablets"
    ]
}

{
    "httpStatus": 201,
    "estimatedSeconds": 5,
    "purgeId": "e535071c-26b2-11e7-94d7-276f2f54d938",
    "supportId": "17PY1492793544958045-219026624",
    "detail": "Request accepted"
}

Delete by URL or ARL

Deletes content on the selected URL or ARL for the selected network. In most cases, you should invalidate rather than delete content. URLs and ARLs can be submitted in the same request. Note that it takes longer to purge ARLs when using the Control Center interface. Use this API to purge them within five seconds.

{
    "objects": [
        "https://foo1.bar.com/some/path",
        "http://foo2.bar.com/some/other/path"
    ]
}

{
    "httpStatus": 201,
    "estimatedSeconds": 5,
    "purgeId": "e535071c-26b2-11e7-94d7-276f2f54d938",
    "supportId": "17PY1492793544958045-219026624",
    "detail": "Request accepted"
}

Delete by CP code

Deletes content on the selected CP code for the selected network. In most cases, you should invalidate rather than delete content.

{
    "objects": [
        12345,
        98765
    ]
}

{
    "httpStatus": 201,
    "estimatedSeconds": 5,
    "purgeId": "e535071c-26b2-11e7-94d7-276f2f54d938",
    "supportId": "17PY1492793544958045-219026624",
    "detail": "Request accepted"
}

Delete by cache tag

Deletes content on the selected set of cache tags for the selected network. In most cases, you should invalidate rather than delete content.

{
    "objects": [
        "black-friday",
        "electronics",
        "laptops",
        "tablets"
    ]
}

{
    "httpStatus": 201,
    "estimatedSeconds": 5,
    "purgeId": "e535071c-26b2-11e7-94d7-276f2f54d938",
    "supportId": "17PY1492793544958045-219026624",
    "detail": "Request accepted"
}

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

This section’s data schema tables list membership requirements as follows:

UrlRequest

Specifies a list of URLs or ARLs to invalidate or delete. You can submit URLs and ARLs in the same purge request.

Download schema: UrlRequest.json

Sample POST request:

{
    "objects": [
        "https://foo1.bar.com/some/path",
        "http://foo2.bar.com/some/other/path"
    ]
}

UrlRequest members

UrlRequestWithHostname

Specifies a list of server paths to invalidate or delete for a common hostname.

Download schema: UrlRequestWithHostname.json

Sample POST request:

{
    "hostname": "origin.qux.com",
    "objects": [
        "/some/path/object1",
        "/some/other/path/object2"
    ]
}

UrlRequestWithHostname members

CpCodeRequest

Specifies a list of CP codes to invalidate or delete.

Download schema: CPCodeRequest.json

Sample POST request:

{
    "objects": [
        12345,
        98765
    ]
}

CpCodeRequest members

TagRequest

Specifies a list of cache tags to invalidate or delete.

Download schema: TagRequest.json

Sample POST request:

{
    "objects": [
        "black-friday",
        "electronics",
        "laptops",
        "tablets"
    ]
}

TagRequest members

Response

V3 Purge response schema

Download schema: Response.json

Sample POST response:

{
    "httpStatus": 201,
    "estimatedSeconds": 5,
    "purgeId": "e535071c-26b2-11e7-94d7-276f2f54d938",
    "supportId": "17PY1492793544958045-219026624",
    "detail": "Request accepted"
}

Response members

Errors

This section shows you how to handle various kinds of errors the Fast Purge API generates and lists the range of HTTP status codes along with their likely causes.

NOTE: It’s strongly recommended that you code test the response. The response isn’t hard coded, and can be different.

Error responses

The format of error response objects follows the JSON Problem Details standard, and are identified with the application/api-problem+json content type.

This example shows an error response for a request processed by Fast Purge.

{
    "supportId": "17PY1234567890123456-123456789",
    "title": "Unauthorized",
    "httpStatus": 401,
    "detail": "You are not authorized to invalidate this resource.",
    "describedBy": "https://developer.akamai.com/api/core_features/fast_purge/v3.html#httpcodes"
}

HTTP status codes

The Fast Purge API responds with these standard HTTP response codes: