loading

Property Manager API v0

The original beta version of PAPI.

Learn more:


Overview

NOTE: This initial API version 0 has been superseded. See version 1 for the latest features. Upgrade to the new version of the API at your earliest opportunity, mainly by updating to v1 in all request URLs. Version 1 is backwards compatible with v0, so your code will work as before, but you need to upgrade to v1 to take advantage of many upcoming features. A deprecation notice for PAPI v0 will be posted in early July, 2017. The v0 endpoints will continue to work until January, 2018. This v0 API guide has been frozen, so consult the v1 guide for the most up-to-date information.

The Property Manager API (a.k.a. PAPI) offers a programmatic interface to manage how Akamai edge servers process requests, responses, and objects served over the Akamai platform. A distributed property configuration encapsulates all the rules for how to process end-user requests for your web assets. Like the Luna Control Center’s Property Manager, this API lets you modify your property configurations and activate them on Akamai staging or production networks. The API allows you to access the same features rapidly and flexibly using your own tools. PAPI allows you to generate properties dynamically, associate them with dynamically generated hostnames, and to create new CP codes to report on your content’s traffic.

Getting started

Before using PAPI for the first time:

  • Contact your Akamai representative to enable it for your account.

  • Review Get Started on available tools. Note that tools such as edgegrid-curl and edgegrid-python assume a maximum message-body size of 2048 bytes, which for PAPI needs to increase to 128K. How you do so depends on your chosen tool, for example by setting max-body:131072 in the .egcurl file, or in python by passing in max_body:131072 as part of the EdgeGridAuth() call.

  • Review Authorize Your Client to create your API access credentials and authorizations, making sure you enable read/write access for the Property Manager API grant. When setting up your credentials for use with PAPI, make sure to associate it with a user who does not have access to more than one portal account, as that can cause authorization errors.

  • Review the API’s Known Issues.

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

The security token you use to form a custom domain for the request, as discussed in The API Identity Model, keys to your account. The entire URL for the GET request will look something like this:

https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net/papi/v0/contracts/

Once you have a custom domain that is keyed to your account, you can gather other prerequisite data from the API: the relevant contract and group to access other PAPI objects, and a product to create new ones. See the Resources section for PAPI’s full range of capabilities.

PAPI concepts

This section provides a road map of all the conceptual objects you deal with when interacting with PAPI, and provides pointers to where you can learn more.

  • Accounts: Akamai customers access all their services via an account key. While administrators may have access to more than one account, in general they provision all their web assets under a single account within the Akamai Luna portal. PAPI responses often return details about the account to which the security token you use to access the API is implicitly tied.

  • Groups: Each account features a hierarchy of groups, which control access to properties and help consolidate reporting functions, typically mapping to an organizational hierarchy. Using either the Luna portal or the User Admin API, account administrators can assign properties to specific groups, each with its own set of users and accompanying roles. Your access to any given property depends on the role set for you in its group. Along with information about the contract, you need the group identifier to access virtually all of PAPI’s resources. (See the Groups interface and Group object type.)

  • Contracts: Each account features one or more contracts, each of which has a fixed term of service during which specified Akamai products and modules are active. Along with information about the group, you need the contract identifier to access virtually all of PAPI’s resources. (See the Contracts interface and Contract object type.)

  • Products: Each contract enables one or more products, each of which allows you to deploy web properties on the Akamai edge network and receive associated support from Akamai Professional Services. Products allow you to create new properties, CP codes, and edge hostnames. They also determine the baseline set of a property’s rule behaviors. (See the Products interface and Product object type.)

  • Modules: Modules are add-ons to products that may enable additional rule behaviors. Different products support different sets of modules. Your ability to specify any given rule behavior depends on the currently active product and associated modules. PAPI does not provide information directly about your selected modules, but it does allow you to determine the currently available behaviors and criteria they enable.

The inputs above allow you to deploy properties:

  • Properties: Akamai’s edge network caches your web assets near to servers that request them. A property, sometimes also referred to as a configuration, provides the main way to control how edge servers respond to various kinds of requests for those assets. Properties apply rules to a set of hostnames, and you can only apply one property at a time to any given hostname. Each property is assigned to a product, which determines which rule behaviors you can use. Each property’s default rule must specify a valid CP code to bill and report for the service. (See the Properties interface and Property object type.)

  • Versions: Each property has snapshot versions, which allows you to modify one instance of a property while another is activated. You can freely modify a property version (along with its component hostnames and rules) up until the point at which it is activated, after which you must create a new version to modify it further. You do not need to create a new property version for each modification you make. Each version is identified by ascending integer, and features a time stamp, the username who modified it, and a log message. (See the Property Versions interface and Version object type.)

  • Activations: Once you are satisfied with any version of a property, an activation deploys it, either to the Akamai staging or production network. You activate a specific version, but the same version can be activated separately more than once. You can cancel an activation shortly after enabling it, making it the only PAPI object you can delete. (See the Property Activations interface and Activation object type.)

  • Metadata: Once activated, each property is distributed to the Akamai network as an XML configuration file known as Akamai metadata. This XML format combines information about the property’s rules and hostnames. You can view metadata for each version regardless of activation, but you can only modify it indirectly. (See the Property Versions interface.):

  • Messages: When you modify different aspects of a property, responses may include errors or warnings. An error prevents you from activating a property version, but you can activate versions that yield less severe warnings. Warnings that result from activations must be explicitly acknowledged.

Properties include rules:

  • Rules: Properties allow you to design rules to respond to different kinds of requests. A rule consists of criteria that identify which requests to process, and the behaviors to apply to those requests. In addition to a top-level default rule that determines overall behavior, you may include any number of your own rules, arranged in a tree structure up to five levels deep. The API provides an interface to the entire rule tree, not to each component rule. The API also does not support the Luna interface’s rule templates feature, since programming tools allow you to build your own rule templating system more flexibly. (See the Property Version Rules interface and Rule object type. See also the Rule Trees section for guidance on how to structure a rule tree.)

  • Criteria: Rules may specify an optional set of criteria (often referred to as conditions or matches), based on which accompanying behaviors execute. (See the PAPI Feature Catalog Reference for information on all criteria the API makes available, and see the Rule Trees section for instructions on how to arrange them within JSON payloads.)

  • Behaviors: Also referred to as features, these objects embedded within the rule tree instruct edge servers how to respond to requests. Your available set of behaviors depends on the selected product that enables the property. (See the PAPI Feature Catalog Reference for information on all behaviors the API makes available, and see the Rule Trees section for instructions on how to arrange them within JSON payloads.)

  • Options: Most rule behaviors and criteria specify a set of options that determine how they operate. For example, most criteria check for a specific value option, and most behaviors feature an enabled option that turns them on or off. Despite the name, some options are actually required, often depending on values set by other options.

  • Variables: Many behavior and criteria options allow you to inject variable text that interprets at runtime on edge servers, typically based on details about the client request. PAPI allows you to reference a set of built-in system variables, and create your own set of variables based on various inputs. (The Rules section discusses how to insert variables within a rule tree, and how to declare and modify your own variables.)

  • Advanced Features: Most PAPI features translate to edge metadata in clearly prescribed ways. Functionality that falls outside what these predefined behaviors and criteria can do may be implemented as customized metadata. Advanced features are read-only, and require Akamai Professional Services to configure for you. In addition, you may request any feature with sensitive data to be locked for you. (The Rules section discusses advanced and locked features.)

  • CP Codes: A content provider code is necessary to track all web traffic handled by Akamai servers. It is supplied to you when you purchase a product, and you need it to activate any associated properties. You can generate additional CP codes, typically to implement more detailed billing and reporting functions and assign to custom properties. Each property must specify at least one cpCode behavior as part of its default rule. (See the CP Codes interface and CpCode object type.)

  • Schemas: Some errors may result when a request is not in the expected format. In that case, errors reference request schemas that represent the expected structure formatted as a JSON Schema object. (See the Schemas interface and Schema object type.)

  • Rule Formats: You use rule formats to freeze or update the versioned set of behaviors and criteria a rule tree invokes. (Without this mechanism, behaviors and criteria would update automatically and generate unexpected errors.) PAPI tracks rule formats in a database keyed by rule format version date strings. These reference rule format schema objects, which specify the full set of behaviors and criteria available for a given product and the set of modules it may enable, as well as their allowed options and option values. (See the operations to List Rule Formats and Get a Rule Format’s Schema. See also the operations that list currently available behaviors and criteria.)

  • Client Settings: This API resource collects various configuration parameters for clients keyed to an authorization token. Currently it specifies only a single parameter: the default rule format version that is assigned to new properties.

Properties also include hostnames:

  • Hostnames: Each property version applies its rules to requests for a set of hostnames under your control, such as www.example.com and m.example.com. This API interface specifies that set of hostnames. You also use this interface to specify whether each hostname only uses IPv4, or whether it also allows dual-stack IPv6 traffic. (See the Property Version Hostnames interface and data object type.)

  • Edge Hostnames: Each hostname assigned to a property corresponds to an Akamai edge hostname, which is typically the hostname suffixed with edgesuite.net over HTTP or edgekey.net over secure HTTPS. For example, your source hostname m.example.com corresponds by default to the edge hostname m.example.com.edgesuite.net. This interface specifies the full set of edge hostnames under your control, regardless of how they are assigned to various properties or property versions. (See the Edge Hostnames interface and EdgeHostname object type.)

  • CNAME: For a property to serve live traffic, you must first configure your DNS server so that requests for each hostname resolves to a corresponding edge hostname, the latter referred to as the canonical name. In turn, servers across the Akamai network use their own CNAME records to resolve these edge hostnames to more specific local server names and ultimately their IP addresses.

API versioning

The API exposes several different versioning systems:

  • The version of the API is specified as part of the URL path. The current API version is v1.

  • The API supports different dated versions for the set of features available within a property’s rule tree, for example: v2015-08-17. You can freeze and smoothly update the set of features that a property’s rules apply to your content. Each behavior and criteria you invoke within your rules may independently increment versions from time to time, but the API only allows you to specify the snapshot version for the entire set of features.

    Reference documentation for the latest set of features is available in the PAPI Feature Catalog Reference. For information on features specified by older rule formats, see the following:

  • The API’s Build interface also provides details on the current software build and its accompanying catalog of behaviors and criteria. These include version numbers and extraneous commit and build dates, which bear no relation to dated rule format versions. Do not rely on any of the internal version numbers this interface makes available.

Expect internal catalog versions to update the most frequently, followed by less frequent rule format versions, followed by infrequent new API versions.

Data conventions

PAPI’s JSON data follows these overall conventions:

  • When any response data can be singular or plural, it is always represented as an array to simplify client processing. This also applies to resources that only yield a single item.

  • Parameter names always match member names in JSON requests and responses.

  • Member names are fairly specific, for example propertyVersion rather than version.

PAPI applies the following JSON member naming conventions:

  • *Name members are meant to be descriptive and human-readable (such as propertyName), and never need to appear as input to an endpoint.

  • *Id members are machine-readable identifiers (such as propertyId) often used as inputs to endpoints. The values of *Id members use the following type prefixes to help distinguish them:

    • act_ prefix for accountId
    • ctr_ prefix for contractId
    • grp_ prefix for groupId
    • prd_ prefix for productId
    • prp_ prefix for propertyId
    • ehn_ prefix for edgeHostnameId
    • hst_ prefix for hostnameId
    • atv_ prefix for activationId
    • msg_ prefix for messageId
    • cpc_ prefix for cpcodeId
  • *Date members represent date-time in ISO 8601 format using UTC timezone (such as updateDate). The API names all timestamps as *Date, they all use this same format.

  • *Link members are URLs (such as activationLink) that respond to HTTP GET requests (described by a linked json-schema document). Since API hostnames are client-specific, URLs appear as absolute-path relative reference URLs, for example /papi/v0/properties rather than https://myclient.luna.akamaiapis.net/papi/v0/properties. Clients need to establish the base URL of links from the retrieval URL. The * part of the name can informally be considered the link relation.

NOTE: As a convenience, any response that provides a *Link JSON member also provides the same information in the Location HTTP header.

Rate and resource limiting

When working with any objects whose number is capped, X-Limit-prefixed HTTP headers provide that context in responses. Overall limits adhere to this format:

  • X-Limit-Max-*-Limit
  • X-Limit-Max-*-Remaining

Some limits may depend on other variables, such as the level of service included in your contract. These appear as:

  • X-Limit-*-Per-*-Limit
  • X-Limit-*-Per-*-Remaining

Anything that’s limited to periods of time uses this format, where Reset provides the epoch time at which the Remaining value resets to the overall Limit:

  • X-RateLimit-*-Limit
  • X-RateLimit-*-Remaining
  • X-RateLimit-*-Reset

Note that you may have the option to override these limits. Contact your Akamai representative for more information.

PAPI reports the following set of contextual HTTP headers:

  • X-Limit-Edgehostnames-Per-Contract-Limit
  • X-Limit-Edgehostnames-Per-Contract-Remaining
  • X-Limit-Properties-Per-Contract-Limit
  • X-Limit-Properties-Per-Contract-Remaining
  • X-Limit-Hosts-Per-Property-Limit
  • X-Limit-Hosts-Per-Property-Remaining
  • X-Limit-Clientip-Per-Property-Limit
  • X-Limit-Clientip-Per-Property-Remaining
  • X-Limit-Elements-Per-Property-Limit
  • X-Limit-Elements-Per-Property-Remaining
  • X-Limit-Max-Clientip-Per-Match-Limit
  • X-Limit-Max-Clientip-Per-Match-Remaining
  • X-Limit-Max-Nested-Rules-Limit
  • X-Limit-Max-Nested-Rules-Remaining
  • X-RateLimit-Activations-Limit
  • X-RateLimit-Activations-Remaining
  • X-RateLimit-Activations-Reset

Concurrency control

PAPI provides support for optimistic concurrency control on its property version, property hostname, and rule resources. When reading data from any of these resources, an opaque digest string representing a snapshot of the property version is available from the following:

  • An etag object member.
  • The double-quoted contents of the Etag HTTP header.

When performing any subsequent write operation (POST, PUT, PATCH, or DELETE), provide the same data as either of the following:

  • An etag object member.
  • The double-quoted contents of the If-Match HTTP header.

The request succeeds if the digest matches the current state of the resource’s data, otherwise it produces a 412 error. This prevents outdated representations from being used as the basis for updates when more than one client accesses the same resource. It keeps you from overwriting other users’ data, regardless of whether they access it with PAPI or the Luna portal’s Property Manager interface.

NOTE: Within the Etag or If-Match HTTP headers, the data digest must be double-quoted, or the request fails even if the digest otherwise appears to match. Also, you can only use the If-Match HTTP header when writing property hostnames, because that interface specifies an array, which can’t accommodate a top-level etags object member.

PAPI provides several other ways to use this mechanism:

  • When creating a new property version, passing the request’s createFromVersionEtag member back in as an etag ensures the component hostnames or rules of the version on which it was based have not changed in the interim.

  • When cloning a property, passing the request’s cloneFromVersionEtag member back in as an etag ensures the component hostnames or rules of the property version on which it was based have not changed in the interim.

PAPI tracks changes to data for the entire property version. Suppose you read a property version’s rule tree along with its etag digest. Another client then modifies the property version’s set of hostnames. When you write the rule tree back along with the etag, the request fails because one of the version’s components has been modified.

NOTE: The Network Lists API uses the term Sync Point to refer to the same concurrency control feature.

Validation and activation time

PAPI’s most important function is to modify rule trees associated with sets of hostnames, and to activate them on the edge. As described in the Rule Trees section, rule trees are potentially very large, complex objects that often require frequent, iterative optimizations.

Under PAPI’s traditional development cycle, each time you modify and save a rule tree, you would need to wait for a lengthy set of validation tests to complete, making an iterative development cycle more difficult. The current API release provides two shortcuts to speed up development:

Both the rule tree and the set of hostnames are part of the same property definition for which there is a single validation process. The benefits of routinely deferring validation increases along with the size of the rule tree, and with the number of hostnames you assign it to. When you defer validation, the response object comes to you more quickly, and without its usual errors and warnings arrays described in the JSON Problems section. Note that you still need to fix any errors, and to either fix or acknowledge any warnings. To get this information, you need to enable validation again before activating the property.

In general, expect validation to accelerate over time. Once a property is ready, the amount of time it takes to activate it across the Akamai network has also decreased dramatically. While activation times have been speeding up, they remain relatively slow in two cases:

  • when you activate a property for the first time.

  • whenever the set of deployed hostnames changes.

Contact your Akamai representative for guidance on latency for property activations.

Resources

This section provides details for the workflow through PAPI, and tells you how to interact with each operation. This provides you with a high-level overview to the PAPI workflow:

See PAPI Concepts to learn more about how these resources relate to each other. For information on specific operations, the table below summarizes all of the basic actions the API enables, along with their corresponding combinations of methods and endpoints.

API summary

Operation Method Endpoint
Groups  
List Groups GET /papi/v0/groups/
Contracts  
List Contracts GET /papi/v0/contracts/
Products  
List Products GET /papi/v0/products/{?contractId}
CP Codes  
List CP Codes GET /papi/v0/cpcodes/{?contractId,groupId}
Create a New CP Code POST /papi/v0/cpcodes/{?contractId,groupId}
Get a CP Code GET /papi/v0/cpcodes/{cpcodeId}{?contractId,groupId}
Edge Hostnames  
List Edge Hostnames GET /papi/v0/edgehostnames/{?contractId,groupId,options}
Create a New Edge Hostname POST /papi/v0/edgehostnames/{?contractId,groupId,options}
Get an Edge Hostname GET /papi/v0/edgehostnames/{edgeHostnameId}{?contractId,groupId,options}
Properties  
List Properties GET /papi/v0/properties/{?contractId,groupId}
Create or Clone a Property POST /papi/v0/properties/{?contractId,groupId}
Get a Property GET /papi/v0/properties/{propertyId}{?contractId,groupId}
Remove a Property DELETE /papi/v0/properties/{propertyId}{?contractId,groupId}
Property Versions  
List Versions GET /papi/v0/properties/{propertyId}/versions/{?contractId,groupId}
Create a New Version POST /papi/v0/properties/{propertyId}/versions/{?contractId,groupId}
Get a Version GET /papi/v0/properties/{propertyId}/versions/{propertyVersion}{?contractId,groupId}
Get the Latest Version GET /papi/v0/properties/{propertyId}/versions/latest{?contractId,groupId,activatedOn}
List Available Behaviors GET /papi/v0/properties/{propertyId}/versions/{propertyVersion}/available-behaviors{?contractId,groupId}
List Available Criteria GET /papi/v0/properties/{propertyId}/versions/{propertyVersion}/available-criteria{?contractId,groupId}
Property Version Hostnames  
List a Property’s Hostnames GET /papi/v0/properties/{propertyId}/versions/{propertyVersion}/hostnames/{?contractId,groupId}
Update a Property’s Hostnames PUT /papi/v0/properties/{propertyId}/versions/{propertyVersion}/hostnames/{?contractId,groupId,validateHostnames}
Property Version Rules  
Get a Rule Tree GET /papi/v0/properties/{propertyId}/versions/{propertyVersion}/rules/{?contractId,groupId}
Get a Rule Tree’s Digest HEAD /papi/v0/properties/{propertyId}/versions/{propertyVersion}/rules/{?contractId,groupId}
Update a Rule Tree PUT /papi/v0/properties/{propertyId}/versions/{propertyVersion}/rules/{?contractId,groupId,validateRules}
Property Search  
Search Properties GET /papi/v0/search/find-by-value
Property Activations  
List Activations GET /papi/v0/properties/{propertyId}/activations/{?contractId,groupId}
Activate a Property POST /papi/v0/properties/{propertyId}/activations/{?contractId,groupId}
Get an Activation GET /papi/v0/properties/{propertyId}/activations/{activationId}{?contractId,groupId}
Cancel a Pending Activation DELETE /papi/v0/properties/{propertyId}/activations/{activationId}{?contractId,groupId}
Rule Formats  
List Rule Formats GET /papi/v0/rule-formats
Schemas  
Get a Request’s Schema GET /papi/v0/schemas/request/{filename}
Get a Rule Format’s Schema GET /papi/v0/schemas/products/{productId}/{ruleFormat}
Client Settings  
Get Client Settings GET /papi/v0/client-settings
Update Client Settings PUT /papi/v0/client-settings
Build  
Get Build Details GET /papi/v0/build

List groups

You need information about the prevailing group to access most PAPI interfaces. This operation provides a read-only list of groups, which may contain properties. (The User Admin API allows you to modify the group hierarchy.) This operation provides a flat list of groups, along with parentGroupId information to structure them as a hierarchy. Each group also lists any available contracts that enable property features, but not which group is associated with a given property. The User Admin API allows you to associate properties with groups.

GET /papi/v0/groups/

Status 200 application/json

Response:

{
    "accountId": "act_1-1TJZFB",
    "accountName": "Example.com",
    "groups": {
        "items": [
            {
                "groupName": "Example.com-1-1TJZH5",
                "groupId": "grp_15225",
                "contractIds": [ "ctr_1-1TJZH5" ]
            },
            {
                "groupName": "Test",
                "groupId": "grp_15231",
                "parentGroupId": "grp_15225",
                "contractIds": [ "ctr_1-1TJZH5" ]
            },
            {
                "groupName": "TomTest",
                "groupId": "grp_41443",
                "parentGroupId": "grp_15225",
                "contractIds": [ "ctr_1-1TJZH5" ]
            }
        ]
    }
}

  1. GET a list of groups from /papi/v0/groups/.

  2. Select the appropriate group object from the JSON’s groups.items array.

  3. Store the object’s grp_-prefixed groupId.

List contracts

You need information about the prevailing contract to access most PAPI interfaces. This operation provides a read-only list of contract names and identifiers. The response provides context on the overall account (prefixed act_) that enables each contract and keys your API credentials, but you do not need it to access any PAPI objects.

GET /papi/v0/contracts/

Status 200 application/json

Response:

{
    "accountId": "act_1-1TJZFB",
    "contracts": {
        "items": [
            {
                "contractId": "ctr_1-1TJZH5",
                "contractTypeName": "Direct Customer"
            }
        ]
    }
}

  1. GET the list of contracts from /papi/v0/contracts/.

  2. Select the appropriate contract object from the JSON’s contracts.items array.

  3. Store the object’s ctr_-prefixed contractId.

List products

This operation lists the set of products that are available under a given contract. You need a product identifier to create new edge hostnames, CP codes, or properties. The range of rule behaviors available within a property is determined by the assigned product.

GET /papi/v0/products/{?contractId}

Example: /papi/v0/products/?contractId=ctr_1–1TJZH5

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.

Status 200 application/json

Response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "products": {
        "items": [
            {
                "productName": "Alta",
                "productId": "prd_Alta"
            }
        ]
    }
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. GET a list of products from /papi/v0/products/{?contractId}

  3. Select the appropriate product object from the JSON’s products.items array.

  4. Store the object’s prd_-prefixed productId.

List CP codes

This operation lists CP codes available within your contract/group pairing, which you assign to a property within its rule tree. CP codes include information about the product under which they were generated. When creating a new property, you should apply the same product under which the associated CP code was created.

GET /papi/v0/cpcodes/{?contractId,groupId}

Example: /papi/v0/cpcodes/?contractId=ctr_1–1TJZFW&groupId=grp_15166

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZFW Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15166 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.

Status 200 application/json

Response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZFW",
    "groupId": "grp_15225",
    "cpcodes": {
        "items": [
            {
                "cpcodeId": "cpc_33190",
                "cpcodeName": "SME WAA",
                "productIds": [ "prd_Web_App_Accel" ],
                "createdDate": "2015-03-02T15:06:13Z"
            }
        ]
    }
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List CP codes from /papi/v0/cpcodes/{?contractId,groupId}.

  4. Select the appropriate CpCode object from the JSON’s cpcodes.items array.

  5. Store the object’s cpc_-prefixed cpcodeId.

Create a new CP code

To create a new CP code, you need to associate it with a product. You can assign any CP code within a property’s rule tree as detailed in the Rule Trees section. You should match the same productId that’s assigned to properties that invoke the CP code to the one assigned to the CP code, otherwise you may get a warning.

POST /papi/v0/cpcodes/{?contractId,groupId}

Example: /papi/v0/cpcodes/?contractId=ctr_1–1TJZFW&groupId=grp_15166

Content-Type: application/json

Request:

{
    "productId": "prd_Web_App_Accel",
    "cpcodeName": "SME WAA"
}

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZFW Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15166 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.

Status 201 application/json

Headers:

  • Location: /papi/v0/cpcodes/cpc_33190?contractId=ctr_1-1TJZFW&groupId=grp_15166

Response:

{
    "cpcodeLink": "/papi/v0/cpcodes/cpc_33190?contractId=ctr_1-1TJZFW&groupId=grp_15166"
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Products from /papi/v0/products{?contractId} and store the relevant productId with which to enable the CP code.

  4. Build a CpCode POST object.

  5. POST the object to /papi/v0/cpcodes/{?contractId,groupId}.

  6. Optionally GET the new CP code from the response’s cpcodeLink or Location header.

Get a CP code

This operation gets details about a CP code.

GET /papi/v0/cpcodes/{cpcodeId}{?contractId,groupId}

Example: /papi/v0/cpcodes/cpc_33190?contractId=ctr_1–1TJZFW&groupId=grp_15166

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZFW Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
cpcodeId String cpc_33190 Unique identifier for the CP code. Remove the cpc_ prefix if using the value in other Akamai APIs.
groupId String grp_15166 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.

Status 200 application/json

Response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZFW",
    "groupId": "grp_15166",
    "cpcodes": {
        "items": [
            {
                "cpcodeId": "cpc_33190",
                "cpcodeName": "SME WAA",
                "productIds": [ "prd_Web_App_Accel" ],
                "createdDate": "2015-03-02T15:06:13Z"
            }
        ]
    }
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List CP Codes from /papi/v0/cpcodes/{?contractId,groupId} and and store the relevant cpcodeId.

  4. GET the CP code from /papi/v0/cpcodes/{cpcodeId}{?contractId,groupId}.

  5. Store the object’s cpc_-prefixed cpcodeId.

List edge hostnames

This lists all edge hostnames available under a contract. You assign these hostnames to a property as a separate operation.

GET /papi/v0/edgehostnames/{?contractId,groupId,options}

Example: /papi/v0/edgehostnames/?contractId=ctr_1–1TJZH5&groupId=grp_15255&options=mapDetails

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15255 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
Optional
options String mapDetails Comma-separated list of options to enable; mapDetails enables extra mapping-related information.

Status 200 application/json

Headers:

  • X-Limit-Edgehostnames-Per-Contract-Limit: 100
  • X-Limit-Edgehostnames-Per-Contract-Remaining: 98

Response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "edgeHostnames": {
        "items": [
            {
                "edgeHostnameId": "ehn_895822",
                "edgeHostnameDomain": "example.com.edgekey.net",
                "productId": "prd_Alta",
                "domainPrefix": "example.com",
                "domainSuffix": "edgekey.net",
                "status": "PENDING",
                "secure": true,
                "ipVersionBehavior": "IPV4",
                "mapDetails:serialNumber": 79,
                "mapDetails:slotNumber": 11,
                "mapDetails:mapDomain": "e79.x.akamaiedge.net"
            },
            {
                "edgeHostnameId": "ehn_887436",
                "edgeHostnameDomain": "example.com.edgesuite.net",
                "productId": "prd_Alta",
                "status": "ACTIVE",
                "domainPrefix": "example.com",
                "domainSuffix": "edgesuite.net",
                "secure": false,
                "ipVersionBehavior": "IPV4",
                "mapDetails:serialNumber": 1951,
                "mapDetails:mapDomain": "a1951.g.akamai.net"
            }
        ]
    }
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. GET the edge hostname list from /papi/v0/edgehostnames/{?contractId,groupId}

  4. EdgeHostname objects are listed within the response’s edgeHostnames.items array.

Create a new edge hostname

This operation creates a new edge hostname. Once the hostname is active, you can assign it to a property. After activating the property, modifying your DNS to map the origin hostname to the edge hostname ultimately enables traffic. See Enable Traffic for a New Edge Hostname for details.

Note that PAPI does not allow you to create new secure edge hostnames, but you can do this using the Secure Provisioning Service API. Once secure hostnames are queued, list all the edge hostnames in PAPI to confirm their activation status.

POST /papi/v0/edgehostnames/{?contractId,groupId,options}

Example: /papi/v0/edgehostnames/?contractId=ctr_1–1TJZH5&groupId=grp_15255&options=mapDetails

Content-Type: application/json

Request:

{
    "productId": "prd_PPP",
    "domainPrefix": "www.example.com",
    "domainSuffix": "edgesuite.net",
    "secure": true,
    "ipVersionBehavior": "IPV4",
    "slotNumber": 12345
}

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15255 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
Optional
options String mapDetails Comma-separated list of options to enable; mapDetails enables extra mapping-related information.

Status 201 application/json

Headers:

  • Location: /papi/v0/edgehostnames/ehn_1332?contractId=ctr_1-1TJZH5&groupId=grp_15225
  • X-Limit-Edgehostnames-Per-Contract-Limit: 100
  • X-Limit-Edgehostnames-Per-Contract-Remaining: 97

Response:

{
    "edgeHostnameLink": "/papi/v0/edgehostnames/ehn_1332?contractId=ctr_1-1TJZH5&grp_15225"
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups, choose the relevant group, and store its groupId.

  3. List Products from /papi/v0/products{?contractId} and store the relevant productId with which to enable the edge hostname.

  4. Build an EdgeHostname POST object.

    • For a standard edge hostname, set secure to false. This boolean flag does not refer to HTTPS, but to whatever additional level of security options the product enables. To create a secure edge hostname, you need to use the Secure Provisioning Service API instead.

    • Setting the request’s ipVersionBehavior to IPV6_COMPLIANCE allows both IPv4 and IPv6, but you need to be careful your origin servers support the latter.

    • Set the domainPrefix to the origin hostname, for example custom.example.com.

    • Set the domainSuffix to edgesuite.net.

  5. POST the object to /papi/v0/edgehostnames/{?contractId,groupId}.

  6. Optionally GET the new edge hostname from the response’s edgeHostnameLink or Location header to poll its deployment status.

Enable traffic for a new edge hostname

After creating a new edge hostname, assigning it to a property, and activating the property, you still need to modify your DNS configuration to direct the origin’s traffic to the new edge hostname, otherwise known as Akamaizing your content.

Edge hostnames are formed from the combined domainPrefix and domainSuffix included in the POST request, in this case custom.example.com.edgesuite.net to indicate standard HTTP traffic:

{
    "productId": "prd_PPP",
    "domainPrefix": "custom.example.com",
    "domainSuffix": "edgesuite.net",
    "secure": true,
    "ipVersionBehavior": "IPV4",
    "slotNumber": 12345
}

(HTTPS typically uses an edgekey.net suffix.) The POST request tells Akamai’s network of DNS servers to map it to local server names, but for the hostname to ultimately activate, you need to update your own DNS record to map your origin hostname to the edge hostname. A resulting DNS resolution looks like this:

$ host -v custom.example.com
Trying "custom.example.com"
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 14682
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;custom.example.com.            IN      A

;; ANSWER SECTION:
custom.example.com.     300     IN      CNAME   custom.example.com.edgekey.net.
custom.example.com.edgekey.net. 3701 IN CNAME   e79.x.akamaiedge.net.
e79.x.akamaiedge.net.   11      IN      A       72.246.8.105

The first CNAME entry maps your custom.example.com domain to the edge hostname custom.example.com.edgekey.net, required for traffic to flow to the edge hostname. POSTing the new edge hostname implements the second CNAME, which in this case maps the edge hostname to the local hostname e79.x.akamaiedge.net, and in turn to a local IP address.

Get an edge hostname

This polls the state of an edge hostname, typically after creating a new edge hostname. The response tells you whether the CNAME has been fully distributed across the network. If the hostname’s status is ACTIVE, the process is complete. Until then, you typically see values of ZONE1, ZONE2, ZONE3, or simply PENDING.

GET /papi/v0/edgehostnames/{edgeHostnameId}{?contractId,groupId,options}

Example: /papi/v0/edgehostnames/ehn_887436?contractId=ctr_1–1TJZH5&groupId=grp_15255&options=mapDetails

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
edgeHostnameId String ehn_887436 Unique identifier for the edge hostname. Remove the ehn_ prefix if using the value in other Akamai APIs.
groupId String grp_15255 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
Optional
options String mapDetails Comma-separated list of options to enable; mapDetails enables extra mapping-related information.

Status 200 application/json

Response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "edgeHostnames": {
        "items": [
            {
                "edgeHostnameId": "ehn_887436",
                "edgeHostnameDomain": "example.com.edgesuite.net",
                "productId": "prd_Alta",
                "status": "ACTIVE",
                "domainPrefix": "example.com",
                "domainSuffix": "edgesuite.net",
                "secure": false,
                "ipVersionBehavior": "IPV4",
                "mapDetails:serialNumber": 1951,
                "mapDetails:mapDomain": "a1951.g.akamai.net"
            }
        ]
    }
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Edge Hostnames from /papi/v0/edgehostnames/{?contractId,groupId} and store the relevant edgeHostnameId.

  4. GET the edge hostname from /papi/v0/edgehostnames/{edgeHostnameId}{?contractId,groupId}.

  5. The EdgeHostname object is available within the response’s single-item edgeHostnames.items array.

List properties

This operation lists properties available for the current contract and group.

GET /papi/v0/properties/{?contractId,groupId}

Example: /papi/v0/properties/?contractId=ctr_1–1TJZH5&groupId=grp_15225

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.

Status 200 application/json

Headers:

  • X-Limit-Properties-Per-Contract-Limit: 100
  • X-Limit-Properties-Per-Contract-Remaining: 99

Response:

{
    "properties": {
        "items": [
            {
                "accountId": "act_1-1TJZFB",
                "contractId": "ctr_1-1TJZH5",
                "groupId": "grp_15225",
                "propertyId": "prp_175780",
                "propertyName": "example.com",
                "latestVersion": 2,
                "stagingVersion": 1,
                "productionVersion": null,
                "note": "Notes about example.com"
            },
            {
                "accountId": "act_1-1TJZFB",
                "contractId": "ctr_1-1TJZH5",
                "groupId": "grp_15225",
                "propertyId": "prp_175781",
                "propertyName": "m.example.com",
                "latestVersion": 1,
                "stagingVersion": null,
                "productionVersion": null,
                "note": "Notes about m.example.com"
            }
        ]
    }
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. GET the list of properties from /papi/v0/properties/{?contractId,groupId}.

  4. Property objects are available from the response’s properties.items array.

Create or clone a property

This operation either creates a new property from scratch, or bases one on another property’s rule tree and optionally its set of assigned hostnames.

POST /papi/v0/properties/{?contractId,groupId}

Example: /papi/v0/properties/?contractId=ctr_1–1TJZH5&groupId=grp_15225

Content-Type: application/json

Request:

{
    "productId": "prd_Alta",
    "propertyName": "my.new.property.com",
    "cloneFrom": {
        "propertyId": "prp_175780",
        "version": 2,
        "cloneFromVersionEtag": "a9dfe78cf93090516bde891d009eaf57",
        "copyHostnames": true
    }
}

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.

Status 201 application/json

Headers:

  • Location: /papi/v0/properties/prp_173137?contractId=ctr_1-1TJZH5&groupId=grp_15225
  • X-Limit-Properties-Per-Contract-Limit: 100
  • X-Limit-Properties-Per-Contract-Remaining: 98

Response:

{
    "propertyLink": "/papi/v0/properties/prp_173137?contractId=ctr_1-1TJZH5&groupId=grp_15225"
}

Gather prerequisites:

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Products from /papi/v0/products{?contractId} and store the relevant productId with which to enable the property.

To create a property from scratch:

  1. Optionally List Rule Formats from /papi/v0/rule-formats and store the desired feature catalog version.

  2. Build a Property POST object, optionally specifying the rule format, as in the example below.

To clone a property:

  1. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId from the property you want to clone.

  2. List the property’s versions from /papi/v0/properties/{propertyId}/versions/{?contractId,groupId} and select the version you want to clone.

  3. Store the version’s propertyVersion and etag.

  4. Build a Property POST object.

  5. Add a Property.cloneFrom sub-object.

POST the request:

  1. POST the object to /papi/v0/properties/{?contractId,groupId}.

  2. Optionally GET the new property from the response’s propertyLink or Location header.

When cloning with copyHostnames enabled, you can apply the same set of hostnames as the original property. Regardless, the new property clones the rule tree from the original, along with its assigned ruleFormat. Setting cloneFromVersionEtag allows you to perform an etags check to ensure the original property has not changed.

Note that unlike a new property version, a property that you clone along with all of its hostnames can be activated independently of the property on which it was based. If you activate a property that specifies hostnames that are already active on another property, the other property automatically gets a new version activated without the common set of hostnames, or deactivated if all its hostnames are part of the new property.

PAPI’s ability to create and clone new properties means that you can design a system of rule templates targeted to specific domains, rather than maintain a single set of rules with conditional logic for your full range of domains. Maintaining properties manually within the Luna Control Center interface limited you to that more consolidated approach, but PAPI allows you to deploy rules more efficiently. In either case, PAPI makes it much easier for you to support a large, flexible set of domains.

Get a property

This operation gets a specific property. You can call this operation by specifying any of the propertyId members from a list of properties, or by running a GET on the propertyLink response when creating a new property:

GET /papi/v0/properties/{propertyId}{?contractId,groupId}

Example: /papi/v0/properties/prp_175780?contractId=ctr_1–1TJZH5&groupId=grp_15225

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_175780 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.

Status 200 application/json

Response:

{
    "properties": {
        "items": [
            {
                "accountId": "act_1-1TJZFB",
                "contractId": "ctr_1-1TJZH5",
                "groupId": "grp_15225",
                "propertyId": "prp_175780",
                "propertyName": "example.com",
                "latestVersion": 2,
                "stagingVersion": 1,
                "productionVersion": null,
                "note": "Notes about example.com"
            }
        ]
    }
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  4. GET the property from /papi/v0/properties/{propertyId}{?contractId,groupId}

  5. The Property object is available in the response’s single-item properties.items array.

Remove a property

Removes a specific property, which you can only do if none of its versions are currently active. Activating another property with the same set of hostnames automatically triggers a deactivation on the targeted property. See Create a New Activation for details.

A successful DELETE results in a 200 response with the link to the remaining properties for the given contract and group. Attempting to delete an active property results in a 666 error. Attempting to delete an unknown property results in a 404 error.

DELETE /papi/v0/properties/{propertyId}{?contractId,groupId}

Example: /papi/v0/properties/prp_175780?contractId=ctr_1–1TJZH5&groupId=grp_15225

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_175780 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.

Status 200 application/json

Response:

{
    "message" : "Deletion Successful."
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  4. Make a DELETE request to /papi/v0/properties/{propertyId}{?contractId,groupId}

List versions

List all versions of a property. Each property version indicates activation status on different networks, and an etag digest useful in cloning the property.

GET /papi/v0/properties/{propertyId}/versions/{?contractId,groupId}

Example: /papi/v0/properties/prp_173136/versions/?contractId=ctr_1–1TJZH5&groupId=grp_15225

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_173136 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.

Status 200 application/json

Response:

{
    "propertyId": "prp_173136",
    "propertyName": "981.catalog.amenai.net",
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "versions": {
        "items": [
            {
                "propertyVersion": 2,
                "updatedByUser": "amenai",
                "updatedDate": "2014-05-10T19:06:13Z",
                "productionStatus": "INACTIVE",
                "stagingStatus": "ACTIVE",
                "etag": "5891b5b522d5df08",
                "productId": "prd_Alta",
                "note": "updated caching"
            },
            {
                "propertyVersion": 1,
                "updatedByUser": "afaden",
                "updatedDate": "2013-05-04T21:12:57Z",
                "productionStatus": "ACTIVE",
                "stagingStatus": "INACTIVE",
                "etag": "71573b922a87abc3",
                "productId": "prd_Alta",
                "note": "initial version"
            }
        ]
    }
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  4. GET a list of versions from /papi/v0/properties/{propertyId}/versions/{?contractId,groupId}.

  5. Version objects are available from the response’s versions.items array.

Create a new version

Create a new property version based on any previous version. All data from the createFromVersion populates the new version, including its rules and hostnames. Specify createFromVersionEtag if you want to ensure you are creating from a version that has not changed since you fetched it.

POST /papi/v0/properties/{propertyId}/versions/{?contractId,groupId}

Example: /papi/v0/properties/prp_173136/versions/?contractId=ctr_1–1TJZH5&groupId=grp_15225

Content-Type: application/json

Request:

{
    "createFromVersion": 1,
    "createFromVersionEtag": "2641910c585cf67b"
}

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_173136 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.

Status 201 application/json

Headers:

  • Location: /papi/v0/properties/prp_173136/versions/2?contractId=ctr_1-1TJZH5&groupId=grp_15225

Response:

{
    "versionLink": "/papi/v0/properties/prp_173136/versions/2?contractId=ctr_1-1TJZH5&groupId=grp_15225"
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  4. List the property’s versions from /papi/v0/properties/{propertyId}/versions/{?contractId,groupId} and store the relevant version’s propertyVersion.

  5. Build a Property POST object.

  6. POST the object to /papi/v0/properties/{propertyId}/versions/{?contractId,groupId}.

  7. Optionally GET the new version from the response’s versionLink or Location header.

Get a version

This polls the state of a specific property version, for example to check its activation status.

When specifying Accept: text/xml, this resource provides the Akamai metadata configuration data that is distributed to edge servers when the property version is activated. This XML data encapsulates the property version’s component rules and hostnames, and is available on a read-only basis. Contact your Akamai representative if you need help interpreting it.

GET /papi/v0/properties/{propertyId}/versions/{propertyVersion}{?contractId,groupId}

Example: /papi/v0/properties/prp_173136/versions/3?contractId=ctr_1–1TJZH5&groupId=grp_15225

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_173136 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.
propertyVersion Integer 3 Property’s incremental version number.

Status 200 application/json

Headers:

  • Etag: "71573b922a87abc3"

Response:

{
    "propertyId": "prp_173136",
    "propertyName": "981.calatog.amenai.net",
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "versions": {
        "items": [
            {
                "propertyVersion": 1,
                "updatedByUser": "afaden",
                "updatedDate": "2014-03-04T21:12:57Z",
                "productionStatus": "ACTIVE",
                "stagingStatus": "INACTIVE",
                "etag": "71573b922a87abc3",
                "productId": "prd_Alta",
                "ruleFormat": "latest",
                "note": "initial version"
            }
        ]
    }
}

Status 200 text/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<configs xmlns:cache="uri:akamai.com/metadata/cache/5.0" xmlns:edgeservices="uri:akamai.com/metadata/edgeservices/5.0" xmlns:config="uri:akamai.com/metadata/config/5.0" xmlns:network="uri:akamai.com/metadata/network/5.0" xmlns:auth="uri:akamai.com/metadata/auth/5.0" xmlns:match="uri:akamai.com/metadata/match/5.0" xmlns:forward="uri:akamai.com/metadata/forward/5.0" xmlns:comment="uri:akamai.com/metadata/comment/5.0" xmlns:akamai="uri:akamai.com/metadata/akamai/5.0" xmlns:security="uri:akamai.com/metadata/security/5.0" xmlns:reporting="uri:akamai.com/metadata/reporting/5.0" xmlns:edgecomputing="uri:akamai.com/metadata/edgecomputing/5.0" xmlns:assign="uri:akamai.com/metadata/assign/5.0">
    <comment:note value="Property Manager generated metadata. XML engine version: 14.2.1"/>
    <comment:note value="Catalog version: 14.4.4"/>
    <comment:note value="Product name: Site_Accel"/>
    <comment:note value="Property name: example.com, version: 33"/>
    <comment:note value="Asset ID: 99999"/>
    <comment:note value="AcgID: "/>
    <comment:note value="AccountId: 1-7KLGH"/>
    <comment:note value="Hostnames: www.example.com"/>
</configs>
  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Products from /papi/v0/products{?contractId} and store the relevant productId with which to enable the property.

  4. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  5. List the property’s versions from /papi/v0/properties/{propertyId}/versions/{?contractId,groupId} and store the relevant propertyVersion.

  6. Optionally to get XML metadata, specify an Accept: text/xml header.

  7. GET the version from /papi/v0/properties/{propertyId}/versions/{propertyVersion}{?contractId,groupId}.

  8. The Version object is available from the response’s single-item versions.items array.

Get the latest version

This operation provides either the latest property version overall, or the latest one active on the production or staging networks. By default, the response yields the property version with the highest number. Specifying an activatedOn of STAGING or PRODUCTION yields the version that’s currently active on either network.

GET /papi/v0/properties/{propertyId}/versions/latest{?contractId,groupId,activatedOn}

Example: /papi/v0/properties/prp_173136/versions/latest?contractId=ctr_1–1TJZH5&groupId=grp_15225&activatedOn=STAGING

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_173136 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.
Optional
activatedOn String STAGING If present, returns the latest version activated on the given network.

Status 302 application/json

Headers:

  • Location: /papi/v0/properties/prp_173136/versions/2?contractId=ctr_1-1TJZH5&groupId=grp_15225

Response:

{
    "versionLink": "/papi/v0/properties/prp_173136/versions/2?contractId=ctr_1-1TJZH5&groupId=grp_15225"
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Products from /papi/v0/products{?contractId} and store the relevant productId with which to enable the property.

  4. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  5. Optionally set the activatedOn query parameter to PRODUCTION or STAGING to get the latest activated version.

  6. GET the latest version from /papi/v0/properties/{propertyId}/versions/latest{?contractId,groupId,activatedOn}.

  7. Make another GET request on the response object’s versionLink or Location header.

List available behaviors

Lists behaviors you may apply within a property version’s rules. The available set is determined by the product under which you created the property, and any additional modules enabled under your account.

Note that this list of available behaviors is more accurate than that specified in the rule format schema, which includes behaviors you may potentially add to your contract for a given product, but that are not currently active. However, it only lists behaviors currently available on your contract, so you should only use it to list available behaviors for the current property version. If you had a behavior enabled at one time, but then dropped it from your contract, a list of available behaviors for an older property version might be inaccurate.

GET /papi/v0/properties/{propertyId}/versions/{propertyVersion}/available-behaviors{?contractId,groupId}

Example: /papi/v0/properties/prp_173136/versions/3/available-behaviors?contractId=ctr_1–1TJZH5&groupId=grp_15225

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_173136 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.
propertyVersion Integer 3 Property’s incremental version number.

Status 200 application/json

Response:

{
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "productId": "prd_Alta",
    "ruleFormat": "v2015-08-08",
    "availableBehaviors": {
        "items": [
            {
                "name": "cpCode",
                "schemaLink": "/papi/v0/schemas/products/prd_Alta/latest#/definitions/catalog/behaviors/cpCode"
            },
            {
                "name": "origin",
                "schemaLink": "/papi/v0/schemas/products/prd_Alta/latest#/definitions/catalog/behaviors/origin"
            }
        ]
    }
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  4. List the property’s versions from /papi/v0/properties/{propertyId}/versions/{?contractId,groupId} and store the relevant version’s propertyVersion.

  5. GET the list of behaviors from /papi/v0/properties/{propertyId}/versions/{propertyVersion}/available-behaviors{?contractId,groupId}.

  6. Data is listed in the response’s availableBehaviors.items array, either the name of the behavior or the rule format schemaLink that describes its basic requirements.

List available criteria

Lists criteria you may apply within a property version’s rules. The available set is determined by the product under which you created the property, and any additional modules enabled under your account.

Note that this list of available criteria is more accurate than that specified in the rule format schema, which includes criteria you may potentially add to your contract for a given product, but that are not currently active. However, it only lists criteria currently available on your contract, so you should only use it to list available criteria for the current property version. If you had a behavior enabled at one time, but then dropped it from your contract, a list of available criteria for an older property version might be inaccurate.

GET /papi/v0/properties/{propertyId}/versions/{propertyVersion}/available-criteria{?contractId,groupId}

Example: /papi/v0/properties/prp_173136/versions/3/available-criteria?contractId=ctr_1–1TJZH5&groupId=grp_15225

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_173136 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.
propertyVersion Integer 3 Property’s incremental version number.

Status 200 application/json

Response:

{
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "productId": "prd_Alta",
    "ruleFormat": "v2015-08-08",
    "availableCriteria": {
        "items": [
            {
                "name": "fileExtension",
                "schemaLink": "/papi/v0/schemas/products/prd_Alta/latest#/definitions/catalog/criteria/fileExtension"
            },
            {
                "name": "hostname",
                "schemaLink": "/papi/v0/schemas/products/prd_Alta/latest#/definitions/catalog/criteria/hostname"
            }
        ]
    }
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  4. List the property’s versions from /papi/v0/properties/{propertyId}/versions/{?contractId,groupId} and store the relevant version’s propertyVersion.

  5. GET the list of criteria from /papi/v0/properties/{propertyId}/versions/{propertyVersion}/available-criteria{?contractId,groupId}.

  6. Data is listed in the response’s availableCriteria.items array, either the name of the criteria or the rule format schemaLink that describes its basic requirements.

List a property’s hostnames

This lists all the hostnames assigned to a property version, which may be a subset of all available edge hostnames.

GET /papi/v0/properties/{propertyId}/versions/{propertyVersion}/hostnames/{?contractId,groupId}

Example: /papi/v0/properties/prp_175780/versions/1/hostnames/?contractId=ctr_1–1TJZH5&groupId=grp_15255

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15255 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_175780 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.
propertyVersion Integer 1 Property’s incremental version number.

Status 200 application/json

Headers:

  • ETag: "6aed418629b4e5c0"
  • X-Limit-Hosts-Per-Property-Limit: 100
  • X-Limit-Hosts-Per-Property-Remaining: 98

Response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_175780",
    "propertyVersion": 1,
    "etag": "6aed418629b4e5c0",
    "hostnames": {
        "items": [
            {
                "cnameType": "EDGE_HOSTNAME",
                "edgeHostnameId": "ehn_895822",
                "cnameFrom": "example.com",
                "cnameTo": "example.com.edgesuite.net"
            },
            {
                "cnameType": "EDGE_HOSTNAME",
                "edgeHostnameId": "ehn_895833",
                "cnameFrom": "m.example.com",
                "cnameTo": "m.example.com.edgesuite.net"
            }
        ]
    }
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  4. List the property’s versions from /papi/v0/properties/{propertyId}/versions/{?contractId,groupId} and store the relevant version’s propertyVersion.

  5. GET the list of hostnames from /papi/v0/properties/{propertyId}/versions/{propertyVersion}/hostnames/{?contractId,groupId}.

  6. Hostname objects are available in the response’s hostnames.items array.

Update a property’s hostnames

Modify the set of hostname entries for a property version. For each hostname entry, the cnameFrom is required along with either the cnameTo or edgeHostnameId.

There are no POST or DELETE operations to add or remove hostnames from a property, so to assign them you need to make a PUT request that specifies the entire set as an array. Since the data sent in the PUT request is an array, adding an If-Match HTTP header is the only way to prevent overwriting edits from another client. See Concurrency Control for more information on this technique.

If you activate a property version that specifies a hostname already active on another property, it is removed from that property, and a new property version is automatically created and activated with the change. Otherwise you do not receive any warning when saving a set of overlapping hostnames on an inactive version.

Set the validateHostnames query parameter to false to bypass a set of validation tests that may significantly slow this operation’s execution time. See Validation and Activation Time for guidance on when to defer validation. See JSON Problems for information on how validation data is embedded within the response object.

PUT /papi/v0/properties/{propertyId}/versions/{propertyVersion}/hostnames/{?contractId,groupId,validateHostnames}

Example: /papi/v0/properties/prp_175780/versions/1/hostnames/?contractId=ctr_1–1TJZH5&groupId=grp_15255&validateHostnames=true

Content-Type: application/json

Headers:

  • If-Match: "6aed418629b4e5c0"

Request:

[
    {
        "cnameType": "EDGE_HOSTNAME",
        "cnameFrom": "m.example.com",
        "cnameTo": "example.com.edgesuite.net"
    },
    {
        "cnameType": "EDGE_HOSTNAME",
        "edgeHostnameId": "ehn_895824",
        "cnameFrom": "example3.com"
    }
]

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15255 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_175780 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.
propertyVersion Integer 1 Property’s incremental version number.
Optional
validateHostnames Boolean true When false (the default), skips validation tests that would identify potential hostname-related problems within the response object’s errors and warnings arrays. See Property Hostname Errors for details on relevant error feedback. See Validation and Activation Time for details on the delays this might avoid.

Status 200 application/json

Headers:

  • ETag: "6aed418629b4e5c0"
  • X-Limit-Hosts-Per-Property-Limit: 100
  • X-Limit-Hosts-Per-Property-Remaining: 98

Response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_175780",
    "propertyVersion": 1,
    "etag": "6aed418629b4e5c0",
    "hostnames": {
        "items": [
            {
                "cnameType": "EDGE_HOSTNAME",
                "edgeHostnameId": "ehn_895822",
                "cnameFrom": "example.com",
                "cnameTo": "example.com.edgesuite.net"
            },
            {
                "cnameType": "EDGE_HOSTNAME",
                "edgeHostnameId": "ehn_895833",
                "cnameFrom": "m.example.com",
                "cnameTo": "m.example.com.edgesuite.net"
            }
        ]
    }
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. Optionally List Edge Hostnames and collect any relevant edgeHostnameId values to assign.

  4. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  5. List the property’s versions from /papi/v0/properties/{propertyId}/versions/{?contractId,groupId} and store the relevant version’s propertyVersion and etag.

  6. List the property’s hostnames and store the response’s hostnames.items array.

  7. Modify the contents of the array, optionally adding objects that represent new edge hostnames.

  8. Optionally set the validateHostnames query parameter to false if you don’t want to perform potentially slower validation tests on the set of hostnames. See Validation and Activation Time for guidance.

  9. PUT the array to /papi/v0/properties/{propertyId}/versions/{propertyVersion}/hostnames/{?contractId,groupId,validateHostnames}, passing in the etag as an If-Match header.

Get a rule tree

This gets the entire rule tree for a property version. See the Rule Trees section for details on the response object’s structure. Also use this operation to update from one rule format to another more recent version, incrementing the assigned set of features. See Update Rules to a Newer Set of Features below.

GET /papi/v0/properties/{propertyId}/versions/{propertyVersion}/rules/{?contractId,groupId}

Example: /papi/v0/properties/prp_173136/versions/3/rules/?contractId=ctr_1–1TJZH5&groupId=grp_15225

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_173136 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.
propertyVersion Integer 3 Property’s incremental version number.

Status 200 application/json

Headers:

  • Etag: "a9dfe78cf93090516bde891d009eaf57"
  • X-Limit-Clientip-Per-Property-Limit: 10
  • X-Limit-Clientip-Per-Property-Remaining: 10
  • X-Limit-Elements-Per-Property-Limit: 100
  • X-Limit-Elements-Per-Property-Remaining: 74
  • X-Limit-Max-Clientip-Per-Match-Limit: 300
  • X-Limit-Max-Clientip-Per-Match-Remaining: 300
  • X-Limit-Max-Nested-Rules-Limit: 5
  • X-Limit-Max-Nested-Rules-Remaining: 4

Response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_173136",
    "propertyVersion": 3,
    "etag": "a9dfe78cf93090516bde891d009eaf57",
    "ruleFormat": "v2015-08-08",
    "rules": {
        "name": "default",
        "options": { "is_secure": false },
        "criteria": [],
        "behaviors": [
            {
                "name": "origin",
                "options": {
                    "http_port": "80",
                    "tcip_enabled": "off",
                    "compression": "on",
                    "cachekeyhostname": "originhostname",
                    "forwardhostheader": "requesthostheader",
                    "hostname": "origin.test.com",
                    "type": "customer"
                }
            },
            {
                "name": "cpCode",
                "options": { "cpcodeId": 12345 }
            }
        ],
        "children": []
    }
}

This procedure simply gets a rule tree. To increment its rule format, see Update Rules to a Newer Set of Features below.

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  4. List the property’s versions from /papi/v0/properties/{propertyId}/versions/{?contractId,groupId} and store the relevant version’s propertyVersion.

  5. GET the rule tree from /papi/v0/properties/{propertyId}/versions/{propertyVersion}/rules/{?contractId,groupId}

Update rules to a newer set of features

This section describes a specific use for the Get a Rule Tree operation described above: to increment the versioned set of rule format features that are assigned to a rule tree. See also Freeze a Rule Tree’s Feature Set to assign a specific rule format.

Use this procedure to update from one rule format to another more recent version, incrementing the assigned set of features. This also modifies the rule tree to implement most required syntax changes, such as changes to option names and enum values. You can’t use this approach to assign an older rule format. In this procedure, the initial GET operation specifies a MIME type that converts the rule tree, after which you PUT the converted object to write it back.

  1. List Rule Formats and store the more recent rule format version string to which you want to update the rule tree.

  2. Build a custom MIME type string using this template, application/vnd.akamai.papirules.vYYYY-MM-DD+json, where vYYYY-MM-DD is the variable rule format version string.

  3. GET the rule tree as described above, adding an Accept header that specifies the custom MIME type.

  4. Confirm the response object’s top-level ruleFormat reflects the desired version.

  5. PUT the converted rule tree to the same URL you retrieved it from, adding a Content-Type header that specifies the same custom MIME type.

This represents the formal update path to increment versions of deployed features. Do not assign a rule format of latest, as that does not modify your rule tree to smoothly upgrade to any emerging changes to features. The latest rule format is instead likely to produce unexpected errors over time.

Updating to a more recent rule format modifies the rule tree to accommodate renamed options, renamed enumeration values, and two-state enums retyped as boolean. Other values may not be able to convert, such as string numerics retyped as actual numerics, or if an updated behavior features a new required option or different validation criteria. In these cases the PUT response’s rule tree object includes errors that help you refine the updated rule tree, as detailed in the Errors section.

Get a rule tree’s digest

This operation retrieves the rule tree’s Etag without the rule tree object. Ordinarily when you get a rule tree, the response includes a large rule tree object. As discussed in Concurrency Control, it includes a top-level etag data digest to use when writing back the data. Use this operation if you simply want to retrieve the Etag as a header without retrieving the data.

HEAD /papi/v0/properties/{propertyId}/versions/{propertyVersion}/rules/{?contractId,groupId}

Example: /papi/v0/properties/prp_173136/versions/3/rules/?contractId=ctr_1–1TJZH5&groupId=grp_15225&validateRules=true

Headers:

  • Accept: application/vnd.akamai.papirules.latest+json

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_173136 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.
propertyVersion Integer 3 Property’s incremental version number.

Status 204

Headers:

  • Etag: "a9dfe78cf93090516bde891d009eaf57"

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  4. List the property’s versions from /papi/v0/properties/{propertyId}/versions/{?contractId,groupId} and store the relevant version’s propertyVersion.

  5. Send a HEAD request to /papi/v0/properties/{propertyId}/versions/{propertyVersion}/rules/{?contractId,groupId}

  6. Store the value of the response’s Etag header and remove the surrounding double quote characters.

Update a rule tree

To write a rule tree to a property version, make a PUT request to the same resource as the GET request that reads it, passing in the rule object in the body of the request. See the Rule Trees section for details on the rule tree’s structure. Use this operation also to freeze a set of rules to a rule format version to ensure no change in a deployed activation’s behavior. Set the validateRules query parameter to false to bypass a set of validation tests that may significantly slow this operation’s execution time. See Validation and Activation Time for guidance on when to defer validation. See JSON Problems for information on how validation data is embedded within the response object.

PUT /papi/v0/properties/{propertyId}/versions/{propertyVersion}/rules/{?contractId,groupId,validateRules}

Example: /papi/v0/properties/prp_173136/versions/3/rules/?contractId=ctr_1–1TJZH5&groupId=grp_15225&validateRules=true

Content-Type: application/vnd.akamai.papirules.latest+json

Headers:

  • If-Match: "a9dfe78cf93090516bde891d009eaf57"

Request:

{
    "rules": {
        "name": "default",
        "children": [
            {
                "name": "Handle /my-path",
                "criteriaMustSatisfy": "all",
                "criteria": [
                    {
                        "name": "path",
                        "value": [ "/my-path" ]
                    }
                ],
                "behaviors": [
                    {
                        "name": "caching",
                        "behavior": "max-age",
                        "ttl": "1m"
                    }
                ]
            }
        ]
    }
}

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_173136 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.
propertyVersion Integer 3 Property’s incremental version number.
Optional
validateRules Boolean true Set to true by default. When false, skips validation tests that would identify potential problems within the response object’s errors and warnings arrays. See the Debug section for details on this error feedback. See Validation and Activation Time for details on the delays this might avoid.

Status 200 application/vnd.akamai.papirules.latest+json

Headers:

  • Etag: "418c2c1986051606324fbb316131e0bf"
  • X-Limit-Clientip-Per-Property-Limit: 10
  • X-Limit-Clientip-Per-Property-Remaining: 10
  • X-Limit-Elements-Per-Property-Limit: 100
  • X-Limit-Elements-Per-Property-Remaining: 74
  • X-Limit-Max-Clientip-Per-Match-Limit: 300
  • X-Limit-Max-Clientip-Per-Match-Remaining: 300
  • X-Limit-Max-Nested-Rules-Limit: 5
  • X-Limit-Max-Nested-Rules-Remaining: 4

Response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_173136",
    "propertyVersion": 3,
    "etag": "a9dfe78cf93090516bde891d009eaf57",
    "errors": [
        {
            "type": "/papi/v0/errors/validation.required_behavior",
            "title": "Missing required behavior in default rule",
            "detail": "In order for this property to work correctly behavior Content Provider Code needs to be present in the default section",
            "instance": "/papi/v0/properties/prp_173136/versions/3/rules#err_100",
            "behaviorName": "cpCode"
        },
        {
            "type": "/papi/v0/errors/validation.required_behavior",
            "title": "Missing required behavior in default rule",
            "detail": "In order for this property to work correctly behavior Origin needs to be present in the default section",
            "instance": "/papi/v0/properties/prp_173136/versions/3/rules#err_101",
            "behaviorName": "origin"
        }
    ],
    "rules": {
        "name": "default",
        "children": [
            {
                "name": "Handle /my-path",
                "criteriaMustSatisfy": "all",
                "criteria": [
                    {
                        "name": "path",
                        "value": [ "/my-path" ]
                    }
                ],
                "behaviors": [
                    {
                        "name": "caching",
                        "behavior": "max-age",
                        "ttl": "1m"
                    }
                ]
            }
        ]
    }
}

This procedure simply modifies a rule tree. To assign a fixed rule format version to a rule tree, see Freeze a Rule Tree’s Feature Set below.

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  4. List the property’s versions from /papi/v0/properties/{propertyId}/versions/{?contractId,groupId} and store the relevant version’s propertyVersion.

  5. Optionally get the existing rule tree object.

  6. Modify the rule tree.

  7. Optionally set the validateRules query parameter to false if you don’t want to perform potentially long-running validation tests on the rule tree. See Validation and Activation Time for guidance.

  8. PUT the object to /papi/v0/properties/{propertyId}/versions/{propertyVersion}/rules/{?contractId,groupId,validateRules}.

Freeze a rule tree’s feature set

This section describes a specific use for the Update a Rule Tree operation described above: to assign a specific rule format’s feature set to a rule tree. See also Freeze a Rule Tree’s Feature Set to increment the versioned set of rule format features that are assigned to a rule tree.

Rule trees are best deployed by assigning them a rule format that specifies a fixed, frozen set of features that are guaranteed not to change unexpectedly over time and cause errors. New properties’ rule trees are assigned whatever rule format you specify as a default client setting, or else the most recent dated rule format version available. To confirm your rule tree is already frozen, and freeze it if necessary:

  1. GET the rule tree and store the URL you use to retrieve it.

  2. If the rule tree’s top-level ruleFormat member is a dated version, the rule tree is already frozen. Continue to freeze it only if it is latest.

  3. List available rule formats and store the most recent dated rule format version string.

  4. Build a custom MIME type string using this template, application/vnd.akamai.papirules.vYYYY-MM-DD+json, where vYYYY-MM-DD is the variable rule format version string.

  5. PUT the rule tree object to the same URL you used to retrieve it, adding the custom MIME type to the request as a Content-Type header.

See also Get a Rule Tree for steps to update a rule tree to a more recent rule format. If the set of features you include in your rule tree does not conform to the associated rule format schema, the response includes errors that may prevent you from activating the property.

Search properties

This operation searches properties by name, or by the hostname or edge hostname for which it is currently active. Specify a request object with a single propertyName, hostname, or edgeHostname value. The response lists the matching set of currently active property versions. Each of the response’s Version objects features additional context for the property in which it appears, or the account, contract, or group under which the property was provisioned.

POST /papi/v0/search/find-by-value

Content-Type: application/json

Request:

{
    "edgeHostname": "my-hostname-1.example.com.edgesuite.net"
}

Status 200 application/json

Response:

{
    "versions": {
        "items": [
            {
                "accountId": "act_1-1TJZFB",
                "contractId": "ctr_1-1TJZH5",
                "groupId": "grp_15225",
                "propertyId": "prp_173136",
                "propertyName": "981.catalog.amenai.net",
                "propertyVersion": 2,
                "updatedByUser": "amenai",
                "updatedDate": "2014-05-10T19:06:13Z",
                "productionStatus": "INACTIVE",
                "stagingStatus": "ACTIVE",
                "note": "updated caching",
                "hostname": "non-null-hostname-for-hostname-searches",
                "edgeHostname": "non-null-edge-hostname-for-hostname-searches"
            },
            {
                "accountId": "act_1-1TJZFB",
                "contractId": "ctr_1-1TJXYZ",
                "groupId": "grp_15226",
                "propertyId": "prp_173137",
                "propertyName": "a-different-property.net",
                "propertyVersion": 1,
                "updatedByUser": "afaden",
                "updatedDate": "2013-05-04T21:12:57Z",
                "productionStatus": "ACTIVE",
                "stagingStatus": "INACTIVE",
                "note": "initial version",
                "hostname": "non-null-hostname-for-hostname-searches",
                "edgeHostname": "non-null-edge-hostname-for-hostname-searches"
            }
        ]
    }
}

List activations

This lists all activations for all versions of a property, on both production and staging networks.

GET /papi/v0/properties/{propertyId}/activations/{?contractId,groupId}

Example: /papi/v0/properties/prp_173136/activations/?contractId=ctr_1–1TJZH5&groupId=grp_15225

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_173136 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.

Status 200 application/json

Headers:

  • X-RateLimit-Activations-Limit: 10
  • X-RateLimit-Activations-Remaining: 9
  • X-RateLimit-Activations-Reset: 139603655200

Response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "activations": {
        "items": [
            {
                "activationId": "atv_1696985",
                "propertyName": "example.com",
                "propertyId": "prp_173136",
                "propertyVersion": 1,
                "network": "STAGING",
                "activationType": "ACTIVATE",
                "status": "ACTIVE",
                "submitDate": "2014-03-05T02:22:12Z",
                "updateDate": "2014-03-04T21:12:57Z",
                "note": "Sample activation",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ]
            },
            {
                "activationId": "atv_1696986",
                "propertyName": "example.com",
                "propertyId": "prp_173136",
                "propertyVersion": 1,
                "network": "PRODUCTION",
                "activationType": "ACTIVATE",
                "status": "ACTIVE",
                "submitDate": "2014-03-02T02:22:12Z",
                "updateDate": "2014-03-01T21:12:57Z",
                "note": "Sample activation",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ]
            }
        ]
    }
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  4. GET a list of the property’s activations from /papi/v0/properties/{propertyId}/activations/{?contractId,groupId}.

  5. Activation objects are available in the response’s activations.items array.

Activate a property

This operation creates a new property activation, which deactivates any current activation. After a necessary delay, this activates your property version’s rule tree and set of hostnames across Akamai’s network of edge servers, modifying how your edge content responds to end-user requests.

If the activation request produces warnings, a 400 response indicates this problem message: {"type": "/papi/v0/activation-warnings-not-acknowledged"}. Subsequent requests succeed if you list the messageId values in the request’s acknowledgeWarnings array. Once an activation is successful, it responds with a 201 code and provides a Location header and activationLink in the response object indicating where to poll the status of the activation.

NOTE: If you set activationType to DEACTIVATE in the POST request object, the property would deactivate and no longer serve any traffic. You would need to modify (de-Akamaize) your DNS configuration and specify a different way to handle the traffic. See Enable Traffic for a New Edge Hostname for more information.

POST /papi/v0/properties/{propertyId}/activations/{?contractId,groupId}

Example: /papi/v0/properties/prp_173136/activations/?contractId=ctr_1–1TJZH5&groupId=grp_15225

Content-Type: application/json

Request:

{
    "propertyVersion": 1,
    "network": "STAGING",
    "note": "Sample activation",
    "notifyEmails": [
        "you@example.com",
        "them@example.com"
    ],
    "acknowledgeWarnings": [
        "msg_baa4560881774a45b5fd25f5b1eab021d7c40b4f"
    ]
}

Parameter Type Sample Description
Required
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_173136 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.

Status 201 application/json

Headers:

  • Location: /papi/v0/properties/prp_173136/activations/atv_67037?contractId=ctr_1-1TJZFB&groupId=grp_15225
  • X-RateLimit-Activations-Limit: 10
  • X-RateLimit-Activations-Remaining: 9
  • X-RateLimit-Activations-Reset: 139603655200

Response:

{
    "activationLink": "/papi/v0/properties/prp_173136/activations/atv_67037?contractId=ctr_1-1TJZFB&groupId=grp_15225"
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  4. Either get the property’s latestVersion or list all versions and store the relevant version’s propertyVersion.

  5. Build an Activation POST object.

  6. POST the object to /papi/v0/properties/{propertyId}/activations/{?contractId,groupId}.

  7. Optionally poll the new activation to check its deployment status.

Get an activation

Gets details about an activation. You typically get a single activation from an activationLink when launching a new activation and following up to poll its status. For activations whose status is PENDING, a Retry-After header provides an estimate for when it’s likely to change.

GET /papi/v0/properties/{propertyId}/activations/{activationId}{?contractId,groupId}

Example: /papi/v0/properties/prp_173136/activations/atv_1696855?contractId=ctr_1–1TJZH5&groupId=grp_15225

Parameter Type Sample Description
Required
activationId String atv_1696855 Unique identifier for the activation.
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_173136 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.

Status 200 application/json

Headers:

  • Retry-After: 600

Response:

{
    "activations": {
        "items": [
            {
                "activationId": "atv_1696985",
                "propertyName": "example.com",
                "propertyId": "prp_173136",
                "propertyVersion": 1,
                "network": "STAGING",
                "activationType": "ACTIVATE",
                "status": "PENDING",
                "submitDate": "2014-03-02T02:22:12Z",
                "updateDate": "2014-03-01T21:12:57Z",
                "note": "Sample activation",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ],
                "accountId": "act_1-1TJZFB",
                "groupId": "grp_15225"
            }
        ]
    }
}

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.

  2. List Groups from /papi/v0/groups and store the relevant groupId.

  3. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId.

  4. List Activations for the property and store the relevant activationId.

  5. GET the activation from /papi/v0/properties/{propertyId}/activations/{activationId}{?contractId,groupId}.

  6. The Activation object is available in the response’s single-item activations.items array.

Cancel a pending activation

If you detect a problem with a property version while its activation is still PENDING, this operation allows you to cancel it. Make a DELETE request on the response’s activationLink from running Activate a Property. Once you DELETE the activation, it no longer appears in the list of activations, but you can still access it individually.

A successful cancellation results in a 200 response and an ABORTED status. If the activation is no longer PENDING, a 422 (unprocessable) error indicates that it can no longer be canceled. Canceling an activation that has already been canceled results in a 204 response, indicating there’s no resource to delete. Canceling an unknown activation results in a 404 error.

You can only abort an activation while it’s queued for deployment across the various network zones with PENDING status. Once the window has closed and it’s been dispatched across the network, you can either reactivate an older version, or create a new version that fixes the problem and activate that instead.

DELETE /papi/v0/properties/{propertyId}/activations/{activationId}{?contractId,groupId}

Example: /papi/v0/properties/prp_173136/activations/atv_1696855?contractId=ctr_1–1TJZH5&groupId=grp_15225

Parameter Type Sample Description
Required
activationId String atv_1696855 Unique identifier for the activation.
contractId String ctr_1-1TJZH5 Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs.
groupId String grp_15225 Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs.
propertyId String prp_173136 Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs.

Status 200 application/json

Response:

{
    "activations": {
        "items": [
            {
                "activationId": "atv_1696985",
                "propertyName": "example.com",
                "propertyId": "prp_173136",
                "propertyVersion": 1,
                "network": "STAGING",
                "activationType": "ACTIVATE",
                "status": "ABORTED",
                "submitDate": "2014-03-02T02:22:12Z",
                "updateDate": "2014-03-01T21:12:57Z",
                "note": "Sample activation cancellation",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ],
                "accountId": "act_1-1TJZFB",
                "groupId": "grp_15225"
            }
        ]
    }
}

List rule formats

Gets a list of available rule formats. These dated version strings available in the response’s ruleFormats.items array allow you to control the set of behaviors and criteria you invoke within a property’s rules to apply to edge content, either freezing a rule tree or updating to a new rule format. To validate a rule tree to the requirements of a specific rule format, see Get a Rule Format’s JSON Schema.

GET /papi/v0/rule-formats

Status 200 application/json

Response:

{
    "ruleFormats": {
        "items": [
            "latest",
            "v2015-08-08"
        ]
    }
}

Get a request’s schema

Fetch the JSON schema for a particular request. These are typically linked from error messages about schema mismatches.

GET /papi/v0/schemas/request/{filename}

Example: /papi/v0/schemas/request/EdgeHostnamesPostRequestV0.json

Parameter Type Sample Description
Required
filename String EdgeHostnamesPostRequestV0.json Schema’s filename.

Status 200 application/json

Response:

{
    "type": "object"
}

Get a rule format’s schema

Get the JSON schema for the given product and rule format, which you can use to validate a rule tree object.

NOTE: Your rule tree may still fail to activate if you specify features that are optional within the schema for a product but not currently supported on your contract. To validate the set of currently available features you want to activate, run List Available Behaviors and List Available Criteria.

GET /papi/v0/schemas/products/{productId}/{ruleFormat}

Example: /papi/v0/schemas/products/prd_Site_Accel/latest

Parameter Type Sample Description
Required
productId String prd_Site_Accel Unique identifier for the product. Remove the prd_ prefix if using the value in other Akamai APIs.
ruleFormat String latest Name of the rule format, either one frozen to a specific date, or representing the latest set of behaviors and criteria.

Status 200 application/json

Response:

{
    "type": "object",
    "properties": {
        "rules": { "type": "object" }
    },
    "required": [ "rules" ]
}

  1. List Products from /papi/v0/products{?contractId} and store the relevant productId.

  2. List Rule Formats and store the relevant ruleFormat string.

  3. GET the rule format schema from /papi/v0/schemas/products/{productId}/{ruleFormat}.

Get client settings

Get the current set of default values that apply to API clients keyed by the current authorization token. This operation currently has one use: to access the dated rule format version for a set of features assigned by default to new properties’ rule trees.

GET /papi/v0/client-settings

Status 200 application/json

Response:

{
    "ruleFormat": "v2015-08-08"
}

Update client settings

Update the current set of default values that apply to API clients keyed by the current authorization token. This operation currently has one use: to update the dated rule format version for a set of features assigned by default to new properties’ rule trees.

PUT /papi/v0/client-settings

Content-Type: application/json

Request:

{
    "ruleFormat": "v2015-08-08"
}

Status 200 application/json

Response:

{
    "ruleFormat": "v2015-08-08"
}

This sets a new default rule format:

  1. List Rule Formats and select the appropriate version.

  2. Build a ClientSettings object, or modify a GET response with the new ruleFormat value.

  3. PUT the object to /papi/v0/client-settings.

Get build details

Gets information about the current API release. Note that available information about version numbers and build dates are unrelated to the overall API version or to various rule format versions. See API Versioning for details.

GET /papi/v0/build

Status 200 application/json

Response:

{
    "catalogGitInfo": {
        "buildDate": "2014-05-26T23:56:21Z",
        "commitDate": "2014-05-26T23:55:53Z",
        "branch": "candidate-14.2",
        "commitId": "59a193acdf26ba6de1522486411a749f19efde8c"
    },
    "coreGitInfo": {
        "buildDate": "2014-04-25T17:02:43Z",
        "commitDate": "2014-04-25T17:01:11Z",
        "branch": "14.2",
        "commitId": "22163903cb91a62492dfce745aaa95de991b0653"
    },
    "currentCatalogVersion": "14.2.6",
    "coreVersion": "14.2"
}

Data

This section describes Property Manager API’s various data structures.

Most of the API’s JSON objects are structured as wrappers whose high-level members provide overall context for the request. The following contextual members may appear within this top-level object:

Member Type Description
accountId String A unique identifier for the prevailing account.
accountName String A descriptive name for the account.
contractId String A unique identifier for the prevailing contract.
etag String A digest with which to check the data’s integrity.
groupId String A unique identifier for the prevailing group.
propertyId String A unique identifier for the property.
propertyName String A descriptive name for the property.
propertyVersion Number Identifies a property instance.
ruleFormat String A read-only value that indicates the versioned set of features and criteria that are currently applied to a rule tree.

As described in the Data Conventions section, relevant data for most resources is available within a nested items array, even if the request yields a single record. When writing to the API, you often POST these smaller objects rather than perform a PUT on the entire data structure. For example, a GET may yield this hypothetical data structure:

{
    "contextualMember": true,
    "nouns": {
        "items": [
            { "nounName": "resource" }
        ]
    }
}

To write new data, you would POST only the inner object to the same endpoint:

{ "nounName": "endpoint" }

See the Resources section for samples of JSON data.

Group

Encapsulates information about the group that contains a property and allows it to be deployed. See the List Groups operation for a detailed interaction.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "accountName": "Example.com",
    "groups": {
        "items": [
            {
                "groupName": "Example.com-1-1TJZH5",
                "groupId": "grp_15225",
                "contractIds": [
                    "ctr_1-1TJZH5"
                ]
            },
            {
                "groupName": "Test",
                "groupId": "grp_15231",
                "parentGroupId": "grp_15225",
                "contractIds": [
                    "ctr_1-1TJZH5"
                ]
            }
        ]
    }
}

Group members

The top-level JSON object features the following outer contextual members:

  • accountId
  • accountName

The groups member is an object whose nested items array lists each group. These objects contain the following members:

Member Type Required Description
contractIds Array A set of string identifiers for contracts whose products can be applied to properties within a group.
groupId String A unique identifier for the group.
groupName String A descriptive label for the group.
parentGroupId String Identifies another group as a parent, defining the relative location of the group within the group hierarchy. If omitted, it is the root-level group at the top of the hierarchy.

Contract

Encapsulates information about the contract under which a property may be deployed. See the List Contracts operation for a detailed interaction.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contracts": {
        "items": [
            {
                "contractId": "ctr_1-1TJZH5",
                "contractTypeName": "Direct Customer"
            }
        ]
    }
}

Contract members

The top-level JSON object features the following outer contextual member:

  • accountId

The contracts member is an object whose nested items array lists each contract. These objects contain the following members:

Member Type Required Description
contractId String A unique identifier for the contract.
contractTypeName Enumeration Distinguishes the type of contract, either Direct Customer or Indirect Customer.

Product

Encapsulates information on the product that determines a property’s available range of features. See the List Products operation for a detailed interaction.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "products": {
        "items": [
            {
                "productName": "Alta",
                "productId": "prd_Alta"
            }
        ]
    }
}

Product members

The top-level JSON object features the following outer contextual members:

  • accountId
  • contractId

The products member is an object whose nested items array lists each product. These objects contain the following members:

Member Type Description
productId String A unique identifier for the product.
productName String A descriptive name for the product.

CpCode

Specifies billing and reporting codes. See the CP Codes interface for detailed interactions.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZFW",
    "groupId": "grp_15225",
    "cpcodes": {
        "items": [
            {
                "cpcodeId": "cpc_33190",
                "cpcodeName": "SME WAA",
                "productIds": ["prd_Web_App_Accel"],
                "createdDate": "2015-03-02T15:06:13Z"
            }
        ]
    }
}

Sample POST request:

{
        "productId"  : "prd_Obj_Caching",
        "cpcodeName" : "g2o"
}

CpCode members

The top-level JSON object features the following outer contextual members:

  • accountId
  • contractId
  • groupId

The cpcodes member is an object whose nested items array lists each CP code. These objects contain the following members:

Member Type Required Description
cpcodeId String A unique identifier for the CP code.
cpcodeName String A descriptive label for the CP code.
createdDate String A time stamp for the CP code.
productId String On POST, the product to assign to this CP code.
productIds Array On GET, lists identifiers for products assigned to this CP code. (Note that PAPI does not support Property Manager’s ability to assign more than one product to a CP code.)

To make a POST request that creates a new CP code, specify a single cpcode object with the required productId and cpcodeName members.

EdgeHostname

Specifies a set of available hostnames to which a property version may be applied. See the Edge Hostnames interface for detailed interactions.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "edgeHostnames": {
        "items": [
            {
                "edgeHostnameId": "ehn_895822",
                "edgeHostnameDomain": "example.com.edgekey.net",
                "productId": "prd_Alta",
                "domainPrefix": "example.com",
                "domainSuffix": "edgekey.net",
                "status": "PENDING",
                "secure": true,
                "ipVersionBehavior": "IPV4"
            },
            {
                "edgeHostnameId": "ehn_887436",
                "edgeHostnameDomain": "example.com.edgesuite.net",
                "productId": "prd_Alta",
                "status": "ACTIVE",
                "domainPrefix": "www.mysales.co",
                "domainSuffix": "edgesuite.net",
                "secure": false,
                "ipVersionBehavior": "IPV4"
            }
        ]
    }
}

Sample POST Request:

{
    "productId": "prd_Alta",
    "domainPrefix": "custom.example.com",
    "domainSuffix": "edgesuite.net",
    "secure": false,
    "ipVersionBehavior": "IPV4"
}

EdgeHostname members

The top-level JSON object features the following outer contextual members:

  • accountId
  • contractId
  • groupId

The edgeHostnames member is an object whose nested items array lists each edge hostname. These objects contain the following members:

Member Type Required Description
domainPrefix String The origin domain portion of the edge hostname. An edge hostname consists of a customer-specific namePrefix such as www.example.com and an Akamai-specific domainSuffix such as edgesuite.net. The edge hostname’s final DNS CNAME combines the two, for example, www.example.com.edgesuite.net.
domainSuffix String The Akamai-specific portion of the edge hostname, for example, edgesuite.net.
edgeHostnameDomain String The full edge domain name formed from the domainPrefix and domainSuffix.
edgeHostnameId String The edge hostname’s unique identifier, which can be assigned to a property.
ipVersionBehavior Enumeration Which version of the IP protocol to use: IPV4 for version 4 only, or IPV6_COMPLIANCE for both 4 and 6. The default value for requests is IPV4.
productId String The product associated with the edge hostname.
secure Boolean Set to true if the edge hostname is to be used with SSL. The default value for POST requests is false. (Setting secure:true for new edge hostnames is not supported.)
status Enumeration Either active for fully deployed, or pending for a newly defined hostname whose DNS mapping has not yet been distributed across the entire Akamai network. (Not to be confused with a property activation’s deployment status.)

To POST a new edge hostname, specify a single object containing productId, domainPrefix, and domainSuffix members, and optional ipVersionBehavior and secure members.

Property

Contains configuration data to apply to edge content. See the Properties interface for detailed interactions.

Sample GET response:

{
    "properties": {
        "items": [
            {
                "accountId": "act_1-1TJZFB",
                "contractId": "ctr_1-1TJZH5",
                "groupId": "grp_15225",
                "propertyId": "prp_175780",
                "propertyName": "example.com",
                "latestVersion": 2,
                "stagingVersion": 1,
                "productionVersion": null,
                "note": "Notes about example.com"
            }
        ]
    }
}

Sample POST request used to optionally clone an existing property:

{
    "productId"    : "prd_Obj_Caching",
    "propertyName" : "new.example.com"
    "cloneFrom": {
        "propertyId"    : "prp_175780",
        "version"       : 2,
        "copyHostnames" : true,
        "cloneFromVersionEtag" : "a9dfe78cf93090516bde891d009eaf57"
    }
}

Property members

The properties member within the top-level JSON is an object whose nested items array lists each property. These objects contain the following members:

Member Type Required Description
accountId String Identifies the account under which the property was created.
cloneFrom Property.cloneFrom Optionally identifies another property instance to clone when making a POST request to create a new property. The cloned property must share the same contract and group.
contractId String Identifies the contract under which the property was created.
groupId String Identifies the group to which the property is assigned.
latestVersion Number Specifies the most recent version of the property.
note String Further descriptive commentary.
productId String The product assigned to the property, required when POSTing a new property.
productionVersion Number The most recent version to be activated to the production network, otherwise null.
propertyId String The property’s unique identifier.
propertyName String A descriptive name for the property.
stagingVersion Number The most recent version to be activated to the test network, otherwise null.
Property.cloneFrom: To POST a new property, specify an object with the required productId and propertyName members. The optional cloneFrom member specifies an object with the following members:
cloneFromVersionEtag String Performs an etag data integrity check on the original property.
copyHostnames Boolean Assigns the same set of hostnames to the new property, false by default.
propertyId String Specifies the property to clone.
version Number Specifies the version of the property to clone.

Version

Specifies the version of a property. See the Property Versions interface for detailed interactions.

Sample GET response:

{
    "propertyId": "prp_173136",
    "propertyName": "981.calatog.amenai.net",
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "versions": {
        "items": [
            {
                "propertyVersion": 1,
                "updatedByUser": "afaden",
                "updatedDate": "2014-03-04T21:12:57Z",
                "productionStatus": "ACTIVE",
                "stagingStatus": "INACTIVE",
                "etag": "71573b922a87abc3",
                "productId": "prd_Alta",
                "ruleFormat": "latest",
                "note": "initial version"
            }
        ]
    }
}

Sample POST request:

{
    "createFromVersion": 2,
    "createFromVersionEtag": "5891b5b522d5df08"
}

Version members

The top-level JSON object features the following outer contextual members:

  • accountId
  • contractId
  • groupId
  • propertyId
  • propertyName
  • ruleFormat

The versions member is an object whose nested items array lists each version. These objects contain the following members:

Member Type Required Description
note String A descriptive log comment.
productId String The product assigned to the property when versioned.
productionStatus Enumeration Whether the version has been activated to the production network. (If ACTIVE, the version is read-only. Otherwise it may be INACTIVE or PENDING.)
propertyVersion Number A positive integer identifying the incremental version.
stagingStatus Enumeration Whether the version has been activated to the test network. (If ACTIVE, the version is read-only. Otherwise it may be INACTIVE or PENDING.)
updatedByUser String The username associated with the new version.
updatedDate String The date stamp of the version’s latest update.
etag String A digest with which to check the data’s integrity.
Only appears in search results
accountId String Identifies the account under which the property version is active.
contractId String Identifies the contract under which the property version is active.
edgeHostname String When searching for hostname or edgeHostname, this shows the edge hostname to which the active version currently applies.
groupId String Identifies the group under which the property version is active.
hostname String When searching for hostname or edgeHostname, this shows the property hostname to which the active version currently applies.
propertyId String Identifies the property to which the listed version belongs.
propertyName String The name of the property to which the listed version belongs.

Version POST members

When incrementing a new version, POST an object with the following members:

Member Type Required Description
createFromVersion Number The property version on which to base the new version.
createFromVersionEtag String The data digest of the version on which to base the new version.

Hostname

Specifies an edge hostname that is applied to a property version. See the Property Version Hostnames interface for detailed interactions.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_175780",
    "propertyVersion": 1,
    "etag": "6aed418629b4e5c0",
    "hostnames": {
        "items": [
            {
                "cnameType": "EDGE_HOSTNAME",
                "edgeHostnameId": "ehn_895822",
                "cnameFrom": "example.com",
                "cnameTo": "example.com.edgesuite.net"
            },
            {
                "cnameType": "EDGE_HOSTNAME",
                "edgeHostnameId": "ehn_895833",
                "cnameFrom": "m.example.com",
                "cnameTo": "m.example.com.edgesuite.net"
            }
        ]
    }
}

Hostname members

The top-level JSON object features the following outer contextual members:

  • accountId
  • contractId
  • groupId
  • propertyId
  • propertyVersion
  • etag

The hostnames member is an object whose nested items array lists each hostname. These objects contain the following members:

Member Type Required Description
cnameFrom String The original origin’s hostname.
cnameTo String The hostname for edge content, corresponding to the edge hostname object’s edgeHostnameDomain member.
cnameType Enumeration Only one supported EDGE_HOSTNAME value.
edgeHostnameId String A unique identifier for the edge hostname.

Writing data to this resource requires that you PUT an array of all the hostname objects, each containing edgeHostnameId, cnameFrom, and cnameTo members.

Rule

Specifies the executable logic to apply to cached edge content. See the Property Version Rules interface for detailed interactions, and the Rule Trees section for guidance on how to structure the data.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_173136",
    "propertyVersion": 3,
    "etag": "a9dfe78cf93090516bde891d009eaf57",
    "ruleFormat": "v2015-08-08",
    "rules": {
        "name": "default",
        "options": {
            "is_secure": false
        },
        "criteria": [],
        "behaviors": [
            {
                "name": "origin",
                "options": {
                    "originType": "CUSTOMER",
                    "hostname": "origin.test.com",
                    "httpPort": 80,
                    "enableTrueClientIp": false,
                    "cacheKeyHostname": "ORIGIN_HOSTNAME",
                    "forwardHostHeader": "REQUEST_HOST_HEADER",
                    "compress": true
                }
            },
            {
                "name": "cpCode",
                "options": {
                    "value": {
                        "id": 12345,
                        "name": "main site"
                    }
                }

            }
        ],
        "children": []
    }
}

Rule members

The top-level JSON object features the following outer contextual members:

  • accountId
  • contractId
  • etag
  • groupId
  • propertyId
  • propertyVersion
  • ruleFormat

The rules member defines the default rule object. A rule may apply behaviors based on an initial criteria test, and may also execute other nested rules, which are available as children. The entire data structure is called the rule tree. Each rule object contains the following members:

Member Type Required Description
behaviors Array A series of behavior objects. Optional on nested rules.
children Array A series of nested rule objects, which execute after the current rule’s criteria and behaviors.
comment String A descriptive comment to help you track the rule’s function.
criteriaLocked Boolean Within child rules, this prohibits any modifications to criteria objects. This value is read-only. Contact your Akamai representative to change it.
criteria Array A series of criteria objects.
name String A description of the rule. The top-level rule must be named default.
options Rule.option Flags that apply to the top-level rule object.
Rule.options
is_secure Boolean When enabled, serves the property’s content over SSL. Doing so may enable additional rule behaviors.

Activation

Activates property versions on a specific network. See the Property Activations interface for detailed interactions.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "activations": {
        "items": [
            {
                "activationId": "atv_1696985",
                "propertyName": "example.com",
                "propertyId": "prp_173136",
                "propertyVersion": 1,
                "network": "STAGING",
                "activationType": "ACTIVATE",
                "status": "ACTIVE",
                "submitDate": "2014-03-05T02:22:12Z",
                "updateDate": "2014-03-04T21:12:57Z",
                "note": "Sample activation",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ]
            },
            {
                "activationId": "atv_1696986",
                "propertyName": "example.com",
                "propertyId": "prp_173136",
                "propertyVersion": 1,
                "network": "PRODUCTION",
                "activationType": "ACTIVATE",
                "status": "ACTIVE",
                "submitDate": "2014-03-02T02:22:12Z",
                "updateDate": "2014-03-01T21:12:57Z",
                "note": "Sample activation",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ]
            }
        ]
    }
}

Sample POST request:

{
    "propertyVersion": 3,
    "network": "STAGING",
    "note": "test of custom.example.com",
    "notifyEmails": [
        "you@example.com",
        "them@example.com"
    ]
}

Activation members

The top-level JSON object features the following outer contextual members:

  • accountId
  • contractId
  • groupId

The activations member is an object whose nested items array lists each activation. These objects contain the following members:

Member Type Required Description
propertyVersion Number The property version targeted with activation. Once activated, you can no longer modify that version of the property.
network Enumeration The network to activate on, either STAGING or PRODUCTION.
notifyEmails Array A list of email address strings to notify when the activation status changes.
acknowledgeWarnings Array A list of msg_-prefixed strings acknowledging any warnings noted when modifying rules, or in responses to previous activation requests.
acknowledgeAllWarnings Boolean Whether you need to acknowledge each warning as an acknowledgeWarnings array.
activationId String The activation’s unique identifier.
activationType Enumeration Either ACTIVATE or DEACTIVATE. The default is ACTIVATE. Any new activation automatically deactivates the current activation. Note that if you were to POST a DEACTIVATE type on an active property, it would no longer serve any traffic. You would need to modify (de-Akamaize) your DNS configuration and specify a different way to field the traffic.
fastPush Boolean Enable a fast meta-data push when activating a new property, true by default.
ignoreHttpErrors Boolean Ignore any HTTP errors when pushing fast meta-data activation, true by default.
note String Assigns a log message to the activation request.
propertyId String Identifies property targeted with activation.
propertyName String The name of the property targeted with activation.
status Enumeration Either ACTIVE, INACTIVE, PENDING, ZONE_1, ZONE_2, ZONE_3, ABORTED, FAILED, DEACTIVATED, PENDING_DEACTIVATION, or NEW.
submitDate String A date stamp marking when the activation initiated.
updateDate String A date stamp marking when the status last changed.

RuleFormat

Lists available rule format versions. See List Rule Formats for a sample response.

The top-level ruleFormats member is an object whose nested items array lists each available rule format version string.

Schema

PAPI generates JSON schemas for various resources’ expected data format. For details on schemas you use to structure a rule tree, see Understanding Rule Formats, and the Get a Rule Format’s Schema operation for a sample request.

ClientSettings

Specifies default settings for an API client. See the Client Settings interface for a detailed interactions.

Sample GET response:

{
    "ruleFormat": "v2015-08-08"
}

ClientSettings members

The JSON object contains the following member:

Member Type Required Description
ruleFormat String A string key indicating the dated version of the API’s set of features specified by a rule format schema.

Build

Provides details on the software build. See the Build interface for details.

Sample GET response:

{
    "catalogGitInfo": {
        "buildDate": "2014-05-26T23:56:21Z",
        "commitDate": "2014-05-26T23:55:53Z",
        "branch": "candidate-14.2",
        "commitId": "59a193acdf26ba6de1522486411a749f19efde8c"
    },
    "coreGitInfo": {
        "buildDate": "2014-04-25T17:02:43Z",
        "commitDate": "2014-04-25T17:01:11Z",
        "branch": "14.2",
        "commitId": "22163903cb91a62492dfce745aaa95de991b0653"
    },
    "currentCatalogVersion": "14.2.6",
    "coreVersion": "14.2"
}

Build members

The JSON object contains the following members:

Member Type Required Description
coreVersion String The Property Manager version.
currentCatalogVersion String The version of the Property Manager catalog that specifies rule behaviors and criteria. Note that this catalog is not the same as the rule format version available in the Rule Format Versions interface.
catalogGitInfo Object Specifies internal tracking data listed below.
coreGitInfo Object Specifies internal tracking data listed below.
Build.*GitInfo
branch String The name of the build’s branch.
buildDate String When the code was built.
commitDate String When the final commit occurred.
commitId String An opaque data signature for the final commit.

Rule trees

A property’s main functionality is encapsulated in its set of rules. This section details how rules operate, and how to structure a rule tree from the root down. It shows how to inject variables within rules and modify their value at runtime. It also shows how to interpret contextual rule format JSON schemas that specify your product’s level of support for various behaviors and criteria.

The default rule

The JSON object for the API’s Rules interface features a top-level rules element that specifies a default rule object. As discussed in the Errors section, responses may also include top-level warnings, errors, and other contextual members, hence the additional layer of data. (The examples that follow remove extraneous data members.)

{
    "rules": {
        "name": "default",
        "options": {
            "is_secure": false
        }
    }
}

The rule’s default name is more than simply a default; the top-level rule must be named that way.

The only nominally mandatory member when saving a rule is its name, so you don’t have to pass in the options object, which as shown above displays default behavior. The Create a New Edge Hostname operation shows to specify hostnames as secure. When the property’s is_secure is set to true, it means you want to apply a shared certificate for all hostnames, possibly supplementing hostname-specific certificates. With is_secure enabled within the rule tree, you may receive warnings about any non-secure hostnames to which the rule applies. Note that some rule behaviors may only be available when is_secure is true.

Behaviors

The default rule must feature a set of behaviors, which is represented as an array of objects. New properties come with different sets of default rules depending on the product, but this much simpler example features the two behaviors that are always necessary to activate your property. The origin behavior determines how the edge network interacts with your origin servers, and the cpCode behavior is required for billing and reporting on traffic.

{
    "rules": {
        "name": "default",
        "options": {
            "is_secure": false
        },
        "behaviors": [
            {
                "name": "origin",
                "options": {
                    "originType": "CUSTOMER",
                    "hostname": "example.com",
                    "forwardHostHeader": "REQUEST_HOST_HEADER",
                    "cacheKeyHostname": "ORIGIN_HOSTNAME",
                    "compress": true,
                    "tcipEnabled": false,
                    "httpPort": 80
                }
            },
            {
                "name": "cpCode",
                "options": {
                    "value": {
                        "id": 12345,
                        "name": "main site"
                    }
                }
            }
        ]
    }
}

While nominally optional, default rules typically also specify a caching behavior to position the content on the edge, and a report behavior to refine the information you receive in traffic reports.

Each behavior object is identified by a name field. It features a locked member explained below, and most require a nested options object. Some behaviors only feature an enabled option that toggles whether the behavior is activated, while others require more fields once they’re activated. The exact set of options you need to specify for each behavior often varies depending on what you are trying to do, and some options are required based on the value of others. The PAPI Feature Catalog Reference details the requirements for each option.

In the origin example above, the originType is set to CUSTOMER, in which case your own server is the origin and you need to identify it with the hostname field. If the originType were set to any other value, the hostname would be unnecessary and thus ignored. PAPI silently ignores any unexpected values, but it always warns you about any expected values that are missing. (For example, setting the originType to NET_STORAGE would require another netStorage option providing details about your NetStorage account.)

Criteria

Rules are more powerful when they respond to the client request’s different criteria. To do so, the rule needs to specify children containing an array of nested rule objects. Along with a descriptive name, child rules may contain an additional set of criteria objects that determine when its behaviors execute.

In this example, the child rule’s contentType criteria matches requests for common HTML, CSS, and JavaScript files, and applies the gzipResponse behavior to compress them.

{
    "rules": {
        "name": "default",
        "options": {
            "is_secure": false
        },
        "behaviors": [
            {
                "name": "origin",
                "options": {
                    "originType": "CUSTOMER",
                    "hostname": "example.com",
                    "forwardHostHeader": "REQUEST_HOST_HEADER",
                    "cacheKeyHostname": "ORIGIN_HOSTNAME",
                    "compress": true,
                    "tcipEnabled": false,
                    "httpPort": 80
                }
            },
            {
                "name": "cpCode",
                "options": {
                    "value": {
                        "id": 12345,
                        "name": "main site"
                    }
                }
            }
        ],
        "children": [
            {
                "name": "Compress Text Content",
                "criteria": [
                    {
                        "name": "contentType",
                        "options": {
                            "matchOperator": "IS_ONE_OF",
                            "values": [
                                "text/html*",
                                "text/css*",
                                "application/x-javascript*"
                            ],
                            "matchWildcard": true,
                            "matchCaseSensitive": false
                        }
                    }
                ],
                "behaviors": [
                    {
                        "name": "gzipResponse",
                        "options": { "behavior": "ALWAYS" }
                    }
                ]
            }
        ]
    }
}

Criteria are structured exactly the same as behavior objects, with a name string identifier and a nested options object. Most criteria options behave similarly. The values option usually specifies the set of strings you are trying to match. (Throughout PAPI, whenever a value is optionally plural, it is always represented as an array.) Various matchWildcard options allow you to match flexibly with * and ? characters, and various matchCaseSensitive options allow you to ignore case. The matchOperator option typically allows you to invert the result, so that the criteria succeeds if specified values don’t match.

The example above features a single contentType criteria. Once you define more than one, the rule needs a criteriaMustSatisfy field to set whether to match any or all criteria. This alternate example of the children array adds a random criteria to match half the requests for the specified contentType.

"children": [
    {
        "name": "Compress Half of Requests for Text Content",
        "criteriaMustSatisfy": "all",
        "criteria": [
            {
                "name": "contentType",
                "options": {
                    "matchOperator": "IS_ONE_OF",
                    "values": [
                        "text/html*",
                        "text/css*",
                        "application/x-javascript*"
                    ],
                    "matchWildcard": true,
                    "matchCaseSensitive": false
                }
            },
            {
                "name": "random",
                "options": { "bucket": 50 }
            }
        ],
        "behaviors": [
            {
                "name": "gzipResponse",
                "options": { "behavior": "ALWAYS" }
            }
        ]
    }
]

In this example, criteriaMustSatisfy is set to all. If it were set to any, the criteria would compress all text content, and half of all other content, including images that are already compressed. (This is almost certainly not what you want, and exemplifies the sort of bug that falls beyond what the API can identify for you, as discussed in the Errors section.)

Note that rules do not provide any explicit support for else cases in response to criteria matches, but there are a couple of ways to implement them:

  • Specify exclusive pairs of match criteria: From the example above, the first rule could specify a contentType criteria that matches HTML/CSS/JavaScript using a matchOperator of IS_ONE_OF. The second rule could specify the same contentType criteria, only with a matchOperator of IS_NOT_ONE_OF.

  • Override a parent rule’s behavior: In the random example above, if you were to apply some other behavior to the remaining half of the requests, you would need to do so as part of the parent rule. If the parent rule enables a behavior that shouldn’t apply to the child, the child rule needs to specify the behavior again specifically to disable it.

Overall, the rules for how rules work are very simple. They are evaluated from top to bottom. A rule first evaluates its criteria, then executes its behaviors and children if the set of criteria matches. If any behavior is specified more than once within a set of executing rules, the last one overrides those that precede it. In some cases the ordering of different behaviors that perform similar functions may also matter. In other cases you can re-use the same behavior to do different things that don’t conflict with each other, for example, by modifying one HTTP header and then a different one.

Based on the newly added custom hostname discussed in Create a New Edge Hostname, you would typically add a corresponding set of rules. Appending this simple example to the rule’s array of children as part of a PUT request tests the hostname and assigns a different CP code to report on and separately bill for the custom site’s traffic.

{
    "name": "Custom Site",
    "criteria": [
        {
            "name": "hostname",
            "options": {
                "matchOperator": "IS_ONE_OF",
                "values": [ "custom.example.com" ]
            }
        }
    ],
    "behaviors": [
        {
            "name": "cpCode",
            "options": {
                "value": {
                    "id": 54321,
                    "name": "custom site"
                }
            }
        }
    ]
}

TIP: While the hostname criteria matches hostnames, the clientIp criteria matches IP addresses.

Once you’ve completed work on your rule tree, a PUT request with the revised data saves it:

PUT /papi/v0/properties/prp_175780/versions/3/rules/?contractId=ctr_1-1TJZH5&groupId=grp_15225

If the API detects any problems with the data, they are noted as part of the response, and you need to either fix or acknowledge them before you activate the property with that rule tree. See the Activate a Property operation. For details on the range of problems you may encounter when modifying a rule tree, see the Errors section.

Advanced and locked features

In addition to its name and component options, special types of behavior and criteria objects may feature these additional members:

  • A uuid string signifies an advanced feature. Advanced behaviors and criteria are read-only, and can only be modified by Akamai representatives. They typically deploy metadata customized for you, whose functionality falls outside the predefined guidelines of what other read/write behaviors can do. Such metadata might also cause problems if executed outside of its intended context within the rule tree. (Advanced features are identified as read-only in the PAPI Feature Catalog Reference.)

  • If a locked boolean member is true, it indicates a behavior or criteria that your Akamai representative has locked so that you can’t modify it. You typically arrange with your representative to lock certain behaviors to protect sensitive data from erroneous changes. Any kind of behavior or criteria may be locked, including writable ones.

When modifying rule trees, you must preserve the state of any uuid or locked members. You receive an error if you try to modify or delete either of these special types of feature. You can reposition regular features relative to these special ones, for example by inserting them within the same rule, but each rule’s sequence of special features must remain unchanged.

Additionally, rule objects may indicate the presence of special features:

  • A uuid member present on a rule object indicates that at least one of its component behaviors or criteria is advanced and read-only. You need to preserve this uuid as well when modifying the rule tree.

  • A criteriaLocked member enabled on a criteria rule by your Akamai representative means that you may not insert additional criteria objects within the sequence. This typically keeps complex logical tests from breaking. Preserve the state of criteriaLocked when modifying the rule tree.

Inserting variables

For many behavior and criteria option fields, you can inject variable text, custom values that interpret when the property executes at runtime. You can invoke a set of built-in variables to capture contextual information about the client’s request, define your own variables, assign values to them based on these built-in variables or various other inputs, and use transform functions to modify their value at any point throughout the rule tree. You can perform conditional logic based on the variable’s value, and catch any unforeseen runtime errors.

Variables allow you to implement functionality that previously was only possible by injecting advanced custom XML metadata, a process requiring assistance from your Technical Support representative. Variables may not completely replace advanced metadata functionality but can greatly reduce the need.

Throughout the PAPI Feature Catalog Reference, any option fields that allow you to inject variable text are marked allows variables. Within any of those option’s string values, you invoke variable names within pairs of {{}} delimiters. This example of a redirectPlus behavior option invokes the original request’s filename and concatenates it after a static string:

"destination": "/fixed/path/to/{{builtin.AK_FILENAME}}"

Note that, to accommodate the injection of variable strings, some options that reference conceptually numeric data are implemented instead as string types.

When inserting variables into text, you refer to them within a common namespace, in this case builtin for read-only system variables, followed by the unique variable name that is ultimately distributed in the XML metadata. The {{builtin.AK_FILENAME}} variable inserted above translates to %(AK_FILENAME) in XML metadata.

Built-in system variables

The following lists all the built-in system variables available to you. For any of these items that are optional, such as filename extensions, the inserted variable may yield a blank string. Note that the AKA prefix for the first variable listed varies from all others.

Name Description
AKA_PM_CACHEABLE_OBJECT Either true if the requested object is cacheable, or false if not.
AK_BASE_URL The incoming request’s URL path, without filename and extension.
AK_CLIENT_IP Client IP address as seen by the Akamai server, possibly overridden by X-Forwarded-For or Akamai-Client-IP request headers.
AK_CLIENT_REAL_IP The client IP address as seen by the Akamai server, ignoring any request headers.
AK_CLIENT_RTT Milliseconds elapsed for the TCP round-trip (RTT) between client and edge server.
AK_CLIENT_TRANSFER_TIME Milliseconds elapsed to transfer content from edge to client. This value is only available after the client response completes. Applies only to custom log fields.
AK_CLIENT_TURNAROUND_TIME Milliseconds elapsed for the combined initial request (AK_CLIENT_RTT) plus the response’s transfer time (AK_CLIENT_TRANSFER_TIME). This value is only available after the client response completes. Applies only to custom log fields.
AK_CONNECTED_CLIENT_IP The IP on the TCP socket, either client or a redirecting ghost.
AK_CPCODE The CP code associated with the request.
AK_CURRENT_TIME The epoch time when edge metadata is applied to the request. If necessary, use the setVariable behavior to convert epoch time values to other time formats.
AK_DOMAIN The hostname without the initial subdomain, such as example.com when requesting www.example.com.
AK_EXTENSION The filename extension of the incoming request.
AK_FILENAME The complete filename of the incoming request.
AK_FIREWALL_ALERTED_RULES With webApplicationFirewall enabled, a colon-separated list of IDs for firewall rules that triggered an alert for the current request.
AK_FIREWALL_DENY_RULEID With webApplicationFirewall enabled, the ID for a firewall rule set to deny the request when the rule triggers.
AK_FIREWALL_DETECTED_RULES With webApplicationFirewall enabled, a colon-separated list of IDs for all firewall rules that apply to the request.
AK_GHOST_IP The IP address on which end client requests are received, and ultimately resolve for the end user.
AK_GHOST_SERVICE_IP The edge server IP address used to forward a request, also commonly known as the machine IP. This is the IP address the origin server sees as the client IP when it receives a request from the edge.
AK_HOST_CNAME_CHAIN A space-delimited list of the CNAME chain provided by DNS lookup on the incoming Host header.
AK_HOST The incoming request’s hostname.
AK_METHOD The request method, such as GET, PUT, POST, or HEAD.
AK_ORIGINAL_URL The original URL before any processing by Akamai Edge servers.
AK_PATH The original URL path as seen by the Akamai Edge server.
AK_PROTOCOL_NEGOTIATION The protocol negotiated with the client when NPN or ALPN is in use. Under HTTP, possible values are http/1.1 or http/1.0. For HTTP2, values are h2-14 or h2. For SPDY, values are spdy/3.1, spdy/3 or spdy/2.
AK_QUERY The URL’s entire query string.
AK_REQUEST_ID Unique identifier for each request on the edge server, the same as reported in logs.
AK_SCHEME The request scheme, either http or https.
AK_SLOT The incoming request’s slot number.
AK_TLS_CIPHER_NAME For HTTPS and SPDY requests, specifies the name of the cipher used for the SSL connection, otherwise NO-CIPHER for HTTP requests.
AK_TLS_ENCRYPTION_BITS Bits of encryption used for the request.
AK_TLS_PREFERRED_CIPHERS The value of the request’s security:essl.slot-assignment.preferred-ciphers tag.
AK_TLS_SNI_NAME The SNI name submitted by the client.
AK_TLS_VERSION The TLS version used for the connection.
AK_URL The incoming request’s entire URL.

Declaring variables

While the built-in system variables described above are read-only, you can create and modify your own set of user variables. You can base their values on built-in system variables or other data about the request’s context, then transform them as described below.

First you need to declare the variable within the default rule’s variables array, otherwise you get an error when you later try to assign to them or invoke them in option values. The example below defines a single variable whose unique underlying name is VAR_NAME. Variable names may only feature alphanumeric and underscore characters. Uppercase is recommended by convention but is not required.

{
    "rules": {
        "name": "default",
        "options": {
            "is_secure": false
        },
        "variables": [
            {
                "name": "VAR_NAME",
                "value": "default value",
                "description": "This is a sample Property Manager variable.",
                "hidden": false,
                "sensitive": false
            }
        ],
        "criteriaMustSatisfy": "all",
        "criteria": [],
        "behaviors": [],
        "children": []
    }
}

The variable declaration object specifies these members:

Member Type Description
Required
name String The underlying root name of the variable, which must be unique within the set of variables.
hidden Boolean When enabled, the variable is suppressed from session response headers, often used to test content as described in the Debugging section.
sensitive Boolean When enabled, the variable is suppressed from session responses as hidden ones, but it also can’t be invoked within any behaviors that assign values to cookies or response headers. You also can’t assign a sensitive variable to another one that is not sensitive, and you can’t add it to custom logging fields. Use this more stringent option for any personally identifiable information, typically after initially testing on the staging network.
Optional
description String Text for you to keep track of how the variable is used.
value String Initializes a default value. Omitting this member equates to initializing an empty string.

There are three different ways variable names appear:

  • Within the variables declaration, you specify the base VAR_NAME.

  • When you modify the variable with setVariable or match it with matchVariable as described below, you add a PMUSER_ prefix to refer to the variable name as PMUSER_VAR_NAME. (In activated metadata, this appears as %(PMUSER_VAR_NAME).)

  • When you insert the variable as an expression within behavior and criteria option fields, you need an additional user. namespace prefix: {{user.PMUSER_VAR_NAME}}.

Assigning variables

Once you declare a variable within the default rule’s variables array, you assign a value to it using the setVariable behavior, which you can place anywhere as appropriate within the rule tree. This example assigns the value of the built-in AK_EXTENSION variable to store the request’s file extension in a user variable named EXT. To assign a variable, specify the variableName you want to modify, specify the valueSource as EXPRESSION, then as the variableValue inject the variable using the same syntax as in any other option field. In this example, setting the TRANSFORM to NONE means you don’t yet want to change the value.

{
    "name": "setVariable",
    "options": {
        "variableName": "PMUSER_EXT",
        "valueSource": "EXPRESSION",
        "variableValue": "{{builtin.AK_EXTENSION}}",
        "transform": "NONE"
    }
}

The matchVariable criteria allows you to test a variable’s value at runtime. This example set of criteria tests if the request is for a filename with no extension, but requiring a filename and thus excluding any directory-style URLs that end with a slash character:

"criteriaMustSatisfy": "all",
"criteria": [
  {
    "name": "matchVariable",
    "options": {
      "variableName": "AK_FILENAME",
      "mode": "IS_NOT_EMPTY"
    }
  },
  {
    "name": "matchVariable",
    "options": {
      "variableName": "PMUSER_EXT",
      "mode": "IS_EMPTY"
    }
  }
]

NOTE: While the matchVariable criteria offers a way to account for known error scenarios, see the Debugging section for more information on the variableError criteria, which allows you to detect other unforeseen error scenarios that only reveal themselves at runtime.

In response to the test criteria above, one of the rule’s accompanying behaviors may assign a static EXPRESSION of html for use as a default file extension:

{
    "name": "setVariable",
    "options": {
        "variableName": "PMUSER_EXT",
        "valueSource": "EXPRESSION",
        "variableValue": "html",
        "transform": "NONE"
    }
}

You can assign values from many other sources besides built-in system variables. Setting the setVariable behavior’s valueSource to EXTRACT gives you the option to assign more specific values from the request. The extractLocation may specify header, cookie, and query parameter names, certificates, path directory components, and any embedded path parameters. Setting extractLocation to EDGESCAPE allows you to leverage a great deal of location-based data based on this request. The sample behaviors below assign the client request’s geographic location to a pair of LAT and LONG variables.

{
    "name": "setVariable",
    "options": {
        "variableName": "PMUSER_LAT",
        "valueSource": "EXTRACT",
        "extractLocation": "EDGESCAPE",
        "locationId": "LAT",
        "transform": "NONE"
    }
},
{
    "name": "setVariable",
    "options": {
        "variableName": "PMUSER_LONG",
        "valueSource": "EXTRACT",
        "extractLocation": "EDGESCAPE",
        "locationId": "LONG",
        "transform": "NONE"
    }
}

In addition, when the valueSource is set to GENERATE, you can incorporate various random numbers and hex strings into variables. See the setVariable behavior for details on all the sources of information you can assign to variables.

Modifying variables

In all of the examples above, the transform option is set to NONE, which leaves the value unchanged after assigning it, but it supports a large set of functions that in effect offers an embedded programming language. Transform functions allow you to:

  • do basic arithmetic
  • perform bitwise operations
  • convert case
  • locate and generate substrings
  • make regular expression substitutions
  • perform many conversions and encodings

See the setVariable behavior for comprehensive details.

To modify a value within any setVariable behavior, set its transform function along with any necessary dependencies. Each behavior can only transform its value once, so to transform a value more than once you need to form a chain of setVariable behaviors. Each subsequent behavior must reassign the transformed value back to itself, then perform an additional transformation.

This simple example modifies a LANG user variable, assigning it the value of the request’s Accept-Language header. The initial behavior performs a SUBSTRING transform to limit the string to the initial two-letter code. The second behavior reassigns {{user.PMUSER_LANG}} back into LANG, then runs the UPPER transform to convert to uppercase.

{
    "name": "setVariable",
    "options": {
        "variableName": "PMUSER_LANG",
        "valueSource": "EXTRACT",
        "extractLocation": "CLIENT_REQUEST_HEADER",
        "headerName": "Accept-Language",
        "transform": "SUBSTRING",
        "startIndex": "1",
        "endIndex": "2"
    }
},
{
    "name": "setVariable",
    "options": {
        "variableName": "PMUSER_LANG",
        "valueSource": "EXPRESSION",
        "variableValue": "{{user.PMUSER_LANG}}",
        "transform": "UPPER"
    }
}

For more details on how to use variables within the Property Manager portal, see Variables.

Understanding rule formats

PAPI provides rule format schema objects that define the features you may enable under a product. This section shows how to interpret a rule format and use it to validate a rule tree or research available features.

The schema’s relevant content is nested within the outer object’s definitions member, which is empty in this example:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "rules": {
            "$ref": "#/definitions/toprule"
        }
    },
    "required": [ "rules" ],
    "definitions": {
    }
}

The top level of the schema specifies only that the rule tree must feature a rules member, specified indirectly within a large definitions section that the example above does not display. The toprule itself specifies an object that must feature a name. While these specify the object’s basic structure, the definition’s catalog member contains available features, separately within the behaviors and criteria sub-trees. Each of those object’s keys list supported features, and the values define their components.

NOTE: The features specified in the rule format represent all the behaviors and criteria the product supports, not necessarily those currently enabled for your account. Each product specifies a baseline set, with other more specialized features enabled via add-on modules, as discussed in PAPI Concepts. To determine the set of features currently available on your account, saving a property that specifies them returns an error that notifies you otherwise.

The following shows a typical behavior definition for caching, along with its component options, some of whose data types are referenced elsewhere within the schema.

"caching": {
    "type": "object",
    "properties": {
        "name": {
            "enum": [ "caching" ]
        },
        "uuid": {
            "type": "string"
        },
        "options": {
            "type": "object",
            "properties": {
                "behavior": {
                    "enum": [ "max-age", "no-store", "bypass-cache", "both", "cc", "expires" ],
                    "default": "max-age"
                },
                "mustRevalidate": {
                    "enum": [ "off", "on" ],
                    "default": "off"
                },
                "ttl": {
                    "$ref": "#/definitions/catalog/option_types/duration"
                },
                "defaultTtl": {
                    "$ref": "#/definitions/catalog/option_types/duration"
                }
            }
        }
    }
}

Understand the limitations of the rule format’s available data. While each option’s basic data type is specified, additional validation logic is not necessarily available within the schema, and may be implemented as part of the API’s back end. The rule format also does not represent dependencies among the options. For example, many behaviors feature a high-level enabled switch. When disabled, the API typically ignores any other specified option. When enabled, there may be other contextual dependencies among the options. The PAPI Feature Catalog Reference details most of these dependencies.

Rule formats often specify only minimal validation criteria. For example, the rule format’s option_types section describes custom data formats, such as the following to represent a CP code object with a required id member:

"cpCode": {
    "type": "object",
    "properties": {
        "id": {
            "type": "number"
        }
    },
    "required": [ "id" ]
},

The rule format does not specify the name member that also typically appears within a cpcode object. It does not specify what happens if you omit the name, or supply other members unknown to the API’s back end. The back end may behave slightly differently over time, even if you freeze the API’s set of features.

Errors

This section shows you how to handle various kinds of error responses the Property Manager API generates. In addition to standard HTTP error responses, it discusses how to resolve errors reported in rule trees before you activate a property, and how to deal with errors from variables as they are interpreted on the edge once you activate a property. This section also lists the range of HTTP response codes, provides details for many API-specific error messages along with their likely causes, and reports any known issues remaining in the current API release.

Known issues

The following known issues may affect your ability to use the Property Manager API:

  • Large rule trees that take more than 5 minutes to validate may time out with a 500 error. As a workaround, try to create smaller configurations targeting smaller sets of hostnames. The less executable logic each configuration contains, the less time it takes to validate it.

  • If you associate PAPI credentials with a user who has access to more than one portal account, attempts to create edge hostnames result in authorization errors.

  • If you create a property within Property Manager with an empty set of hostnames, a GET request to Property Version Hostnames results in a 500 error.

  • Some streaming media configurations are not supported. PAPI supports all properties supported by Property Manager.

  • Before using PAPI, any properties that use the older Configuration Manager must first be upgraded to the Property Manager within the Luna portal.

JSON problems

API endpoints routinely respond with failure codes to a wide range of problems with the integrity of the data you are trying to modify, everything from malformed JSON, to missing fields, to mismatching etags digests. The API returns these error responses in the standard JSON Problem format.

PAPI also serializes problems in some success responses. PAPI allows you to succeed in saving property rule or hostname data in a state that would later fail on activation, but by default it embeds guidance about each problem within the response. Two kinds of problem appear in success responses:

  • An errors array notes any problem that would prevent activation. You need to fix these before activating the property.

  • A warnings array notes less severe issues. You can either modify the data in response, or acknowledge the set of warnings when later activating the property.

For example, when you try to PUT a rule tree that’s missing required origin and cpCode behaviors, a 200 response identifies them as errors:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_173136",
    "propertyVersion": 3,
    "etag": "a9dfe78cf93090516bde891d009eaf57",
    "errors": [
        {
            "type": "/papi/v0/errors/validation.required_behavior",
            "title": "Missing required behavior in default rule",
            "detail": "In order for this property to work correctly behavior Content Provider Code needs to be present in the default section",
            "instance": "/papi/v0/properties/prp_173136/versions/3/rules#err_100",
            "behaviorName": "cpCode"
        },
        {
            "type": "/papi/v0/errors/validation.required_behavior",
            "title": "Missing required behavior in default rule",
            "detail": "In order for this property to work correctly behavior Origin needs to be present in the default section",
            "instance": "/papi/v0/properties/prp_173136/versions/3/rules#err_101",
            "behaviorName": "origin"
        }
    ],
    "rules": {
        "name": "default",
        "options": {
            "is_secure": false
        },
        "children": [
            {
                "name": "Handle /my-path",
                "criteriaMustSatisfy": "all",
                "criteria": [
                    {
                        "name": "wildcard",
                        "value": ["/my-path"]
                    }
                ],
                "behaviors": [
                    {
                        "name": "caching",
                        "behavior": "MAX_AGE",
                        "ttl": "1m"
                    }
                ]
            }
        ]
    }
}

Even though you can save the rule tree, you can’t activate the property until you add the missing behaviors. (See the Rule Trees section for guidance on how to structure rule trees.)

PAPI also allows you the option to skip potentially lengthy validation tests that would result in these errors and warnings. You would still need to address the problems prior to activation, but this option allows you to modify and save data more quickly as a matter of routine throughout your development cycle. See Validation and Activation Time for more information.

Debugging rule trees

The API may release a wide range of validation errors based on the content of rule trees, many of which are detailed below. A few unusual error scenarios are unique to PAPI:

  • As discussed in the Resources section, you can freeze the API to use a specific set of behavior and criteria versions. If instead you specify the rule format that uses the latest versions, behaviors and criteria silently update, and may produce errors if their validation requirements change. Other validation errors may remain even when properly updating from one rule format version to another.

  • As discussed in the Rules section, some behaviors and criteria are locked and read-only, and can only be modified with assistance from Akamai Professional Services. You get an error if you try to modify or move them elsewhere within the rule tree.

  • As discussed in the Rule Trees section and detailed in the PAPI Feature Catalog Reference, some options may be required depending on the values of others. It is much easier to accidentally omit necessary values in the API than in the Luna interface.

  • Some errors may reference Schema objects, which you can examine to determine each product’s support for behaviors and criteria. They also list the full set of options for each, along with their expected data types. However, schemas do not represent dependencies among options.

Aside from errors, PAPI more often returns a set of warnings after checking your chosen set of behaviors and criteria for identifiable logical inconsistencies. Here is a typical warning, whose errorLocation is a URL fragment that can be interpreted as a JSON Pointer expression to help you locate the problem within the JSON tree you submitted:

"warnings": [
    {
        "type": "https://problems.luna.akamaiapis.net/papi/v0/validation/need_feature",
        "errorLocation": "#/rules/behaviors/5",
        "detail": "`Tiered Distribution` only applies to cacheable
              content, but caching was never turned on."
    }
]

Behaviors such as tieredDistribution and prefreshCache can only operate on cached content on edge servers, so the warning identifies when the caching behavior is not enabled. As another example, the cacheKeyIgnoreCase behavior allows requests for files and query parameters with mixed upper- and lower-case letters to resolve to the same cache key. If you pair that behavior with a criteria that doesn’t also specify a case-insensitive match, the warning alerts you not to apply different behaviors to the same cached object based on random variations in case among incoming requests.

These warnings often identify obvious logical problems, such as exclusive sets of criteria when criteriaMustSatisfy is set to all, or nested criteria that can never execute because they’re logically exclusive with their ancestor rules’ criteria. However, as in all programming environments, no validation mechanism can identify all potential bugs, so you need to carefully step through the code. You can also request text/xml rather than application/json from the Property Versions interface if you would rather look at how a version’s combined set of rules and hostnames translate to the Akamai metadata that is ultimately distributed to edge servers. Contact your Akamai Professional Services representative if you need to better understand the metadata.

NOTE: Like the Luna Control Center portal, the API may require you to acknowledge each warning before you activate a property. Unlike the Luna portal, you can batch-acknowledge all warnings by setting acknowledgeAllWarnings to true on the new activation. Either way, pay careful attention to any warnings you have received before you activate a property version, or your site can experience serious problems.

Debugging variables

Most problems with rule trees are detected prior to activation, but problems with variables often occur only at runtime, and are thus more challenging to debug.

The most useful way to debug variables is to view their values in session-related response headers for test content on the staging network:

  1. As discussed in the section on Declaring Variables, each variable defined in the default rule features two hidden and sensitive options, and you first need to disable both for any variables you want to inspect.

  2. Activate the property that includes the variables on the staging network.

  3. Once content activates, send a Pragma:akamai-x-get-extracted-values header in your test requests. The response includes X-Akamai-Session-Info headers that reflect the value of each declared variable.

  4. After debugging, re-enable the hidden and sensitive options if necessary before activating to the production network.

Logging variables in session response headers allows you to check their final values after the rule tree executes. To specifically respond to errors as they occur within the rule tree, you can apply variableError criteria as part of a debugging rule after any setVariable that may cause a problem. For example, if you set user variables that extract the contents of a specific header or cookie name, an error results if either item is missing from the request. The following criteria test executes if any errors occur for the specified set of variables:

{
    "name" : "variableError",
    "options" : {
        "variableNames" : "CUSTOM_HEADER CUSTOM_COOKIE"
    }
}

This approach does not allow you to report on the specific error, but you can still fashion appropriate behaviors, especially for use in testing on the staging network. For example, this denies the request and responds with an appropriate error:

{
    "name" : "denyAccess",
    "options" : {
        "enabled" : true,
        "reason" : "missing-required-header-or-cookie"
    }
}

For more details on how variables work within rule trees, see Assigning Variables, or Variables. within the Property Manager portal.

JSON request schema

Errors about malformed data typically reference schema objects that describe whichever resource you are trying to interact with. PAPI provides a separate Request Schema interface for these objects that reference specific schema files. For example, the following describes the expected data structure when creating a new edge hostname:

GET /papi/v0/schemas/request/EdgeHostnamesPostRequestV0.json

HTTP success codes

The API produces the following range of HTTP success codes:

Code Description
200 The request is successful.
201 The new item was successfully created.
204 The item was successfully removed.
302 The requested item is available at the link provided.

The tables below provide details for many of the errors you may encounter, along with the HTTP status codes they share. (Note that this is not an exhaustive listing, and excludes problems relating to rule trees.) Each problem object’s type member corresponds to items listed in the tables below. Problem types reported in HTTP error responses follow this URL pattern, where the type identifier may include an additional slash character:

https://problems.luna.akamaiapis.net/papi/{version}/{type}

URLs for many problem types included within rule tree and property hostname response objects are formed with an additional validation component:

https://problems.luna.akamaiapis.net/papi/{version}/validation/{type}

HTTP errors

Code Type Problem
400 http/bad-request The system cannot understand your request, perhaps due to malformed data.
401 http/unauthorized The request requires authentication.
403 http/forbidden The authorization token does not allow access to the resource. For example, the request may specify products not authorized on a contract.
404 http/not-found Unable to locate the requested resource.
405 http/method-not-allowed The specified HTTP method is not supported for this resource.
406 http/not-acceptable The content-type restriction specified by your Accept header is not supported.
412 etag-conflict The Etag you provided does not match the most recent edit. The data has changed since initially accessed. Learn more.
412 http/precondition-failed Preconditions such as If-Match or If-Not-Match are not satisfied. The data has changed since initially accessed. Learn more.
415 http/unsupported-media-type The requested MIME format is not allowed.
500 http/internal-server-error The platform experienced an unknown error.
501 http/not-implemented The platform does not support the requested functionality.

Data errors

Code Type Problem
400 json-mapping-error Your input could not be validated against the schema, most likely because it is not the expected data type.
400 json-parse-error Your input could not be parsed as JSON. The problem response provides details on the location of the parsing error.
400 json-schema-invalid Your input does not validate against the data’s schema.
400 missing-request-body-field Your request is missing a Body field.
400 missing-required-parameter The request URL is missing a required parameter, which is detailed in the problem response.

Edge hostname errors

Code Type Problem
400 edgehostname/bad-suffix The edge hostname’s specified domainSuffix is not allowed. Learn more.
400 edgehostname/not-available The specified edge hostname is not available.
403 edgehostname/create-forbidden The product you assigned to the edge hostname is not included in your contract. Learn more.
429 limit-exceeded.edgehostnames_per_contract You exceeded the limit on the number of edge hostnames for your contract, and must deactivate one before proceeding. Contact your Akamai representative for information on how to increase this limit. Learn more.
500 edgehostname/create-error The platform encountered an unknown error when trying to create the edge hostname.

Property hostname errors

Code Type Problem
400 property-version-hostname/bad-cnameto The cnameTo value references an edge hostname that doesn’t exist.
400 property-version-hostname/edgehostname-mismatch You supplied both a cnameTo and edgeHostnameId that reference different hostnames. Learn more.
400 property-version-hostname/missing-cnameto-or-edgehostnameid You need to specify either a cnameTo or a edgeHostnameId member. Learn more.
501 property-version-hostname/unsupported-cnametype You can only specify a property hostname whose cnameType is EDGE_HOSTNAME. Learn more.

An additional set of errors may be listed within Hostname objects that prevent you from activating the property version:

Type Description
generic_behavior_issue.origin_name_hostname_overlap An origin may not specify the same hostname as a property.
hostnames.bad_hostname_format The hostname is not formatted properly.
hostnames.disallowed_akamaihd_dot_net_hostname The AkamaiHD hostname is invalid. The prefix for a.akamaihd.net has a maximum 16 alphanumeric and underscore characters.
hostnames.disallowed_akamaized_dot_net_hostname The hostname may not specify akamaized.net.
hostnames.dualstack_dissuasion_warning Make sure your origin can handle IPv6 traffic.
hostnames.duplicate_hostname The hostname is listed more than once.
hostnames.empty_hostnames Specify at least one property hostname.
hostnames.empty_string_hostname The hostname may not be empty.
hostnames.hostname_contains_underscore Avoid underscore characters in hostnames, which may cause problems for some DNS resolvers.
hostnames.insecure_property_secure_edge_hostname A secure edge hostname is incompatible with your non-secure property.
hostnames.max_hostnames_limit_hard You have reached the maximum number of hostnames per property. Either reconfigure using the instantConfig behavior, split your hostnames across more than one property, or consult with your account representative.
hostnames.max_hostnames_limit_soft You have exceeded the optimal number of hostnames per property. Either reconfigure using the instantConfig behavior, split your hostnames across more than one property, or consult with your account representative.
hostnames.mdc_subdomain_prefix The hostname is formatted incorrectly, and can’t begin with a hyphen.
hostnames.missing_edgehostname A property hostname needs to reference a corresponding edge hostname.
hostnames.secure_property_insecure_edge_hostname An edge hostname is incompatible with your secure property.
hostnames.secure_property_insecure_edge_hostname_shared_cert An edge hostname is incompatible with your secure property.
hostnames.shared_cert_subdomain_prefix The hostname is formatted incorrectly, and can’t begin with a hyphen.
hostnames.unknown_edge_hostname The edge hostname is unavailable, and may not exist.

Property errors

Code Type Problem
400 property/invalid-name Property names may only use alphanumeric characters, underscores, dashes, and dots.
400 property/name-in-use Each property name must be unique.
403 property-version/lock-error Only Akamai representatives can change read-only behaviors, criteria, and child rules. Learn more.
403 property-version/lock-error/behaviors-changed Read-only behaviors have been added, removed, changed, or moved. Learn more.
403 property-version/lock-error/criteria-changed Read-only criteria have been added, removed, changed, or moved. Learn more.
403 property-version/lock-error/rule-structure-changed Read-only rules have been added, removed, changed, or moved. Learn more.
404 property-deletion/not-found The property you are trying to delete is unknown.
404 property-version/not-found The requested Property version is not available.
429 limit-exceeded.properties_per_contract You exceeded the limit on the number of properties for your contract, and must deactivate one before proceeding. Contact your Akamai representative for information on how to increase this limit. Learn more.
500 property-version/error The platform could not process your request on the specified property version.

Activation errors

Code Type Problem
400 activation/bad-notifyemails Activations require at least one email address specified in the notifyEmails array. Learn more.
400 activation/missing-compliance-record-info For Akamai representatives activating customers’ properties, nonComplianceReason cannot be NONE without having a valid unitTested, peerReviewedBy, and customerEmail. Either provide those values or change to a different nonComplianceReason.
400 activation/missing-compliance-record Akamai representatives must provide a compliance record before activating a property on customers’ behalf on the production network. For details, see the required schema: /papi/v0/schemas/request/CreateNewActivationRequestV0.json #/properties/complianceRecord.
400 activation/self-peer-review Akamai representatives may not peer review their own activations.
400 activation/warnings-not-acknowledged Before proceeding, you must acknowledge the activation warnings listed in the problem response. Learn more.
403 property-version/already-activated The specified property version has already been activated. To make changes you must first create a new property version.
404 activation-cancellation/not-found The activation you are trying to cancel is unknown. Learn more.
422 activation-cancellation/unprocessable-status The activation is not in a pending state, so it can’t be canceled. Learn more.
422 activation/already-activated The property version has already been activated.
422 activation/still-pending The property version is currently pending activation or deactivation. Please wait until the operation is complete before starting another activation or deactivation.
429 rate-limit-exceeded.activations You made too many activations in the amount of time allowed for your contract. The problem response provides details on when you can request more activations. Learn more.
500 activation-cancellation/cancel-error The platform could not cancel the activation.
500 activation/property_activation_failed The property activation failed.
500 deactivation/property_deactivation_failed The property deactivation failed.

Behavior/criteria errors

These general errors relate to how you implement behaviors and criteria. They may be listed within Rule objects, and may prevent you from activating the property version:

Type Description
compatible_behaviors Rules include incompatible behaviors.
condition_no_prompt_upgrade You must upgrade to a new version of a criteria.
deprecated The behavior has been deprecated.
deprecated_delete The behavior has been removed.
deprecated_readonly The behavior has been deprecated.
duplicate_feature Two behaviors of the same type are inappropriately placed within the same rule.
feature_no_prompt_upgrade A new version of the behavior is available, requiring an upgrade.
feature_upgrade_required The property needs to be upgraded to replace a deprecated behavior.
feature_upgrade_required_readonly The property needs to be upgraded to replace a deprecated behavior, but this version can’t be edited. Create a new version if necessary.
feature_upgrade_required_viewonly A new version of the behavior is available, requiring an upgrade.
generic_behavior_issue.kss_not_object A new version of the behavior is available that may require a different set of options.
generic_behavior_issue.netstorage_group_not_available A specified NetStorage account is not associated with this property’s group.
generic_behavior_issue.origin_missing_auxlist_subtitle Your auxiliary certificate list specifies trusted items not reflected in what your origin behavior specifies. Confirm they are accurate, and contact your account team if there is a problem.
generic_behavior_issue.origin_missing_trust_ca_certs_from_underride Your auxiliary certificate list specifies trusted items not reflected in what your origin behavior specifies. Confirm they are accurate, and contact your account team if there is a problem.
generic_behavior_issue.origin_missing_trust_certs_from_underride Your auxiliary certificate list specifies trusted items not reflected in what your origin behavior specifies. Confirm they are accurate, and contact your account team if there is a problem.
generic_behavior_issue.origin_valid_cn_missing_values_from_underride_error The origin behavior’s customValidCnValues option is missing CN/SAN match values from the auxiliary certificates list, so an ordinarily trusted certificate may not be trusted, and may result in a service outage.
generic_behavior_issue.origin_valid_cn_missing_values_from_underride_warning Confirm the origin behavior’s customValidCnValues option includes all CN/SAN values from the auxiliary certificates list.
generic_behavior_issue.origin_valid_cn_wildcard Values in the origin behavior’s customValidCnValues option may contain a star (*) character, but it is interpreted literally.
incompatible_condition There is an incompatibility with a specific criteria within the same rule.
incompatible_features There is an incompatibility with a specific behavior within the same rule.
incompatible_stages.multiple There is an incompatibility with a set of match criteria.
incompatible_stages.none There is an incompatibility with a criteria in a parent rule.
incompatible_stages.one There is an incompatibility with a criteria that appears in the same rule.
required_feature The default rule requires a behavior for the property to work.
too_many_instances There are more instances of the specified behavior than allowed within a property.
unknown_condition The criteria is not supported, and you need to remove it before activating your property.
unknown_feature The behavior is not supported, and you need to remove it before activating your property.
unknown_feature_attribute The behavior or criteria specifies an unknown option.

Option value errors

These errors may be listed within Rule objects, and may prevent you from activating the property version:

Type Description
generic_behavior_issue.table_option_dup_row The option specifies duplicated items.
illegal_option_value_format.features A behavior option’s data type is invalid.
illegal_option_value_format.matches A criteria option’s data type is invalid.
insecure_string_value Option values may not specify %( text.
non_ascii The option specifies non-ASCII characters.
option_empty The option may not specify an empty value.
option_required.features The behavior is missing a required option.
option_required.matches The criteria is missing a required option.
option_required_when.features The behavior is missing an option that’s required when another of its options is set to a specific value.
option_required_when.matches The criteria is missing an option that’s required when another of its options is set to a specific value.

Variable-related errors

These errors may be listed within Rule objects, and may prevent you from activating the property version:

Type Description
cannot_validate The option can’t be validated because the value of its embedded variable can only be known at runtime.
duplicate_variable There is more than one declared variable with the same name.
empty_variable_name The name of the variable can’t be empty.
internal_variable_in_xml An advanced behavior specifies a variable that uses a reserved prefix.
no_variable_support Your contract does not support use of variables.
syntax_error_in_variable_expression.illegal_expression There is a format error in a variable expression.
syntax_error_in_variable_expression.illegal_prefix There is an illegal prefix in a variable expression.
syntax_error_in_variable_expression.missing_end_token There is a missing end token in a variable expression.
unknown_variable_name An undeclared variable name was invoked.

Metadata errors

These errors may be listed within Rule objects, and may prevent you from activating the property version:

Type Description
advanced_override_metadata_enabled A rule specifies advanced metadata that potentially overrides other configurations specified in previous rules.
badly_formatted_xml The behavior specifies invalid XML metadata.
conflicting_xml A behavior may not work as expected because advanced metadata may cause conflicts.

Contract, account, and CP code errors

Code Type Problem
429 cpcode/rate-limit-reached You made too many CP code requests. Try again later.
403 cpcode/invalid-services The current product does not allow you to create CP codes.

These errors may be listed within Rule or Hostname objects, and may prevent you from activating the property version:

Type Description
advanced_cpcodes_outside_account_cp_validated_false The property invokes a CP code not provisioned under this account, and Origin Domains will be enforced. Contact your account representative for more information.
advanced_cpcodes_outside_account_cp_validated_true The property invokes a CP code not provisioned under this account, and Origin Domain enforcement is disabled. Choose different CP codes, or move them into the current account.
advanced_cpcodes_outside_group_or_contract The property invokes a CP code that doesn’t belong to its group or contract.
fixed_limit_exceeded A limit has been exceeded for the property.
generic_behavior_issue.cpcode_created_recently The property invokes a recently created CP code that may not have fully propagated across the network. Activating the property version may disrupt your service.
generic_behavior_issue.cpcode_not_available The specified CP code can’t be used with this property. If you just created the CP code, try again later.
limit_key.elements_per_property The property exceeds the number of allowed behaviors and criteria.
limit_key.max_nested_rules The property exceeds the number of nested rules allowed.
not_granted_by_modules_on_contract Your current contract does not include a necessary module.
not_granted_by_modules_on_contract_readonly Your current contract does not include a necessary module.
product_behavior_issue.cpcode_incorrect_product The CP code is not configured for use with this property’s product, which may affect how traffic is reported.
product_not_on_contract The product is not available on your contract. Add the product to the contract, or switch the property to a different product or contract.

Criteria-specific errors

These errors relate to how specific match criteria execute. They may be listed within Rule objects, and may prevent you from activating the property version.

Type Description
cloudlets_origin_group For cloudletsOrigin criteria to work, there must be an allowCloudletsOrigins placed within a parent rule.
incompatible_origin_type The cloudletsOrigin criteria only works when the origin behavior’s originType is set to CUSTOMER, NET_STORAGE, or APPLICATION_LOAD_BALANCER.
incompatible_with_any_conditions Specifying cloudletsOrigin along with any other criteria may make the origin inaccessible during a client request.
need_allowpatch To use requestMethod to match PATCH requests, you need to enable the allowPatch behavior.
need_allowpost To use requestMethod to match POST requests, you need to enable the allowPost behavior.
need_token_verify_behavior The tokenAuthorization match requires a verifyTokenAuthorization behavior in a parent rule with its failureResponse option disabled.
need_webdav To use requestMethod to match the specified method, you need to enable the webdav behavior.
onlyonedge Criteria such as clientIp, clientIpVersion, userLocation, and userNetwork only match on edge servers, not when requests are forwarded to other Akamai servers. Contact your Akamai representative for guidance.
options_with_webdav Requests that specify the OPTIONS method are always passed to the origin, so you can’t use requestMethod to match them.
origin_is_required The cloudletsOrigin behavior must be paired with an origin behavior.
requires_spdy The bucket criteria can only be used along with the spdy behavior.
should_vary_by_user_agent When modifying content based on the deviceCharacteristic, you should use the modifyOutgoingResponseHeader behavior to specify a Vary: User-Agent header.
suggest_audiencesegmentation Rather than randomly segmenting your traffic, consider applying audienceSegmentation to divide users into different groups based on a persistent cookie.
upper_lower_warning The match specifies a lowerBound value that is greater than the upperBound.
warn_use_headers Requests that don’t include an X-Forwarded-For header do not match. Consider disabling the useOnlyFirstXForwardedForIp option.

Behavior-specific errors

These errors relate to how specific behaviors execute. They may be listed within Rule objects, and may prevent you from activating the property version.

Type Description
206override The responseCode behavior’s 206override option allows the 206 response to be overwritten, not recommended because it applies to byte-range responses. Please confirm you want to do this, and contact your Akamai representative for guidance.
advanced_on_image_management_off The imageManager behavior is configured to use a custom policy, but the behavior is disabled, so it has no effect.
advanced_on_warning When overriding the default policy, if the specified policyToken is not found, imageManager applies the default and does not save the one you specified.
applicationloadbalancer_needed For an APPLICATION_LOAD_BALANCER origin to work, an applicationLoadBalancer behavior must also be enabled.
aws_verificationmode_validation To set a third-party origin hostname, set the verificationMode to THIRD_PARTY or CUSTOM.
basic_redirect_conflict You can’t specify both the redirect and redirectplus behaviors.
beware_of_conditions A behavior that implements a persistent connection may mean that a specified condition no longer works.
cache_key_case_off_ext_case_on With cacheKeyIgnoreCase enabled, you should not specify a case-sensitive match, otherwise two different requests that vary only by case may get different results, even though they refer to the same cached object.
cache_key_case_off_filename_case_on With cacheKeyIgnoreCase enabled, you should not specify a case-sensitive match, otherwise two different requests that vary only by case may get different results, even though they refer to the same cached object.
cache_key_case_off_path_case_on With cacheKeyIgnoreCase enabled, you should not specify a case-sensitive match, otherwise two different requests that vary only by case may get different results, even though they refer to the same cached object.
cachekeyqueryparams Since NET_STORAGE origin servers do not honor query strings, set cacheKeyQueryParams to IGNORE_ALL to avoid more than cache key for the same object.
caching You are potentially caching content identified as personallyIdentifiableInformation, so you should set the caching behavior to NO_STORE or BYPASS_CACHE.
caching_bypass The specified behavior only applies to cachable content, not when caching is set to NO_STORE or BYPASS_CACHE.
caching_enabled The sureRoute behavior only applies when caching is set to NO_STORE.
caching_maxage For best performance when using a NET_STORAGE origin, set the caching ttl to over 10 minutes.
can_not_mix_delegate_and_custom You can’t specify more than one origin behavior with a verificationMode of both PLATFORM_SETTINGS and CUSTOM.
centralauth A NET_STORAGE origin can’t be used along with centralAuthorization.
changing_cpcode_warning CP codes specified by imageManager affect cached images. If you change the CP codes after deploying the images in a production environment, image caches get refreshed, which may overload your origin.
conflict_dscaching Applying a behavior that modifies Cache-Control or Expires headers may interfere with caching when both are applied to the same request.
cookie_value_empty_need_to_disable_session_persistence The edgeLoadBalancingOrigin behavior’s enableSessionPersistence is on, but edgeLoadBalancingDataCenter is missing a cookieName.
cookie_value_set_need_to_enable_session_persistence The edgeLoadBalancingOrigin behavior’s enableSessionPersistence is off, but edgeLoadBalancingDataCenter specifies a cookieName that does not work.
cpcode_behavior_not_allowed The cpCode behavior can’t appear within the same rule as imageManager, which specifies its own CP code settings.
customer_origin If the origin server does not support etags, the largeFileOptimization behavior may not work correctly, and data may be corrupted.
disable_gzip When enabling edgeSideIncludes, do not set gzipResponse to ALWAYS work, otherwise content goes through compression and decompression unnecessarily.
dontallow_caching The downgradeProtocol behavior is not allowed when caching is set to NO_STORE or BYPASS_CACHE.
dontallow_delete The downgradeProtocol behavior is not allowed along with allowDelete.
dontallow_modoutgoingreqheader The downgradeProtocol behavior is not allowed along with modifyOutgoingRequestHeader.
dontallow_pii The downgradeProtocol behavior is not allowed for content marked as personallyIdentifiableInformation.
dontallow_post The downgradeProtocol behavior is not allowed along with allowPost.
dontallow_put The downgradeProtocol behavior is not allowed along with allowPut.
downstream_bust The shutr behavior busts downstream caches to prevent non-Akamai proxies from tampering with content. If downstreamCache is set to values other than BUST, shutr overrides it.
downstream_caching_indeterminate A specified behavior may expose content identified as personallyIdentifiableInformation. You should set a downstreamCache to BUST the cache, or ALLOW it but with sendPrivate enabled.
downstream_caching_without_private A specified behavior may expose content identified as personallyIdentifiableInformation. You should set a downstreamCache to BUST the cache, or ALLOW it but with sendPrivate enabled.
elb_must_use_other_cn When using an EDGE_LOAD_BALANCING_ORIGIN_GROUP origin, you can’t specify {{Origin Hostname}} in the customValidCnValues.
elb_origin_definition_needed To specify an origin of EDGE_LOAD_BALANCING_ORIGIN_GROUP, you must also enable an edgeLoadBalancingOrigin behavior that defines the origin.
elb_origin_missing An edgeLoadBalancingAdvanced behavior requires an accompanying edgeLoadBalancingOrigin.
empty_cookie_value_and_failover_rules The edgeLoadBalancingDataCenter is invalid because its cookie value is empty and enableFailover is turned off.
extension_match_advised To apply this behavior to large files, you should match the fileExtension or otherwise avoid applying the behavior to small files, for which it may cause a delay.
filename_match_advised You should enable limitBitRate with a filename, fileExtension, or path match.
g2o_modoutgoing_warning You can’t use modifyOutgoingResponseHeader to modify the X-Akamai-G2O-Auth-Data and X-Akamai-G2O-Auth-Sign headers specified by the g2oheader behavior.
http2_requires_secure The http2 behavior requires that the property is_secure.
includeallqs If one cacheId behavior is set to INCLUDE_ALL_QUERY_PARAMS, there can’t be another in the same rule that includes or excludes specific parameters.
includeqs If one cacheId behavior is set to include a specific set of query parameters, there can’t be another in the same rule that excludes others.
incompatible_opts The failAction behavior is not compatible when the origin is set to EDGE_LOAD_BALANCING_ORIGIN_GROUP.
incompatible_originbasepath You can’t apply the rewriteUrl and baseDirectory behaviors to the same request.
incompatible_ppf_siteshield The siteShield behavior is incompatible with predictivePrefetching.
incompatible_with_any_conditions You can’t specify allowCloudletsOrigins with any matching criteria.
incompatible_with_any_features You can’t specify allowCloudletsOrigins along with any other behaviors. It must be alone in its own rule.
incompatible_with_netstorage deliveryReceipt is not compatible when the origin is NET_STORAGE.
incompatibleesi You may only enable akamaizer with edgeSideIncludes.
incompatibleredirect The responseCode behavior may not work as expected along with redirect, because they use different status codes.
invalid_origincertstohonor_options The origin hostname is AWS and the verificationMode is CUSTOM, but the originCertsToHonor is not set to STANDARD_CERTIFICATE_AUTHORITIES or COMBO.
ip_address_origin You should specify your origin server as a hostname. IP addresses may be abruptly reassigned and negatively affect your service.
lfo_with_td_ch2 A tieredDistribution whose tieredDistributionMap doesn’t specify CH or CH2 can’t be applied within a secure property along with a largeFileOptimization whose useVersioning is enabled.
logging_cookies You are using report to log values for cookies in responses identified as personallyIdentifiableInformation. Make sure the cookies are not exposing sensitive information.
min_24hr_ttl_required Any rule that contains imageManager must also specify a caching behavior with a ttl of at least 1 day.
missing_edge_image_converter The watermarkUrl behavior requires a corresponding edgeImageConversion in the same rule or in a child rule.
missing_elb_origin An edgeLoadBalancingDataCenter requires an accompanying edgeLoadBalancingOrigin.
missing_origin To use simulateErrorCode for the ERR_NO_GOOD_FWD_IP error, healthDetection must be enabled.
mobile_302_conflict Mobile redirect only supports the 302 status code.
mobile_default_conflict A mobile redirect can’t be used in the same rule as a default redirect.
must_be_in_cloudlets_origin_group To enable an origin of EDGE_LOAD_BALANCING_ORIGIN_GROUP, you must also define a cloudletsOrigin rule.
need_additional_match The prefetchable behavior needs to be enabled by a filename or fileExtension match.
need_customer_origin The downgradeProtocol behavior is only allowed when the origin is set to CUSTOMER.
need_data_center_defined To enable the edgeLoadBalancingOrigin behavior’s enableSessionPersistence option, you need to configure an edgeLoadBalancingDataCenter.
needs_akamaizer The akamaizer behavior needs to be enabled for akamaizerTag to work.
needs_akamaizertag There must be at least one akamaizerTag for akamaizer to work.
needs_content_match The edgeSideIncludes behavior may only be used in rules with matching criteria such as path, contentType, or filename.
needs_contenttype You may only enable akamaizer within a contentType match.
netstorage_hostname_warning The origin needs to be set to NET_STORAGE if the hostname is a subdomain of download.akamai.com, upload.akamai.com, or postfile.akamai.com.
no_property_hostname_cachekey You may not use instantConfig when the cacheKeyHostname of the origin is set to REQUEST_HOST_HEADER.
nonce_secret_key_warning The g2oheader behavior’s nonce should be different than its secretKey.
not_compatible You can’t use verifyTokenAuthorization when segmentedContentProtection is enabled.
not_validation_html_warning The constructResponse response body should be valid XHTML.
notallow_ext The downgradeProtocol behavior can’t be enabled by a fileExtension match.
notallow_filename The downgradeProtocol behavior can’t be enabled by a filename match.
notallow_protocol The downgradeProtocol behavior can’t be enabled by a requestProtocol match.
objects_cant_exceed_1mb Objects served with edgeSideIncludes may not be larger than 1MB.
origin_acl_must_be_updated_manually An old origin version specifies a cachekeyhostname of requesthostheader.
origin_acl_must_be_updated_manually_elb An old origin version specifies an elb_origin_group of type.
origin_elb_definition_warning edgeLoadBalancingOrigin doesn’t work unless the origin is set to EDGE_LOAD_BALANCING_ORIGIN_GROUP.
origin_g2o_error You should not use the g2oheader behavior when the origin is set to NET_STORAGE.
origin_netstorage The origin can’t be set to NET_STORAGE if segmentedMediaOptimization is set to stream LIVE.
performance_warning The akamaizer behavior is not recommended for sites that routinely serve more than 100 hits per second.
prefetch The instant behavior is a superset of prefetch, and they are mutually exclusive. Remove either behavior.
prefetching_never_enabled The prefetchable behavior has no effect unless you apply prefetch to the page users access, and which contains links to the prefetchable objects.
prefetching_with_ss The siteShield behavior is incompatible with prefetching.
prune_query_whenns A NET_STORAGE origin server ignores query parameters, so it’s more efficient to disable the rewriteUrl behavior’s keepQueryString option.
receiptdelivery_requires_allow_post Applying deliveryReceipt requires that you enable allowPost.
receiptdelivery_requires_bypass_cache Applying deliveryReceipt requires that you set caching to BYPASS_CACHE.
receiptdelivery_requires_secure deliveryReceipt requires that the property is_secure.
regex_validation_notsecure When siteShield is used in a non-secure property, the domain name of the ssmap must end with .akamai.net.
regex_validation_secure When siteShield is used in a secure property, the domain name of the ssmap must end with .akamaiedge.net.
regex_validation_sureroute The sureRoute behavior’s customMap must be a subdomain of akasrg.akamai.com.
requireakamaizer The savePostDcaProcessing behavior doesn’t work properly unless akamaizer is enabled.
required_mdc_for_saas_cname For a behavior to specify a CNAME chain, the instantConfig behavior must also be enabled, or the property must be secure.
required_negative_caching When your origin is set to NET_STORAGE, set the cacheError with a ttl of at least 30 seconds.
required_third_party_set The origin hostname is AWS, the verificationMode is set to CUSTOM, and originCertsToHonor is set to STANDARD_CERTIFICATE_AUTHORITIES or COMBO, but standardCertificateAuthorities doesn’t include THIRD_PARTY_AMAZON.
requires_caching_enabled To set the cache’s ID, the caching behavior must be enabled.
requires_extension_match The imageManager behavior requires a fileExtension match. ???
requires_hoit_match The http2 and spdy behaviors can only be enabled within a hostname match.
requires_mfro The randomSeek behavior works best when mediaFileRetrievalOptimization is enabled.
requires_nonsecure To apply instantConfig requires a non-secure property.
requires_origin_cacheley_inc_hh You can’t use cacheKeyRewrite when the origin behavior’s cacheKeyHostname is set to REQUEST_HOST_HEADER.
requires_requestmethod_match You can only enable the webdav behavior when matching a requestMethod.
requirescaching When using cachePost, you should also use caching to define a caching strategy.
requirespost The savePostDcaProcessing behavior requires either allowPost or cachePost to be enabled.
requirespostcaching The savePostDcaProcessing behavior requires cachePost to be enabled.
responsecode_conflict The response code defined in constructResponse and responseCode do not match.
saas_origin_hostname_cn When using a SAAS_DYNAMIC_ORIGIN origin, you can’t specify {{Origin Hostname}} in the customValidCnValues.
salt_deprecated The verifyTokenAuthorization behavior’s salt option will be removed in a future release, so you should remove it from your code.
scheduledinvalidation When the origin is NET_STORAGE, the scheduleInvalidation behavior’s repeatInterval must be at least 5 minutes.
secret_key_warning The g2oheader behavior’s secretKey must be at least 10 alphanumeric characters long.
spdy_requires_secure The spdy behavior requires that the property is_secure.
sr_ss_map_mismatch A sureRoute behavior specifies a type of CUSTOM_MAP, and the customMap does not match what is specified by siteShield.
sr_with_ss With siteShield enabled, the optimiziation type for sureRoute should be CUSTOM_MAP.
ss_incompatible The instant behavior is incompatible with siteShield.
ssl_custom_warning_aux_list In an early version of the origin behavior, origin_cert_delete is set to custom.
ssl_custom_warning_expert Due to the security risk, Akamai strongly recommends you consult with your organization’s security expert before configuring the origin SSL certificate verification settings. If you are the security expert and have any questions, contact your account team.
ssl_custom_warning_test_staging If you are changing your origin SSL certificate verification settings, to avoid a service outage Akamai strongly recommends testing on the staging network before activating on production.
ssl_delegate_warning_intro The origin behavior has been enhanced to address the FOSSL exploit.
ssl_delegate_warning_rotate The origin behavior has been enhanced to address the FOSSL exploit.
ssl_warn_warning An older origin version specifies a verificationMode of INSECURE.
subrules_need_condition For allowCloudletsOrigins to work, you need to nest at least one rule with a single cloudletsOrigin criteria.
suggest_edgeredirector Instead of redirect, consider using the edgeRedirector Cloudlet, which allows non-IT staff to manage large numbers of redirects.
sureroute_required When applying instant to content whose caching is NO_STORE, the content must also have sureRoute enabled or it is not prefetched.
tcip_allow_clients_to_set_on The origin is configured to allow clients to set the True-Client-IP header, meaning the IP value sent to the origin may not be the one the client used to connect to the edge server. While this may be useful for testing, it may allow users to bypass IP-based restrictions on your origin server.
tcpoptisdeprecated The tcpOptimization behavior is deprecated, and you should remove it.
td_with_modify_inplace The tieredDistribution behavior can’t be enabled when the largeFileOptimization behavior’s useVersioning is disabled.
td_with_ss The siteShield behavior is incompatible with tieredDistribution because both determine which Akamai servers connect directly to the origin.
third_party_verificationmode Setting the origin’s verificationMode to THIRD_PARTY is incompatible with the specified originType.
tiereddistribution_required When applying instant to cacheable content, it must also have tieredDistribution enabled or it is not prefetched.
unpurgeable Enabling a behavior within a specified criteria prevents Content Control Utility from purging by URL. Contact your Akamai representative for guidance.
urlrewrite_incompatible When using removeQueryParameter, the rewriteUrl behavior’s keepQueryString must also be enabled.
usebody The cachePost behavior specifies a useBody of MD5 or QUERY, but there is no accompanying cacheId.
warn_not_connnectingip When setting denyAccess, disable the match’s useOnlyFirstXForwardedForIp to prevent malicious end users from using X-Forwarded-For headers to bypass the policy.
warn_regex Test any regular expressions you specify in rewriteUrl on the staging network and contact your Akamai representative if you are uncertain how to use this option.
wildcard_match_advised You should enable limitBitRate with a filename, fileExtension, or path match.
with_ignore_case To apply cacheKeyIgnoreCase, you need to lowercase the elements specified by an accompanying cacheId, otherwise they never match.
within_cloudlets_origins_group This Cloudlet behavior may not work as expected when added to the same rule that sets the cloudletsOrigin. Consider moving it to a different rule.

Other errors

The following may appear as standalone 400 errors:

Code Type Problem
400 invalid-rule-format The specified rule format is not supported. Learn more.
400 toolkit/password-needs-rotation The password for the user attached to the given authorization token must be rotated.

The following fallback error may appear when modifying a rule tree:

Type Description
unknown_message Unknown rule tree validation error.

Last modified: 5/24/2017