loading

Property Manager API v1

Use PAPI to manage how Akamai handles requests, objects, and responses for your website.

Learn more:


Overview

The Property Manager API (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. This most recent PAPI release provides bulk update capabilities, allowing you to modify and activate many properties at once.

Getting started

Before using PAPI for the first time:

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

  • If you need to perform bulk search operations across many accounts, there is a different procedure to set up your client token. For details, see Manage many accounts with one API client.

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

  • Once you have a custom domain token, you can gather other prerequisite data used throughout the API: the relevant contract and group to access other PAPI objects, and a product to create new ones. See the API summary for PAPI’s full range of capabilities.

  • Client 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 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!

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 Luna Control Panel. 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.

  • 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.

  • 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.

  • 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 summarized 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.

  • 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.

  • 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 either cancel an activation shortly after requesting it, or in many cases, use a fast fallback feature within a matter of seconds to roll back a live activation to the previous activated version.

  • Metadata. Once activated, each property is distributed to the Akamai network as an XML configuration file known as Akamai metadata. This low-level 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.

  • 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.

  • 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 Rule Trees 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. (See Advanced and locked features.)

  • Custom behaviors. Custom behaviors are read-only, like advanced features, but they’re designed so that you can apply the same customized XML metadata to many properties at a time. (See Custom behaviors and overrides.)

  • Custom overrides. Like custom behaviors, custom overrides offer read-only access to XML metadata. They provide a final postprocessing step that executes at the end of the metadata, useful for restoring state modified within the rule tree.

  • 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.

  • 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.

  • 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.

  • Client settings. This API resource collects various configuration parameters for clients keyed to an authorization token.

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.

  • 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.

  • 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.

This most recent PAPI release supports a set bulk operations to manage many properties’ rule trees at once. See the Bulk Search and Update section for details on this feature.

  • Bulk searches. Bulk searches use a flexible JSON path-based query syntax to search across all your activated property versions’ rule trees. After your search request, search results become available asynchronously for all matching property versions. They include JSON path expressions that locate all the rule tree behaviors and criteria you searched on, for use in a subsequent bulk patch operation.

  • Bulk versions. You feed the results of a bulk search into another operation that creates new versions for the entire set of properties. This new set of versions becomes available asynchronously.

  • Bulk patches. In a bulk patch operation, you use the JSON path locators in conjunction with JSON Patch operators to form a set of customized instructions to modify each property’s rule tree. The results become available asynchronously.

  • Bulk activations. After batch-updating a set of properties, you can asynchronously bulk activate them to the staging or production network.

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, named items, to simplify client processing. This also applies to resources that only yield a single item.

  • Response data is wrapped within a common Envelope object that provides necessary context about the data.

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

  • Member names explicitly reference the type of object, for example propertyVersion rather than version.

PAPI applies the following JSON member naming conventions:

  • *Id members are machine-readable identifiers used for inputs to endpoints. By default, response data features *Id values with three-letter prefixes to help distinguish their function:

    • aid_ for assetId
    • act_ for accountId
    • atv_ for activationId
    • cpc_ for cpcodeId
    • ctr_ for contractId
    • ehn_ for edgeHostnameId
    • grp_ for groupId
    • msg_ for messageId
    • prd_ for productId
    • prp_ for propertyId

    To strip these prefixes and exchange values suitable for use in other Akamai APIs, either:

    • Run Update client settings to set "usePrefixes":false as the default for all requests.

    • Specify PAPI-Use-Prefixes as a boolean request header to override the client’s default setting.

    Regardless of whether you set this header in the request, you can specify these IDs as input parameters or JSON data with or without the prefixes.

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

  • *Date members represent date-time in ISO 8601 format using UTC timezone. The API names all timestamps as *Date, and they all use this same format.

  • *Link members are URLs that respond to HTTP GET requests, described by a linked JSON schema document. (As a convenience, any response that provides a *Link JSON member also provides the same information in the Location HTTP header.) Since API hostnames are client-specific, URLs appear as absolute-path relative reference URLs, for example /papi/v1/properties rather than https://myclient.luna.akamaiapis.net/papi/v1/properties. Clients need to establish the base URL of links from the retrieval URL. The * portion of the name serves as the link relation.

Rate and resource limiting

PAPI imposes various limits on some of the resources you can deploy. In some cases, you may have the option to override these limits. Contact your Akamai representative for more information.

Various responses include HTTP headers that provide details on your current limits:

  • Custom headers suffixed *-Limit report on the overall limit.

  • Corresponding headers suffixed *-Remaining tell you how many items you have left to deploy.

  • For rate-limited activations, an additional *-Reset header lets you know when the current *-Remaining value rises to the original *-Limit value.

The following shows all of the limits PAPI imposes:

Limit Default Value Description
X-Limit-Properties-Per-Contract-Limit 1000 Maximum number of activated property configurations per contract. (Most customers use a single contract.)
X-Limit-Edgehostnames-Per-Contract-Limit 1000 Maximum number of edge hostnames per contract. (Most customers use a single contract.)
X-Limit-Hosts-Per-Property-Limit 1000 Maximum number of hostnames you can assign to a property configuration.
X-Limit-Elements-Per-Property-Limit 1500 Maximum number of separate matches and behaviors per rule tree configuration.
X-Limit-Max-Nested-Rules-Limit 6 Maximum number of nested child rules to apply conditional logic. See Rule trees for details on how nested rules work.
X-Limit-Clientip-Per-Property-Limit 300 Maximum number of separate Client IP matches per rule tree configuration.
X-Limit-Max-Clientip-Per-Match-Limit 10 Maximum number of separate IP addresses allowed within each Client IP match.
X-RateLimit-Activations-Limit 100 Maximum number of PAPI configurations you can activate each day on either staging or production networks.

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 offers 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.

Fast validation, activation, and fallback

PAPI’s most important function is to modify rule trees associated with sets of hostnames, and to activate them on Akamai’s networks of edge servers. 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 shortcuts to accelerate development. One option allows you to defer validation until you are ready:

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 would 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.

Instead of skipping validation when running the Update a rule tree operation, you can also accelerate validation, or run the operation simply to gather errors rather than modify the rule tree. For both of these options, the validateHostnames query parameter must be the default true value:

  • Setting the validateMode query parameter to FAST performs a more superficial JSON syntax check. This focuses on the errors that are more likely during frequent iteration. It skips a lengthier set of execution tests on the converted XML metadata.

  • Alternately, setting the dryRun query parameter to true performs the full validation check, but without saving the rule tree. The response provides any resulting errors and warnings, without committing changes to the rule tree. You can only specify dryRun with validateMode set to the default FULL validation.

Before activating a revised rule tree, you need to fix any errors from a full validation. As part of the activation, you either set the acknowledgeAllWarnings flag or pass in an array of acknowledgeWarnings warning IDs. Activation is much faster if the property’s set of hostnames does not change.

You may also have the option to quickly revert an activation:

  • If you detect a problem with the rule tree within an hour of its activation, POST another activation with useFastFallback set to true. Within a few seconds, it disables the current activation and falls back to the previous version. (Fallback may also occur automatically if the activated metadata fails various execution tests on edge servers.) The fallback option is not available if you have changed the set of property hostnames, or if this is the property’s first activation. When polling the activation’s status, the canFastFallback flag indicates whether fallback is possible.

  • If the fast fallback option is not available as indicated by "canFastFallback":false, you need to separately activate the previous version of the rule tree known not to cause problems.

Contact your Akamai representative for guidance on expected latency, both to validate your property’s rule tree and to activate it worldwide.

Resources

This section describes the workflow through PAPI, providing details on how to interact with each operation.

Before running many other operations, you need a set of contract and group identifiers. Before creating new objects, you also need a relevant product identifier. (See the Contract, Group, and Product interfaces.) With these IDs available, you can access the following interfaces:

  • Use the CP codes interface if you want to generate CP codes, which you assign to a property’s rule tree, or to find out which products existing CP codes are associated with.

  • Use the Edge hostnames interface to deploy new hostnames on Akamai edge servers before assigning them to properties.

  • Use the Properties interface if you want to list available properties or create new properties.

Once you have a property identifier, you can run many operations with no need for contract and group identifiers. You may have the opportunity to design client code to avoid running other operations to derive those values. You may also be able to flexibly change how your properties are provisioned, independent of your client code. With a property identifier available, you can access the following interfaces:

PAPI also provides these additional features:

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

Download the RAML descriptors for this API.

Operation Method Endpoint
Groups  
List groups GET /papi/v1/groups
Contracts  
List contracts GET /papi/v1/contracts
Products  
List products GET /papi/v1/products{?contractId}
CP codes  
List CP codes GET /papi/v1/cpcodes{?contractId,groupId}
Create a new CP code POST /papi/v1/cpcodes{?contractId,groupId}
Get a CP code GET /papi/v1/cpcodes/{cpcodeId}{?contractId,groupId}
Edge hostnames  
List edge hostnames GET /papi/v1/edgehostnames{?contractId,groupId,options}
Create a new edge hostname POST /papi/v1/edgehostnames{?contractId,groupId,options}
Get an edge hostname GET /papi/v1/edgehostnames/{edgeHostnameId}{?contractId,groupId,options}
Properties  
List properties GET /papi/v1/properties{?contractId,groupId}
Create or clone a property POST /papi/v1/properties{?contractId,groupId}
Get a property GET /papi/v1/properties/{propertyId}{?contractId,groupId}
Remove a property DELETE /papi/v1/properties/{propertyId}{?contractId,groupId}
Property versions  
List property versions GET /papi/v1/properties/{propertyId}/versions{?contractId,groupId}
Create a new property version POST /papi/v1/properties/{propertyId}/versions{?contractId,groupId}
Get a version GET /papi/v1/properties/{propertyId}/versions/{propertyVersion}{?contractId,groupId}
List available behaviors GET /papi/v1/properties/{propertyId}/versions/{propertyVersion}/available-behaviors{?contractId,groupId}
List available criteria GET /papi/v1/properties/{propertyId}/versions/{propertyVersion}/available-criteria{?contractId,groupId}
Get the latest version GET /papi/v1/properties/{propertyId}/versions/latest{?activatedOn,contractId,groupId}
Property version hostnames  
List a property’s hostnames GET /papi/v1/properties/{propertyId}/versions/{propertyVersion}/hostnames{?contractId,groupId,validateHostnames}
Update a property’s hostnames PUT /papi/v1/properties/{propertyId}/versions/{propertyVersion}/hostnames{?contractId,groupId,validateHostnames}
Property version rules  
Get a rule tree GET /papi/v1/properties/{propertyId}/versions/{propertyVersion}/rules{?contractId,groupId,validateRules,validateMode}
Update a rule tree PUT /papi/v1/properties/{propertyId}/versions/{propertyVersion}/rules{?contractId,groupId,validateRules,validateMode,dryRun}
Patch a rule tree PATCH /papi/v1/properties/{propertyId}/versions/{propertyVersion}/rules{?contractId,groupId,validateRules,validateMode,dryRun}
Get a rule tree’s digest HEAD /papi/v1/properties/{propertyId}/versions/{propertyVersion}/rules{?contractId,groupId,validateRules,validateMode}
Property activations  
List activations GET /papi/v1/properties/{propertyId}/activations{?contractId,groupId}
Create a new activation or deactivation POST /papi/v1/properties/{propertyId}/activations{?contractId,groupId}
Get an activation GET /papi/v1/properties/{propertyId}/activations/{activationId}{?contractId,groupId}
Cancel a pending activation DELETE /papi/v1/properties/{propertyId}/activations/{activationId}{?contractId,groupId}
Search  
Search properties POST /papi/v1/search/find-by-value
Bulk search  
Bulk search a set of properties POST /papi/v1/bulk/rules-search-requests{?contractId,groupId}
List bulk search results GET /papi/v1/bulk/rules-search-requests/{bulkSearchId}{?contractId,groupId}
Bulk versioning  
Bulk version a set of properties POST /papi/v1/bulk/property-version-creations{?contractId,groupId}
List bulk-versioned properties GET /papi/v1/bulk/property-version-creations/{bulkCreateId}{?contractId,groupId}
Bulk patches  
Bulk patch a set of properties POST /papi/v1/bulk/rules-patch-requests{?contractId,groupId}
List bulk-patched properties GET /papi/v1/bulk/rules-patch-requests/{bulkPatchId}{?contractId,groupId}
Bulk Property Activations  
Bulk activate a set of properties POST /papi/v1/bulk/activations{?contractId,groupId}
List bulk-activated properties GET /papi/v1/bulk/activations/{bulkActivationId}{?contractId,groupId}
Custom behaviors  
List custom behaviors GET /papi/v1/custom-behaviors
Get a custom behavior GET /papi/v1/custom-behaviors/{behaviorId}
Custom overrides  
List custom overrides GET /papi/v1/custom-overrides
Get a custom override GET /papi/v1/custom-overrides/{overrideId}
Rule formats  
List rule formats GET /papi/v1/rule-formats
Schemas  
Get a request’s schema GET /papi/v1/schemas/request/{filename}
Get a rule format’s schema GET /papi/v1/schemas/products/{productId}/{ruleFormat}
Client settings  
Get client settings GET /papi/v1/client-settings
Update client settings PUT /papi/v1/client-settings
Build  
Get build details GET /papi/v1/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/v1/groups

Headers:

PAPI-Use-Prefixes: true

Status 200 application/json

Response Body:

{
    "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/v1/groups.

  2. Select the appropriate Group from the response’s groups.items array.

  3. Store the object’s 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/v1/contracts

Headers:

PAPI-Use-Prefixes: true

Status 200 application/json

Response Body:

{
    "accountId": "act_1-1TJZFB",
    "contracts": {
        "items": [
            {
                "contractId": "ctr_1-1TJZH5",
                "contractTypeName": "Direct Customer"
            }
        ]
    }
}
  1. GET the list of contracts from /papi/v1/contracts.

  2. Select the appropriate Contract from the response’s contracts.items array.

  3. Store the object’s 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/v1/products{?contractId}

Sample: /papi/v1/products?contractId=ctr_1-1TJZFW

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
Required query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. See Data conventions for details on omitting the value’s ctr_ prefix.

Status 200 application/json

Response Body:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "products": {
        "items": [
            {
                "productName": "Alta",
                "productId": "prd_Alta"
            }
        ]
    }
}
  1. Run the List contracts operation and store the relevant contractId.

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

  3. Select the appropriate Product from the response’s products.items array.

  4. Store the object’s 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/v1/cpcodes{?contractId,groupId}

Sample: /papi/v1/cpcodes?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
Required query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. See Data conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Response Body:

{
    "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. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. GET /papi/v1/cpcodes{?contractId,groupId} to list CP codes.

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

  5. Store the object’s 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/v1/cpcodes{?contractId,groupId}

Sample: /papi/v1/cpcodes?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true

Content-Type: application/json

Request Body:

{
    "productId": "prd_Web_App_Accel",
    "cpcodeName": "SME WAA"
}
Parameter Type Sample Description
Required query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. See Data conventions for details on omitting the value’s grp_ prefix.

Status 201 application/json

Headers:

Location: /papi/v1/cpcodes/cpc_33190?contractId=ctr_1-1TJZFW&groupID=grp_15166

Response Body:

{
    "cpcodeLink": "/papi/v1/cpcodes/cpc_33190?contractId=ctr_1-1TJZFW&groupId=grp_15166"
}
  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List products operation and store the relevant productId with which to enable the CP code.

  4. Build a CpCode POST object.

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

  6. Optionally GET the response object’s cpcodeLink or the Location header to access the new CP code.

Get a CP code

This operation gets details about a CP code.

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

Sample: /papi/v1/cpcodes/cpc_33190?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
cpcodeId String cpc_33190 Unique identifier for the CP code. See Data conventions for details on omitting the value’s cpc_ prefix.
Required query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. See Data conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Response Body:

{
    "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. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List CP codes operation and store the relevant cpcodeId.

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

  5. Store the object’s cpcodeId.

List edge hostnames

This lists all edge hostnames available under a contract. To assign any of these hostnames to a property, run Update a property’s hostnames.

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

Sample: /papi/v1/edgehostnames?contractId=ctr_1-1TJZFW&groupId=grp_15166&options=mapDetails

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
Required query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. See Data conventions for details on omitting the value’s grp_ prefix.
Optional query parameters
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 Body:

{
    "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",
                "domainPrefix": "example.com",
                "domainSuffix": "edgesuite.net",
                "secure": false,
                "ipVersionBehavior": "IPV4",
                "mapDetails:serialNumber": 1951,
                "mapDetails:mapDomain": "a1951.g.akamai.net"
            }
        ]
    }
}
  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

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

  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 run Update a property’s hostnames to assign it to a property. After running Create a new activation or deactivation to activate a property, modifying your DNS to map the origin hostname to the edge hostname ultimately enables traffic on the property. See Enable traffic for a new edge hostname for details.

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

Sample: /papi/v1/edgehostnames?contractId=ctr_1-1TJZFW&groupId=grp_15166&options=mapDetails

Headers:

PAPI-Use-Prefixes: true

Content-Type: application/json

Request Body:

{
    "productId": "prd_PPP",
    "domainPrefix": "www.example.com",
    "domainSuffix": "edgesuite.net",
    "secure": true,
    "ipVersionBehavior": "IPV4",
    "slotNumber": 12345
}
Parameter Type Sample Description
Required query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. See Data conventions for details on omitting the value’s grp_ prefix.
Optional query parameters
options String mapDetails Comma-separated list of options to enable; mapDetails enables extra mapping-related information.

Status 201 application/json

Headers:

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

Response Body:

{
    "edgeHostnameLink": "/papi/v1/edgehostnames/ehn_1332?contractId=ctr_1-1TJZH5&grp_15225"
}
  1. Run the List contracts operation and store the relevant contractId.

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

  3. Run the List products operation 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/v1/edgehostnames{?contractId,groupId,options}.

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

Create a secure edge hostname

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, run List edge hostnames in PAPI to confirm their activation 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/v1/edgehostnames/{edgeHostnameId}{?contractId,groupId,options}

Sample: /papi/v1/edgehostnames/ehn_887436?contractId=ctr_1-1TJZFW&groupId=grp_15166&options=mapDetails

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
edgeHostnameId String ehn_887436 Unique identifier for the edge hostname. See Data conventions for details on omitting the value’s ehn_ prefix.
Required query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. See Data conventions for details on omitting the value’s grp_ prefix.
Optional query parameters
options String mapDetails Comma-separated list of options to enable; mapDetails enables extra mapping-related information.

Status 200 application/json

Response Body:

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

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List edge hostnames operation and store the relevant edgeHostnameId.

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

  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/v1/properties{?contractId,groupId}

Sample: /papi/v1/properties?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
Required query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. See Data conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Headers:

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

Response Body:

{
    "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,
                "assetId": "aid_101",
                "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,
                "assetId": "aid_101",
                "note": "Notes about m.example.com"
            }
        ]
    }
}
  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. GET the list of properties from /papi/v1/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/v1/properties{?contractId,groupId}

Sample: /papi/v1/properties?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true

Content-Type: application/json

Request Body:

{
    "productId": "prd_Alta",
    "propertyName": "my.new.property.com",
    "cloneFrom": {
        "propertyId": "prp_175780",
        "version": 2,
        "cloneFromVersionEtag": "a9dfe78cf93090516bde891d009eaf57",
        "copyHostnames": true
    }
}
Parameter Type Sample Description
Required query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. See Data conventions for details on omitting the value’s grp_ prefix.

Status 201 application/json

Headers:

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

Response Body:

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

Gather prerequisites:

  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List products operation and store the relevant productId with which to enable the property.

To create a property from scratch:

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

  2. Build a Property POST object, optionally specifying the rule format.

Alternately, to clone a property:

  1. Run the List properties operation and store the relevant propertyId from the property you want to clone.

  2. Run the List property versions operation 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/v1/properties{?contractId,groupId}.

  2. Optionally GET the response object’s propertyLink or the Location header to access the new property.

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. See Concurrency control for guidance.

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/v1/properties/{propertyId}{?contractId,groupId}

Sample: /papi/v1/properties/prp_175780?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Response Body:

{
    "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,
                "assetId": "aid_101",
                "note": "Notes about example.com"
            }
        ]
    }
}
  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List properties operation and store the relevant propertyId.

  4. GET the property from /papi/v1/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 500 error. Attempting to delete an unknown property results in a 404 error.

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

Sample: /papi/v1/properties/prp_175780?contractId=ctr_1-1TJZFW&groupId=grp_15166

Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Response Body:

{
    "message": "Deletion Successful."
}
  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List properties operation and store the relevant propertyId.

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

List property 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/v1/properties/{propertyId}/versions{?contractId,groupId}

Sample: /papi/v1/properties/prp_175780/versions?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Response Body:

{
    "propertyId": "prp_173136",
    "propertyName": "981.catalog.amenai.net",
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "assetId": "aid_101",
    "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. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List properties operation and store the relevant propertyId.

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

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

Create a new property 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/v1/properties/{propertyId}/versions{?contractId,groupId}

Sample: /papi/v1/properties/prp_175780/versions?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true

Content-Type: application/json

Request Body:

{
    "createFromVersion": 1,
    "createFromVersionEtag": "2641910c585cf67b"
}
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.

Status 201 application/json

Headers:

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

Response Body:

{
    "versionLink": "/papi/v1/properties/prp_173136/versions/2?contractId=ctr_1-1TJZH5&groupId=grp_15225"
}
  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List properties operation and store the relevant propertyId.

  4. Run the List property versions operation and store the relevant version’s propertyVersion.

  5. Build a Version POST object.

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

  7. Optionally GET the response object’s versionLink or the Location header to access the new property version.

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/v1/properties/{propertyId}/versions/{propertyVersion}{?contractId,groupId}

Sample: /papi/v1/properties/prp_175780/versions/3?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
propertyVersion Integer 3 Property’s incremental version number.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Headers:

Etag: "71573b922a87abc3"

Response Body:

{
    "propertyId": "prp_173136",
    "propertyName": "981.catalog.amenai.net",
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "assetId": "aid_101",
    "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

Headers:

Etag: "71573b922a87abc3"

Response Body:

 <?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. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List products operation and store the relevant productId with which to enable the property.

  4. Run the List properties operation and store the relevant propertyId.

  5. Run the List property versions operation and store the relevant propertyVersion.

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

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

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

List available behaviors

Lists the set of 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.

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

Sample: /papi/v1/properties/prp_175780/versions/3/available-behaviors?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
propertyVersion Integer 3 Property’s incremental version number.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Response Body:

{
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "productId": "prd_Alta",
    "ruleFormat": "v2015-08-08",
    "availableBehaviors": {
        "items": [
            {
                "name": "cpCode",
                "schemaLink": "/papi/v1/schemas/products/prd_Alta/latest#/definitions/catalog/behaviors/cpCode"
            },
            {
                "name": "origin",
                "schemaLink": "/papi/v1/schemas/products/prd_Alta/latest#/definitions/catalog/behaviors/origin"
            }
        ]
    }
}
  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List properties operation and store the relevant propertyId.

  4. Run the List property versions operation and store the relevant version’s propertyVersion.

  5. GET the list of behaviors from /papi/v1/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.

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.

List available criteria

Lists the set of 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.

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

Sample: /papi/v1/properties/prp_175780/versions/3/available-criteria?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
propertyVersion Integer 3 Property’s incremental version number.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Response Body:

{
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "productId": "prd_Alta",
    "ruleFormat": "v2015-08-08",
    "availableCriteria": {
        "items": [
            {
                "name": "fileExtension",
                "schemaLink": "/papi/v1/schemas/products/prd_Alta/latest#/definitions/catalog/criteria/fileExtension"
            },
            {
                "name": "hostname",
                "schemaLink": "/papi/v1/schemas/products/prd_Alta/latest#/definitions/catalog/criteria/hostname"
            }
        ]
    }
}
  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List properties operation and store the relevant propertyId.

  4. Run the List property versions operation and store the relevant version’s propertyVersion.

  5. GET the list of criteria from /papi/v1/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.

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 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/v1/properties/{propertyId}/versions/latest{?activatedOn,contractId,groupId}

Sample: /papi/v1/properties/prp_175780/versions/latest?activatedOn=STAGING&contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
Optional query parameters
activatedOn Enumeration STAGING If present, returns the latest version activated on the given network, either STAGING or PRODUCTION.
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.

Status 302 application/json

Headers:

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

Response Body:

{
    "versionLink": "/papi/v1/properties/prp_173136/versions/2?contractId=ctr_1-1TJZH5&groupId=grp_15225"
}
  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List products operation and store the relevant productId with which to enable the property.

  4. Run the List properties operation 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/v1/properties/{propertyId}/versions/latest{?contractId,groupId,activatedOn}.

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

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/v1/properties/{propertyId}/versions/{propertyVersion}/hostnames{?contractId,groupId,validateHostnames}

Sample: /papi/v1/properties/prp_175780/versions/3/hostnames?contractId=ctr_1-1TJZFW&groupId=grp_15166&validateHostnames=true

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
propertyVersion Integer 3 Property’s incremental version number.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.
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 Fast validation, activation, and fallback for details on the delays this might avoid.

Status 200 application/json

Headers:

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

Response Body:

{
    "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. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List properties operation and store the relevant propertyId.

  4. Run the List property versions operation and store the relevant version’s propertyVersion.

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

  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.

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

Sample: /papi/v1/properties/prp_175780/versions/3/hostnames?contractId=ctr_1-1TJZFW&groupId=grp_15166&validateHostnames=true

Headers:

PAPI-Use-Prefixes: true
If-Match: "6aed418629b4e5c0"

Content-Type: application/json

Request Body:

[
    {
        "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
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
propertyVersion Integer 3 Property’s incremental version number.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.
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 Fast validation, activation, and fallback 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 Body:

{
    "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. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Optionally run List edge hostnames and collect any relevant edgeHostnameId values to assign.

  4. Run the List properties operation and store the relevant propertyId.

  5. Run the List property versions operation and store the relevant version’s propertyVersion and etag.

  6. Run List a 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 Fast validation, activation, and fallback for guidance.

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

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 Fast validation, activation, and fallback for guidance on when to defer validation. See JSON problems for information on how validation data is embedded within the response object.

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.

GET /papi/v1/properties/{propertyId}/versions/{propertyVersion}/rules{?contractId,groupId,validateRules,validateMode}

Sample: /papi/v1/properties/prp_175780/versions/3/rules?contractId=ctr_1-1TJZFW&groupId=grp_15166&validateRules=true&validateMode=fast

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
propertyVersion Integer 3 Property’s incremental version number.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.
validateMode Enumeration fast With validateRules enabled, setting this to fast performs a quick validation check based on the provided JSON. This is faster than the default full validation, which performs more extensive checks on the converted XML metadata configuration.
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 JSON problems section for details on this error feedback. See Fast validation, activation, and fallback for details on the delays this might avoid.

Status 200 application/json

Headers:

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

Response Body:

{
    "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": {
                    "httpPort": 80,
                    "enableTrueClientIp": false,
                    "compress": true,
                    "cacheKeyHostname": "ORIGIN_HOSTNAME",
                    "forwardHostHeader": "REQUEST_HOST_HEADER",
                    "hostname": "origin.test.com",
                    "originType": "CUSTOMER"
                }
            },
            {
                "name": "cpCode",
                "options": {
                    "value": {
                        "id": 12345,
                        "name": "my CP code"
                    }
                }
            }
        ],
        "children": []
    }
}

This procedure simply gets a rule tree. To increment its rule format, see Update rules to a newer set of features.

  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List properties operation and store the relevant propertyId.

  4. Run the List property versions operation and store the relevant version’s propertyVersion.

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

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.

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 Fast validation and activation for guidance on when to defer validation. See JSON problems for information on how validation data is embedded within the response object.

PUT /papi/v1/properties/{propertyId}/versions/{propertyVersion}/rules{?contractId,groupId,validateRules,validateMode,dryRun}

Sample: /papi/v1/properties/prp_175780/versions/3/rules?contractId=ctr_1-1TJZFW&groupId=grp_15166&validateRules=true&validateMode=fast&dryRun=true

Headers:

PAPI-Use-Prefixes: true
If-Match: "a9dfe78cf93090516bde891d009eaf57"

Content-Type: application/json

Request Body:

{
    "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
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
propertyVersion Integer 3 Property’s incremental version number.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
dryRun Boolean true With validateRules also enabled, allows for a dry run in order to gather any possible errors without saving the rule tree.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.
validateMode Enumeration fast With validateRules enabled, setting this to fast performs a quick validation check based on the provided JSON. This is faster than the default full validation, which performs more extensive checks on the converted XML metadata configuration.
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 JSON problems section for details on this error feedback. See Fast validation, activation, and fallback for details on the delays this might avoid.

Status 200 application/json

Headers:

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

Response Body:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_173136",
    "propertyVersion": 3,
    "etag": "a9dfe78cf93090516bde891d009eaf57",
    "errors": [
        {
            "type": "/papi/v1/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/v1/properties/prp_173136/versions/3/rules#err_100",
            "behaviorName": "cpCode"
        },
        {
            "type": "/papi/v1/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/v1/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.

  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List properties operation and store the relevant propertyId.

  4. Run the List property versions operation 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 Fast validation, activation, and fallback for guidance.

  8. PUT the object to /papi/v1/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: 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. Run Get a 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. Run List 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.

Patch a rule tree

Selectively modify a rule tree using JSON patch syntax. As a component of the larger Bulk patch a set of properties, this operation patches an individual rule tree. See Bulk Search and Update for more information.

To bypass a set of validation tests that may significantly slow this operation’s execution time, set the validateRules query parameter to false or validateMode to fast. See Fast validation, activation, and fallback for more information.

PATCH /papi/v1/properties/{propertyId}/versions/{propertyVersion}/rules{?contractId,groupId,validateRules,validateMode,dryRun}

Sample: /papi/v1/properties/prp_175780/versions/3/rules?contractId=ctr_1-1TJZFW&groupId=grp_15166&validateRules=true&validateMode=fast&dryRun=true

Headers:

If-Match: "a9dfe78cf93090516bde891d009eaf57"
PAPI-Use-Prefixes: false

Content-Type: application/json-patch+json

Request Body:

[
    {
        "op": "replace",
        "path": "/rules/options/is_secure",
        "value": true
    },
    {
        "op": "replace",
        "path": "/rules/children/0/name",
        "value": "Handle /my-path"
    }
]
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
propertyVersion Integer 3 Property’s incremental version number.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
dryRun Boolean true With validateRules also enabled, allows for a dry run in order to gather any possible errors without saving the rule tree.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.
validateMode Enumeration fast With validateRules enabled, setting this to fast performs a quick validation check based on the provided JSON. This is faster than the default full validation, which performs more extensive checks on the converted XML metadata configuration.
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 JSON problems section for details on this error feedback. See Fast validation, activation, and fallback for details on the delays this might avoid.

Status 200 application/json

Headers:

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

Response Body:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_173136",
    "propertyVersion": 3,
    "etag": "a9dfe78cf93090516bde891d009eaf57",
    "errors": [
        {
            "type": "/papi/v1/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/v1/properties/prp_173136/versions/3/rules#err_100",
            "behaviorName": "cpCode"
        },
        {
            "type": "/papi/v1/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/v1/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"
                    }
                ]
            }
        ]
    }
}
  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List properties operation and store the relevant propertyId.

  4. Run the List property versions operation and store the relevant version’s propertyVersion.

  5. Optionally get the existing rule tree object to determine the set of nodes you want to patch, and to form JSON Pointer expressions to locate them.

  6. Form a JSON patch array for the request. Each object in the array specifies a replacement value for each path location, and an op of replace. Make sure the replacement value matches the data type you are modifying, or the patch fails.

  7. Optionally set the validateRules query parameter to false if you don’t want to perform any validation tests on the rule tree. See Fast validation, activation, and fallback for guidance.

  8. Otherwise optionally set validateRules=true and validateMode=fast to perform a quick schema validation, skipping longer-running XML metadata validation.

  9. Optionally set validateRules=true, validateMode=full, and dryRun=true to leave the rule tree unmodified, in order to view any errors or warnings that would have resulted from the patches.

  10. Include the JSON patch array as the body of a PATCH request to /papi/v1/properties/{propertyId}/versions/{propertyVersion}/rules{?contractId,groupId,validateRules}.

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/v1/properties/{propertyId}/versions/{propertyVersion}/rules{?contractId,groupId,validateRules,validateMode}

Sample: /papi/v1/properties/prp_175780/versions/3/rules?contractId=ctr_1-1TJZFW&groupId=grp_15166&validateRules=true&validateMode=fast

Headers:

Accept: application/vnd.akamai.papirules.latest+json
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
propertyVersion Integer 3 Property’s incremental version number.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.
validateMode Enumeration fast With validateRules enabled, setting this to fast performs a quick validation check based on the provided JSON. This is faster than the default full validation, which performs more extensive checks on the converted XML metadata configuration.
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 JSON problems section for details on this error feedback. See Fast validation, activation, and fallback for details on the delays this might avoid.

Status 204

Headers:

Etag: "a9dfe78cf93090516bde891d009eaf57"
  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List properties operation and store the relevant propertyId.

  4. Run the List property versions operation and store the relevant version’s propertyVersion.

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

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

List activations

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

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

Sample: /papi/v1/properties/prp_175780/activations?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Response Body:

{
    "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"
                ],
                "fmaActivationState": "steady",
                "fallbackInfo": {
                    "fastFallbackAttempted": false,
                    "fallbackVersion": 10,
                    "canFastFallback": true,
                    "steadyStateTime": 1506448172,
                    "fastFallbackExpirationTime": 1506451772,
                    "fastFallbackRecoveryState": null
                }
            }
        ]
    }
}
  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List properties operation and store the relevant propertyId.

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

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

Create a new activation or deactivation

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 there is a problem with the property you activated, you may have the option to fall back to the previous version. Within an hour of activating, POSTing another activation with "useFastFallback":true in the request object disables the current activation and falls back to the previous version. This fallback takes a few seconds, but the option is available only if there have been no changes to the set of property hostnames, as indicated by the canFastFallback member.

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

Sample: /papi/v1/properties/prp_175780/activations?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true

Content-Type: application/json

Request Body:

{
    "propertyVersion": 1,
    "network": "STAGING",
    "note": "Sample activation",
    "notifyEmails": [
        "you@example.com",
        "them@example.com"
    ],
    "acknowledgeWarnings": [
        "msg_baa4560881774a45b5fd25f5b1eab021d7c40b4f"
    ],
    "useFastFallback": false
}
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
Optional query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. (In other operations that don’t specify a propertyId URL parameter, this parameter is always required.) See Data conventions for details on omitting the value’s grp_ prefix.

Status 201 application/json

Response Body:

{
    "activationLink": "/papi/v1/properties/prp_173136/activations/atv_67037?contractId=ctr_1-1TJZFB&groupId=grp_15225"
}
  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List properties operation 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/v1/properties/{propertyId}/activations{?contractId,groupId}.

  7. Optionally GET the response object’s activationLink or the Location header to poll the new activation’s deployment status.

If the activation request produces warnings, a 400 response indicates this problem message: {"type": "/papi/v1/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.

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/v1/properties/{propertyId}/activations/{activationId}{?contractId,groupId}

Sample: /papi/v1/properties/prp_175780/activations/atv_1696855?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
activationId String atv_1696855 Unique identifier for the activation.
Required query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. See Data conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Headers:

Retry-After: 600

Response Body:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-CONTRACT",
    "groupId": "grp_15225",
    "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"
                ],
                "fmaActivationState": "steady",
                "fallbackInfo": {
                    "fastFallbackAttempted": false,
                    "fallbackVersion": 10,
                    "canFastFallback": true,
                    "steadyStateTime": 1506448172,
                    "fastFallbackExpirationTime": 1506451772,
                    "fastFallbackRecoveryState": null
                }
            }
        ]
    }
}
  1. Run the List contracts operation and store the relevant contractId.

  2. Run the List groups operation and store the relevant groupId.

  3. Run the List properties operation and store the relevant propertyId.

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

  5. GET the activation from /papi/v1/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.

If there are unexpected problems with an activation that goes live before you are able to cancel it, you often have a one-hour window to quickly fall back to a previous activation. See Create a new activation or deactivation for details.

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

Sample: /papi/v1/properties/prp_175780/activations/atv_1696855?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
propertyId String prp_175780 Unique identifier for the property. See Data conventions for details on omitting the value’s prp_ prefix.
activationId String atv_1696855 Unique identifier for the activation.
Required query parameters
contractId String ctr_1-1TJZFW Unique identifier for the contract. See Data conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group. See Data conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Response Body:

{
    "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"
            }
        ]
    }
}

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.

Search properties

This operation searches properties by name, or by the hostname or edge hostname for which it is currently active. Specify a Search request object with a single query member. The response lists the matching set of currently active property versions, and also the latest version if inactive. 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. Note that to perform more complex searches for content within a rule tree, run Bulk search a set of properties instead.

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

Headers:

PAPI-Use-Prefixes: true

Content-Type: application/json

Request Body:

{
    "propertyName": "www.example.com_pm"
}

Status 200 application/json

Response Body:

{
    "versions": {
        "items": [
            {
                "accountId": "act_1-1TJZFB",
                "assetId": "aid_10333526",
                "contractId": "ctr_1-1TJZH5",
                "groupId": "grp_41443",
                "productionStatus": "INACTIVE",
                "propertyId": "prp_243865",
                "propertyName": "fifi2",
                "propertyVersion": 6,
                "stagingStatus": "INACTIVE",
                "updatedByUser": "dfknmimouc3ssovc",
                "updatedDate": "2017-08-07T15:39:49Z"
            },
            {
                "accountId": "act_1-1TJZFB",
                "assetId": "aid_10333526",
                "contractId": "ctr_1-1TJZH5",
                "groupId": "grp_41443",
                "productionStatus": "ACTIVE",
                "propertyId": "prp_243865",
                "propertyName": "fifi2",
                "propertyVersion": 1,
                "stagingStatus": "INACTIVE",
                "updatedByUser": "mvanhorn",
                "updatedDate": "2015-06-27T20:37:16Z"
            }
        ]
    }
}

Bulk search a set of properties

POST a BulkSearch object to search across all active property versions, specifying a JSONPath expression to match their rule trees. This operation launches an asynchronous process to gather search results. To check its progress, run the List bulk search results operation, whose link is available in the Location header or the bulkSearchLink member of this operation’s response. After gathering results, you can create new property versions, bulk patch the rule trees, then activate them. See Bulk Search and Update for guidance on this feature. Note that to perform simpler searches for a property’s name or hostnames to which it applies, run the Search properties operation instead.

POST /papi/v1/bulk/rules-search-requests{?contractId,groupId}

Sample: /papi/v1/bulk/rules-search-requests?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: false

Content-Type: application/json

Request Body:

{
    "bulkSearchQuery": {
        "syntax": "JSONPATH",
        "match": "$..conditions[?(@.name == \"ext\" && \"mp3\" in @.options.value && \"mp4\" nin @.options.value)].options.value[?(@ == \"mp3\")]",
        "bulkSearchQualifiers": [
            "$.options[?(@.secure==\"true\")]",
            "$..features[?(@.name==\"origin\")].options[?(@.hostname==\"old.origin.example.com\")]"
        ]
    }
}
Parameter Type Sample Description
Optional query parameters
contractId String ctr_1-1TJZFW Optionally filters bulk searches to properties provisioned under the specified contract. For bulk operations, you can specify contractId and groupId independently from each other.
groupId String grp_15166 Optionally filters bulk searches to properties provisioned under the specified group. For bulk operations, you can specify contractId and groupId independently from each other.

Status 202 application/json

Headers:

Location: /papi/v1/bulk/rules-search-requests?contractId=ctr_1-1TJZH5&groupId=grp_15225

Response Body:

{
    "bulkSearchLink": "/papi/v1/bulk/rules-search-requests/737"
}

Bulk searches are typically followed by other operations to bulk version, patch, and activate properties. You need to be familiar with JSONPath and JSON patch tools. See Bulk Search and Update for details on the full procedure.

List bulk search results

List all property versions that result from a bulk search request. Run this operation to poll the asynchronous process’s status. The response is a BulkSearch GET object. Once the searchTargetStatus is COMPLETE, you can feed the results into a bulk versioning operation. Also use the JSON path matchLocations to run a bulk patch operation over the rule trees. See Bulk Search and Update for guidance.

GET /papi/v1/bulk/rules-search-requests/{bulkSearchId}{?contractId,groupId}

Sample: /papi/v1/bulk/rules-search-requests/5?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
bulkSearchId Integer 5 Identifies each bulk search job.
Optional query parameters
contractId String ctr_1-1TJZFW Optionally filters bulk searches to properties provisioned under the specified contract. For bulk operations, you can specify contractId and groupId independently from each other.
groupId String grp_15166 Optionally filters bulk searches to properties provisioned under the specified group. For bulk operations, you can specify contractId and groupId independently from each other.

Status 200 application/json

Response Body:

{
    "bulkSearchId": 5,
    "searchTargetStatus": "COMPLETE",
    "searchSubmitDate": "2018-01-18T00:00:00Z",
    "searchUpdateDate": "2018-01-18T00:01:00Z",
    "bulkSearchQuery": {
        "syntax": "JSONPATH",
        "match": "$..conditions[?(@.name == \"ext\" && \"mp3\" in @.options.value && \"mp4\" nin @.options.value)].options.value[?(@ == \"mp3\")]",
        "bulkSearchQualifiers": [
            "$.options[?(@.secure==\"true\")]",
            "$..features[?(@.name==\"origin\")].options[?(@.hostname==\"old.origin.example.com\")]"
        ]
    },
    "results": [
        {
            "propertyId": "prp_1",
            "propertyVersion": 1,
            "propertyName": "example1.example.com",
            "stagingStatus": "ACTIVE",
            "productionStatus": "INACTIVE",
            "isLatest": true,
            "isLocked": true,
            "isSecure": true,
            "accountId": "1-abcdef",
            "matchLocations": [
                "/rules/children/1/features/0",
                "/rules/children/1/features/3"
            ],
            "lastModifiedTime": "2018-01-18T00:00:00Z"
        },
        {
            "propertyId": "prp_15",
            "propertyVersion": 2,
            "propertyName": "example2.example.com",
            "stagingStatus": "INACTIVE",
            "productionStatus": "INACTIVE",
            "isLatest": false,
            "isLocked": false,
            "isSecure": true,
            "accountId": "1-abcdef",
            "matchLocations": [
                "/rules/children/1/children/0/features/1"
            ],
            "lastModifiedTime": "2018-01-18T00:00:00Z"
        },
        {
            "propertyId": "prp_3",
            "propertyVersion": 10,
            "propertyName": "example3.example.com",
            "stagingStatus": "INACTIVE",
            "productionStatus": "ACTIVE",
            "isLatest": true,
            "isLocked": true,
            "isSecure": true,
            "accountId": "1-abcdef",
            "matchLocations": [
                "/rules/children/0/children/1/children/2/features/1"
            ],
            "lastModifiedTime": "2018-01-18T00:00:00Z"
        }
    ]
}

To perform bulk searches, you typically run a series of four pairs of POST and GET operations to feed results into a bulk update, and need to be familiar with JSONPath and JSON patch tools. See Bulk Search and Update for details on the full procedure.

Bulk version a set of properties

POST a BulkVersion object to create new versions of a set of properties based on any previous version. This operation launches an asynchronous process to increment versions. To check its progress, run the List bulk-versioned properties operation, whose link is available in the Location header or bulkCreateVersionLink member of this operation’s response. Run this operation only after bulk searching a set of properties you want to change, to prepare new versions to bulk patch. See Bulk Search and Update for guidance on this feature.

POST /papi/v1/bulk/property-version-creations{?contractId,groupId}

Sample: /papi/v1/bulk/property-version-creations?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: false

Content-Type: application/json

Request Body:

{
    "createPropertyVersions": [
        {
            "propertyId": "prp_1",
            "createFromVersion": 1,
            "createFromVersionEtag": "2641910c585cf67b"
        },
        {
            "propertyId": "prp_15",
            "createFromVersion": 2,
            "createFromVersionEtag": "343410c585cf67fc"
        },
        {
            "propertyId": "prp_3",
            "createFromVersion": 10,
            "createFromVersionEtag": "6c7v5c65c6cvcv65"
        }
    ]
}
Parameter Type Sample Description
Optional query parameters
contractId String ctr_1-1TJZFW Optionally filters bulk searches to properties provisioned under the specified contract. For bulk operations, you can specify contractId and groupId independently from each other.
groupId String grp_15166 Optionally filters bulk searches to properties provisioned under the specified group. For bulk operations, you can specify contractId and groupId independently from each other.

Status 202 application/json

Headers:

Location: /papi/v1/bulk/property-version-creations/737?contractId=ctr_1-1TJZH5&groupId=grp_15225

Response Body:

{
    "bulkCreateVersionLink": "/papi/v1/bulk/property-version-creations/737"
}

To perform bulk versioning, you need to run a series of four pairs of POST and GET operations, and need to be familiar with JSONPath and JSON patch tools. See Bulk Search and Update for details on the full procedure.

List bulk-versioned properties

List all new property versions that result from a bulk versioning request, and poll the asynchronous process’s status. The response is a BulkVersion GET object. After the bulkCreateVersionsStatus is COMPLETE, use the new version numbers along with search paths from a bulk search operation to bulk patch them. See Bulk Search and Update for guidance.

GET /papi/v1/bulk/property-version-creations/{bulkCreateId}{?contractId,groupId}

Sample: /papi/v1/bulk/property-version-creations/9?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
bulkCreateId Integer 9 Identifies each bulk-versioning job.
Optional query parameters
contractId String ctr_1-1TJZFW Optionally filters bulk searches to properties provisioned under the specified contract. For bulk operations, you can specify contractId and groupId independently from each other.
groupId String grp_15166 Optionally filters bulk searches to properties provisioned under the specified group. For bulk operations, you can specify contractId and groupId independently from each other.

Status 200 application/json

Response Body:

{
    "bulkCreateId": 9,
    "bulkCreateVersionsStatus": "IN_PROGRESS",
    "bulkCreateVersionSubmitDate": "2018-01-18T00:00:00Z",
    "bulkCreateVersionUpdateDate": "2018-01-18T00:00:00Z",
    "createPropertyVersions": [
        {
            "propertyId": "prp_1",
            "createFromVersion": 1,
            "createFromVersionEtag": "343410c585cf67fb",
            "propertyVersion": 2,
            "createVersionStatus": "PENDING",
            "createVersionSubmitDate": "2018-01-18T00:00:00Z",
            "createVersionUpdateDate": "2018-01-18T00:00:00Z"
        },
        {
            "propertyId": "prp_15",
            "createFromVersion": 2,
            "createFromVersionEtag": "343410c585cf67fc",
            "propertyVersion": 3,
            "createVersionStatus": "IN_PROGRESS",
            "versionLink": null,
            "createVersionSubmitDate": "2018-01-18T00:00:00Z",
            "createVersionUpdateDate": "2018-01-18T00:00:00Z"
        },
        {
            "propertyId": "prp_3",
            "createFromVersion": 10,
            "createFromVersionEtag": "6c7v5c65c6cvcv65",
            "propertyVersion": 11,
            "createVersionStatus": "COMPLETE",
            "versionLink": "/papi/v1/properties/prp_3/versions/11?contractId=ctr_1-TJZFW&groupId=grp_15166",
            "createVersionSubmitDate": "2018-01-18T00:00:00Z",
            "createVersionUpdateDate": "2018-01-18T00:00:00Z"
        }
    ]
}

To perform bulk versioning, you need to run a series of four pairs of POST and GET operations, and need to be familiar with JSONPath and JSON patch tools. See Bulk Search and Update for details on the full procedure.

Bulk patch a set of properties

Apply a series of JSON Patch operations to modify a set of property versions. Form this set of patches based on the JSONPath locations from a bulk search response. Specify a set of new property versions based on the results of a bulk versioning operation. The request is a BulkPatch POST object. This operation launches an asynchronous process to update rule trees. To check its progress, run the List bulk-updated properties operation, whose link is available in the Location header or bulkPatchLink member of this operation’s response. See Bulk Search and Update for overall guidance on this feature.

POST /papi/v1/bulk/rules-patch-requests{?contractId,groupId}

Sample: /papi/v1/bulk/rules-patch-requests?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: false

Content-Type: application/json

Request Body:

{
    "patchPropertyVersions": [
        {
            "propertyId": "prp_1",
            "propertyVersion": 1,
            "patches": [
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/1/features/3/option/enabled"
                },
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/1/features/0/option/enabled"
                }
            ],
            "etag": "a87v5c65c6821bc"
        },
        {
            "propertyId": "prp_15",
            "propertyVersion": 2,
            "patches": [
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/1/children/0/features/1/enabled"
                }
            ],
            "etag": "6c7v5c65c6cvcv65"
        },
        {
            "propertyId": "prp_3",
            "propertyVersion": 10,
            "patches": [
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/0/children/1/children/2/features/1/enabled"
                }
            ],
            "etag": "1f8903bcde2f3"
        }
    ]
}
Parameter Type Sample Description
Optional query parameters
contractId String ctr_1-1TJZFW Optionally filters bulk searches to properties provisioned under the specified contract. For bulk operations, you can specify contractId and groupId independently from each other.
groupId String grp_15166 Optionally filters bulk searches to properties provisioned under the specified group. For bulk operations, you can specify contractId and groupId independently from each other.

Status 202 application/json

Headers:

Location: /papi/v1/bulk/rules-patch-requests?contractId=ctr_1-1TJZH5&groupId=grp_15225

Response Body:

{
    "bulkPatchLink": "/papi/v1/bulk/rules-patch-requests/42"
}

To bulk patch properties, you need to run a series of four pairs of POST and GET operations, and need to be familiar with JSONPath and JSON patch tools. See Bulk Search and Update for details on the full procedure.

List bulk-patched properties

List all modified property versions that result from a bulk patch request, and poll the asynchronous process’s status. The response is a BulkPatch object. Once the overall bulkPatchStatus is COMPLETE, you can feed all successfully updated property versions whose status is UPDATED into a subsequent request to bulk activate them. See Bulk Search and Update for overall guidance on this feature.

GET /papi/v1/bulk/rules-patch-requests/{bulkPatchId}{?contractId,groupId}

Sample: /papi/v1/bulk/rules-patch-requests/7?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
bulkPatchId Integer 7 Identifies each bulk patch job.
Optional query parameters
contractId String ctr_1-1TJZFW Optionally filters bulk searches to properties provisioned under the specified contract. For bulk operations, you can specify contractId and groupId independently from each other.
groupId String grp_15166 Optionally filters bulk searches to properties provisioned under the specified group. For bulk operations, you can specify contractId and groupId independently from each other.

Status 200 application/json

Response Body:

{
    "bulkPatchId": 7,
    "bulkPatchStatus": "COMPLETE",
    "bulkPatchSubmitDate": "2018-01-18T00:00:00Z",
    "bulkPatchUpdateDate": "2018-01-18T01:00:00Z",
    "patchPropertyVersions": [
        {
            "patchPropertyId": "prp_1",
            "patchPropertyVersion": 2,
            "patches": [
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/1/features/3/option/enabled"
                },
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/1/features/0/option/enabled"
                }
            ],
            "patchPropertyVersionStatus": "COMPLETE",
            "patchSubmitDate": "2018-01-18T00:00:00Z",
            "patchUpdateDate": "2018-01-18T00:00:00Z",
            "etag": "etag etag etag",
            "propertyVersionRulesLink": "/papi/v1/properties/prp_1/versions/1/rules",
            "papiErrors": [
                {
                    "type": "https://problems.luna.akamaiapis.net/papi/v1/validation/attribute_required",
                    "title": "Attribute not specified",
                    "detail": "The Verification Settings option on the `Origin Server` behavior is required.",
                    "instance": "https://control.sqa2.qa.akamai.com/papi/v1/bulk/activations/1?contractId=ctr_1-1TJZH5&groupId=grp_15225#853080b7-e411-432d-99ae-967e56b50d72",
                    "errorLocation": "#/rules/behaviors/0/options/verificationMode"
                }
            ],
            "papiWarnings": [
                {
                    "type": "https://problems.luna.akamaiapis.net/papi/v1/validation/product_behavior_issue.cpcode_incorrect_product",
                    "title": "Unstable rule format",
                    "detail": "The CP Code within `Content Provider Code` is not configured for use with the product used by this property, Dynamic Site Accelerator. Traffic for this property might not show up under the correct traffic reports.",
                    "instance": "https://control.sqa2.qa.akamai.com/papi/v1/bulk/activations/1?contractId=ctr_1-1TJZH5&groupId=grp_15225#853080b7-e411-432d-99ae-967e56b50d72",
                    "errorLocation": "#/rules/behaviors/1/options/value"
                }
            ]
        },
        {
            "patchPropertyId": "prp_15",
            "patchPropertyVersion": 3,
            "patches": [
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/1/children/0/features/1/enabled"
                }
            ],
            "patchPropertyVersionStatus": "SUBMISSION_ERROR",
            "patchSubmitDate": "2018-01-18T00:00:00Z",
            "patchUpdateDate": "2018-01-18T00:00:00Z",
            "fatalError": "BAD SYNTAX UNABLE TO SAVE"
        },
        {
            "patchPropertyId": "prp_3",
            "patchPropertyVersion": 11,
            "patches": [
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/0/children/1/children/2/features/1/enabled"
                }
            ],
            "patchPropertyVersionStatus": "COMPLETE",
            "patchSubmitDate": "2018-01-18T00:00:00Z",
            "patchUpdateDate": "2018-01-18T00:00:00Z",
            "etag": "etag etag etag",
            "propertyVersionRulesLink": "/papi/v1/properties/prp_3/versions/1/rules"
        }
    ]
}

To bulk patch properties, you need to run a series of four pairs of POST and GET operations, and need to be familiar with JSONPath and JSON patch tools. See Bulk Search and Update for details on the full procedure.

Bulk activate a set of properties

Bulk activate a set of property versions. (Alternately, perform a bulk fallback to the previous activation within an hour of the previous bulk activation.) Base the set of versions to activate on the results of a bulk patch operation, which you use to create a BulkActivation POST object. This operation launches an asynchronous process to update properties. To check its progress, run the List bulk-activated properties operation, whose link is available in the Location header or bulkActivationLink member of this operation’s response. See Bulk Search and Update for overall guidance on this feature.

POST /papi/v1/bulk/activations{?contractId,groupId}

Sample: /papi/v1/bulk/activations?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true

Content-Type: application/json

Request Body:

{
    "defaultActivationSettings": {
        "notifyEmails": [
            "you@example.com",
            "them@example.com"
        ],
        "acknowledgeAllWarnings": true,
        "useFastFallback": false,
        "fastPush": true
    },
    "activatePropertyVersions": [
        {
            "propertyId": "prp_1",
            "propertyVersion": 2,
            "network": "STAGING",
            "activateFromEtag": "93090516bde891d00923464",
            "note": "Some activation note"
        },
        {
            "propertyId": "prp_15",
            "propertyVersion": 3,
            "notifyEmails": [
                "someoneElse@somewhere.com"
            ],
            "network": "STAGING",
            "activateFromEtag": "a9dfe78cf93090516bde891d009eaf57",
            "note": "Sample activation"
        },
        {
            "propertyId": "prp_3",
            "propertyVersion": 11,
            "network": "PRODUCTION",
            "acknowledgeAllWarnings": false,
            "activateFromEtag": "e891d234009eaf57",
            "note": "created by xyz"
        }
    ]
}
Parameter Type Sample Description
Optional query parameters
contractId String ctr_1-1TJZFW Optionally filters bulk searches to properties provisioned under the specified contract. For bulk operations, you can specify contractId and groupId independently from each other.
groupId String grp_15166 Optionally filters bulk searches to properties provisioned under the specified group. For bulk operations, you can specify contractId and groupId independently from each other.

Status 202 application/json

Response Body:

{
    "bulkActivationLink": "/papi/v1/bulk/activations/311?contractId=ctr_1-1TJZFB&groupId=grp_15225"
}

To perform bulk activations, you need to run a series of four pairs of POST and GET operations, and need to be familiar with JSONPath and JSON patch tools. See Bulk Search and Update for details on the full procedure.

List bulk-activated properties

List all activations that result from a bulk activation request, and poll the asynchronous process’s status. Once the overall bulkActivationStatus is COMPLETE, check each activation’s activationStatus to confirm it is ACTIVATED. The response is a BulkActivation GET object. See Bulk Search and Update for overall guidance on this feature.

GET /papi/v1/bulk/activations/{bulkActivationId}{?contractId,groupId}

Sample: /papi/v1/bulk/activations/234?contractId=ctr_1-1TJZFW&groupId=grp_15166

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
bulkActivationId Integer 234 Identifies each bulk activation job.
Optional query parameters
contractId String ctr_1-1TJZFW Optionally filters bulk searches to properties provisioned under the specified contract. For bulk operations, you can specify contractId and groupId independently from each other.
groupId String grp_15166 Optionally filters bulk searches to properties provisioned under the specified group. For bulk operations, you can specify contractId and groupId independently from each other.

Status 200 application/json

Response Body:

{
    "bulkActivationId": 234,
    "bulkActivationStatus": "COMPLETE",
    "bulkActivationSubmitDate": "2018-01-18T00:00:00Z",
    "bulkActivationUpdateDate": "2018-01-18T01:00:00Z",
    "defaultActivationSettings": {
        "acknowledgeAllWarnings": true,
        "useFastFallback": false,
        "fastPush": true
    },
    "activatePropertyVersions": [
        {
            "propertyId": "prp_1",
            "propertyVersion": 2,
            "notifyEmails": [
                "you@example.com",
                "them@example.com"
            ],
            "acknowledgeAllWarnings": true,
            "useFastFallback": false,
            "fastPush": true,
            "network": "STAGING",
            "activateFromEtag": "93090516bde891d00923464",
            "note": "Some activation note",
            "taskStatus": "COMPLETE",
            "activationStatus": "NEW",
            "activationSubmitDate": "2018-01-18T00:00:00Z",
            "activationUpdateDate": "2018-01-18T00:00:00Z",
            "propertyActivationLink": "/papi/v1/properties/prp_1/activations/act_1"
        },
        {
            "propertyId": "prp_15",
            "propertyVersion": 3,
            "notifyEmails": [
                "someoneElse@somewhere.com"
            ],
            "acknowledgeAllWarnings": true,
            "useFastFallback": false,
            "fastPush": true,
            "network": "STAGING",
            "activateFromEtag": "516bde891d00923464",
            "note": "Sample activation",
            "taskStatus": "COMPLETE",
            "activationStatus": "NEW",
            "activationSubmitDate": "2018-01-18T00:00:00Z",
            "activationUpdateDate": "2018-01-18T00:00:00Z",
            "propertyActivationLink": "/papi/v1/properties/prp_1/activations/act_1",
            "numberOfWarningsFromActivation": 5
        },
        {
            "propertyId": "prp_3",
            "propertyVersion": 11,
            "notifyEmails": [
                "you@example.com",
                "them@example.com"
            ],
            "useFastFallback": false,
            "fastPush": true,
            "network": "PRODUCTION",
            "acknowledgeAllWarnings": false,
            "activateFromEtag": "93090591d00923464",
            "note": "created by xyz",
            "taskStatus": "COMPLETE",
            "activationStatus": "NEW",
            "activationSubmitDate": "2018-01-18T00:00:00Z",
            "activationUpdateDate": "2018-01-18T00:00:00Z",
            "propertyActivationLink": "/papi/v1/properties/prp_1/activations/act_1"
        },
        {
            "propertyId": "prp_4",
            "propertyVersion": 2,
            "notifyEmails": [
                "you@example.com",
                "them@example.com"
            ],
            "acknowledgeAllWarnings": false,
            "useFastFallback": false,
            "fastPush": true,
            "network": "STAGING",
            "activateFromEtag": "930900498abj891d00923464",
            "note": "Some activation note",
            "taskStatus": "SUBMISSION_ERROR",
            "activationStatus": "NEW",
            "activationSubmitDate": "2018-01-18T00:00:00Z",
            "activationUpdateDate": "2018-01-18T00:00:00Z",
            "propertyActivationLink": "/papi/v1/properties/prp_1/activations/act_1",
            "activationWarnings": [
                {
                    "type": "https://problems.luna.akamaiapis.net/papi/v1/validation/product_behavior_issue.cpcode_incorrect_product",
                    "detail": "The CP Code within `Content Provider Code` is not configured for use with the product used by this property, Dynamic Site Accelerator. Traffic for this property might not show up under the correct traffic reports.",
                    "messageId": "msg_48d27043qr3r2322781ac6dd06763470987ed7a5d"
                }
            ]
        },
        {
            "propertyId": "prp_5",
            "propertyVersion": 3,
            "acknowledgeAllWarnings": true,
            "useFastFallback": false,
            "fastPush": true,
            "network": "STAGING",
            "activateFromEtag": "93090516bde891d923797294",
            "note": "Some activation note",
            "taskStatus": "SUBMISSION_ERROR",
            "activationStatus": "NEW",
            "activationSubmitDate": "2018-01-18T00:00:00Z",
            "activationUpdateDate": "2018-01-18T00:00:00Z",
            "propertyActivationLink": "/papi/v1/properties/prp_1/activations/act_1",
            "fatalError": "activation requires a valid notifyEmail"
        }
    ]
}

To perform bulk activations, you need to run a series of four pairs of POST and GET operations, and need to be familiar with JSONPath and JSON patch tools. See Bulk Search and Update for details on the full procedure.

List custom behaviors

Lists the set of custom XML metadata behaviors configured for you by Akamai representatives. Referencing the relevant behaviorId from a customBehavior within the rule tree injects the custom XML within the rest of the rule tree’s metadata XML. See Custom behaviors and overrides for guidance on custom overrides.

GET /papi/v1/custom-behaviors

Headers:

PAPI-Use-Prefixes: true

Status 200 application/json

Response Body:

{
    "accountId": "act_1-1TJZFB",
    "customBehaviors": {
        "items": [
            {
                "behaviorId": "cbe_12345",
                "name": "DLR",
                "status": "ACTIVE",
                "displayName": "Custom Download Receipt",
                "description": "Setting custom download receipt. Uses PMUSER_LOG variable.",
                "updatedDate": "2017-04-24T12:34:56Z",
                "updatedByUser": "jsikkela"
            }
        ]
    }
}

To choose a custom behavior and insert it within a property’s rule tree:

  1. Consult with your Akamai representative to configure the XML metadata you need in the custom behavior.

  2. Once it’s ready, make a GET request to /papi/v1/custom-behaviors.

  3. Choose the appropriate CustomBehavior object from within the customBehaviors.items array and store its behaviorId.

  4. Run the Get a rule tree operation to modify the rule tree.

  5. Within the appropriate rule, either add or modify an existing customBehavior, specifying the stored behaviorId as an option.

  6. Run Update a rule tree to save the change.

Once you activate the rule, the custom behavior will perform any specified processing within the rule tree’s XML metadata.

Get a custom behavior

Get information for a single custom behavior. Use this operation if you want to examine the custom behavior’s XML metadata source.

GET /papi/v1/custom-behaviors/{behaviorId}

Sample: /papi/v1/custom-behaviors/cbe_12345

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
behaviorId String cbe_12345 Unique identifier for the custom behavior.

Status 200 application/json

Response Body:

{
    "customBehaviors": {
        "items": [
            {
                "behaviorId": "cbe_12345",
                "name": "DLR",
                "displayName": "Custom Download Receipt",
                "description": "Setting custom download receipt. Uses PMUSER_LOG variable.",
                "status": "ACTIVE",
                "xml": "<reporting:edge-logging.send-receipt name=\"DLR\"><hostname>logs.customer.com</hostname><url>/dlr</url><allow-cacheh>off</allow-cacheh><status>on</status><port>443</port><format>stuff=%(PMUSER_LOG)&amp;time=%t&amp;url=%u</format><method>POST</method></reporting:edge-logging.send-receipt>",
                "updatedDate": "2017-04-24T12:34:56Z",
                "updatedByUser": "jsikkela"
            }
        ]
    }
}

To choose a custom behavior and insert it within a property’s rule tree:

  1. Consult with your Akamai representative to configure the XML metadata you need in the custom behavior.

  2. Once it’s ready, make a GET request to /papi/v1/custom-behaviors.

  3. Choose the appropriate CustomBehavior object from within the customBehaviors.items array and store its behaviorId.

  4. Optionally make a GET request to /papi/v1/custom-behaviors/{behaviorId} if you want to examine the XML metadata source.

  5. Run the Get a rule tree operation to modify the rule tree.

  6. Within the appropriate rule, either add or modify an existing customBehavior, specifying the stored behaviorId as an option.

  7. Run Update a rule tree to save the change.

Once you activate the rule, the custom behavior will perform any specified processing within the rule tree’s XML metadata.

List custom overrides

Lists the set of custom XML metadata overrides configured for you by Akamai representatives. Referencing the relevant overrideId from a Rule.customOverride object makes the custom XML append to the rest of the metadata XML defined by the rule tree, typically to restore state. See Custom behaviors and overrides for guidance on custom overrides.

GET /papi/v1/custom-overrides

Headers:

PAPI-Use-Prefixes: true

Status 200 application/json

Response Body:

{
    "accountId": "act_1-1TJZFB",
    "customOverrides": {
        "items": [
            {
                "overrideId": "cbo_12345",
                "displayName": "MDC Behavior",
                "description": "Multiple Domain Configuration can be used to ...",
                "name": "mdc",
                "status": "ACTIVE",
                "updatedByUser": "jsikkela",
                "updatedDate": "2017-04-24T12:34:56Z"
            }
        ]
    }
}

To choose a custom override and append it to a property’s rule tree:

  1. Consult with your Akamai representative to configure the custom override XML metadata you need.

  2. Once it’s ready, make a GET request to /papi/v1/custom-overrides.

  3. Choose the appropriate CustomOverride object from within the customOverrides.items array and store its overrideId.

  4. Run the Get a rule tree operation to modify the rule tree.

  5. Modify the top-level default rule’s Rule.customOverride object, adding the stored overrideId as a member on that object.

  6. Run Update a rule tree to save the change.

Once you activate the rule, the custom override will perform any specified post-processing of the rule tree’s XML metadata.

Get a custom override

Get information for a single custom override. Use this operation if you want to examine the override’s XML metadata.

GET /papi/v1/custom-overrides/{overrideId}

Sample: /papi/v1/custom-overrides/cbo_12345

Headers:

PAPI-Use-Prefixes: true
Parameter Type Sample Description
URL parameters
overrideId String cbo_12345 Unique identifier for the custom override.

Status 200 application/json

Response Body:

{
    "customOverrides": {
        "items": [
            {
                "overrideId": "cbo_12345",
                "displayName": "MDC Behavior",
                "description": "Multiple Domain Configuration can be used to ...",
                "name": "mdc",
                "status": "ACTIVE",
                "updatedByUser": "jsikkela",
                "updatedDate": "2017-04-24T12:34:56Z",
                "xml": "<comment:info>This is where the XML goes</comment:info>"
            }
        ]
    }
}

To choose a custom override and append it to a property’s rule tree:

  1. Consult with your Akamai representative to configure the custom override XML metadata you need.

  2. Once it’s ready, make a GET request to /papi/v1/custom-overrides.

  3. Choose the appropriate CustomOverride object from within the customOverrides.items array and store its overrideId.

  4. Optionally make a GET request to /papi/v1/custom-overrides/{overrideId}. if you want to examine the XML metadata source.

  5. Run the Get a rule tree operation to modify the rule tree.

  6. Modify the top-level default rule’s Rule.customOverride object, adding the stored overrideId as a member on that object.

  7. Run Update a rule tree to save the change.

Once you activate the rule, the custom override will perform any specified post-processing of the rule tree’s XML metadata.

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 schema.

GET /papi/v1/rule-formats

Headers:

PAPI-Use-Prefixes: true

Status 200 application/json

Response Body:

{
    "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/v1/schemas/request/{filename}

Sample: /papi/v1/schemas/request/CreateNewEdgeHostnameRequestV0.json

Parameter Type Sample Description
URL parameters
filename String CreateNewEdgeHostnameRequestV0.json Schema’s filename.

Status 200 application/json

Response Body:

{
    "$schema": "http://json-schema.org/draft-04-schema#",
    "id": "resource:/descriptors/papi/v1/schemas/CreateNewEdgeHostnameRequestV0.json#",
    "javaType": "com.akamai.luna.papi.model.EdgeHostnameCreateRequest",
    "type": "object",
    "properties": {
        "productId": {
            "type": "string"
        },
        "domainPrefix": {
            "type": "string"
        },
        "domainSuffix": {
            "type": "string"
        },
        "secure": {
            "type": "boolean"
        },
        "ipVersionBehavior": {
            "type": "string",
            "enum": [
                "IPV4",
                "IPV6_COMPLIANCE",
                "IPV6_PERFORMANCE"
            ]
        },
        "slotNumber": {
            "description": "On POST, sets the slot number for ESSL (secure) properties.",
            "type": "integer"
        }
    },
    "required": [
        "domainPrefix",
        "domainSuffix",
        "ipVersionBehavior",
        "productId"
    ]
}

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 that 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/v1/schemas/products/{productId}/{ruleFormat}

Sample: /papi/v1/schemas/products/prd_Site_Accel/v2016-11-15

Parameter Type Sample Description
URL parameters
productId String prd_Site_Accel Unique identifier for the product. See Data conventions for details on omitting the value’s prd_ prefix.
ruleFormat String v2016-11-15 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 Body:

{
    "type": "object",
    "properties": {
        "rules": {
            "type": "object"
        }
    },
    "required": [
        "rules"
    ]
}
  1. Run the List products operation and store the relevant productId.

  2. Run the List rule formats operation and store the relevant ruleFormat string.

  3. GET the rule format schema from /papi/v1/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.

GET /papi/v1/client-settings

Status 200 application/json

Response Body:

{
    "ruleFormat": "v2015-08-08",
    "usePrefixes": true
}

Update client settings

Update the current set of default values that apply to API clients keyed by the current authorization token.

PUT /papi/v1/client-settings

Content-Type: application/json

Request Body:

{
    "ruleFormat": "v2015-08-08",
    "usePrefixes": true
}

Status 200 application/json

Response Body:

{
    "ruleFormat": "v2015-08-08",
    "usePrefixes": true
}

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 client settings response with the new ruleFormat value.

  3. PUT the object to /papi/v1/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/v1/build

Status 200 application/json

Response Body:

{
    "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 GET data is structured within an outer Envelope object, which provides additional contextual metadata about the requested object. 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" }

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.
Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it either triggers an error, or is ignored.

Group

Encapsulates information about the group that contains a property and allows it to be deployed. Relevant response objects appear within the outer Envelope object’s groups.items array.

Download schema: GetGroupResponse.json

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"
                ]
            },
            {
                "groupName": "TomTest",
                "groupId": "grp_41443",
                "parentGroupId": "grp_15225",
                "contractIds": [
                    "ctr_1-1TJZH5"
                ]
            }
        ]
    }
}

Group 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. See Data conventions for details on how to omit the ID’s grp_ prefix.
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. Relevant response objects appear within the outer Envelope object’s contracts.items array.

Download schema: GetContractResponse.json

Sample GET response:

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

Contract members

Member Type Required Description
contractId String A unique identifier for the contract. See Data conventions for details on how to omit the ID’s ctr_ prefix.
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. Relevant response objects appear within the outer Envelope object’s products.items array.

Download schema: GetProductResponse.json

Sample GET response:

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

Product members

Member Type Required Description
productId String A unique identifier for the product. See Data conventions for details on how to omit the ID’s prd_ prefix.
productName String A descriptive name for the product.

CpCode

Specifies billing and reporting codes. To make a POST request that creates a new CP code, specify an object with productId and cpcodeName members. Relevant response objects appear within the outer Envelope object’s cpcodes.items array.

Download schema: CreateNewCPCodeRequestV0.json, GetCpCodeResponse.json

Sample GET 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"
            }
        ]
    }
}

Sample POST request:

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

CpCode members

Member Type POST GET Description
cpcodeId String Read-only. A unique identifier for the CP code. See Data conventions for details on how to omit the ID’s cpc_ prefix.
cpcodeName String A descriptive label for the CP code.
createdDate String Read-only. A time stamp for the CP code.
productId String On POST, the product to assign to this CP code. See Data conventions for details on how to omit the ID’s prd_ prefix.
productIds Array Read-only. 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.

EdgeHostname

Specifies a set of available hostnames to which a property version may be applied. To POST a new edge hostname, specify a single object with productId, domainPrefix, and domainSuffix members, and optional ipVersionBehavior and secure members. Relevant response objects appear within the outer Envelope object’s edgehostnames.items array.

Download schema: CreateNewEdgeHostnameRequestV0.json, GetEdgeHostnameResponse.json

Sample GET 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",
                "domainPrefix": "example.com",
                "domainSuffix": "edgesuite.net",
                "secure": false,
                "ipVersionBehavior": "IPV4",
                "mapDetails:serialNumber": 1951,
                "mapDetails:mapDomain": "a1951.g.akamai.net"
            }
        ]
    }
}

Sample POST request:

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

EdgeHostname members

Member Type POST GET 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. See Data conventions for details on how to omit the ID’s ehn_ prefix.
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. See Data conventions for details on how to omit the ID’s prd_ prefix.
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.
slotNumber Integer On POST, sets the slot number for ESSL (secure) properties.
status Enumeration Appears as PENDING for any newly defined hostname whose DNS mapping has not yet been distributed across the entire Akamai network. If status is omitted, it indicates the edge hostname is active. (Do not confuse an edge hostname’s status with a property activation’s deployment status.)

Property

Contains configuration data to apply to edge content. Relevant response objects appear within the outer Envelope object’s properties.items array.

Download schema: CreateOrClonePropertyRequestV0.json, GetPropertyResponse.json

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,
                "assetId": "aid_101",
                "note": "Notes about example.com"
            }
        ]
    }
}

Sample POST request, cloning another property:

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

Property members

Member Type POST GET Description
accountId String Read-only. Identifies the account under which the property was created. See Data conventions for details on how to omit the ID’s act_ prefix.
assetId String An alternative identifier for the property, for internal use.
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. See Data conventions for details on how to omit the ID’s ctr_ prefix.
groupId String Identifies the group to which the property is assigned. See Data conventions for details on how to omit the ID’s grp_ prefix.
latestVersion Integer 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. See Data conventions for details on how to omit the ID’s prd_ prefix.
productionVersion Integer, Null The most recent version to be activated to the production network, otherwise null.
propertyId String The property’s unique identifier. See Data conventions for details on how to omit the ID’s prp_ prefix.
propertyName String A descriptive name for the property.
ruleFormat String On GET, reflects the property’s current format. Otherwise on POST, assigns a specific rule format to the property. Ignored on PUT, since you need to modify the Content-Type to change rule formats. For details, see Update rules to a newer set of features.
stagingVersion Integer, Null The most recent version to be activated to the test network, otherwise null.
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.
cloneFromVersionEtag String Performs an etag data integrity check on the original property. See Concurrency control for guidance.
copyHostnames Boolean Assigns the same set of hostnames to the new property, false by default.
propertyId String Specifies the property to clone. See Data conventions for details on how to omit the ID’s prp_ prefix.
version Integer Specifies the version of the property to clone.

Version

Specifies the version of a property. Relevant response objects appear within the outer Envelope object’s versions.items array. Additional contextual members appear in POST response listings when searching property versions. (For the POST request to create a new version, see the CreateVersion object type.)

Download schema: GetVersionResponse.json, PostSearchResponse.json

Sample GET response:

{
    "propertyId": "prp_173136",
    "propertyName": "981.catalog.amenai.net",
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "assetId": "aid_101",
    "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 search POST response:

{
    "versions": {
        "items": [
            {
                "accountId": "act_1-1TJZFB",
                "assetId": "aid_10333526",
                "contractId": "ctr_1-1TJZH5",
                "groupId": "grp_41443",
                "productionStatus": "INACTIVE",
                "propertyId": "prp_243865",
                "propertyName": "fifi2",
                "propertyVersion": 6,
                "stagingStatus": "INACTIVE",
                "updatedByUser": "dfknmimouc3ssovc",
                "updatedDate": "2017-08-07T15:39:49Z"
            },
            {
                "accountId": "act_1-1TJZFB",
                "assetId": "aid_10333526",
                "contractId": "ctr_1-1TJZH5",
                "groupId": "grp_41443",
                "productionStatus": "ACTIVE",
                "propertyId": "prp_243865",
                "propertyName": "fifi2",
                "propertyVersion": 1,
                "stagingStatus": "INACTIVE",
                "updatedByUser": "mvanhorn",
                "updatedDate": "2015-06-27T20:37:16Z"
            }
        ]
    }
}

Version members

Member Type GET POST Description
accountId String Read-only. In search results, identifies the account under which the property version is active. See Data conventions for details on how to omit the ID’s act_ prefix.
assetId String In search results, provides an alternative property identifier, for internal use.
contractId String Read-only. In search results, identifies the contract under which the property version is active. See Data conventions for details on how to omit the ID’s ctr_ prefix.
edgeHostname String Read-only. When searching for hostname or edgeHostname, this shows the relevant edge hostname to which the active version currently applies.
etag String A digest with which to check the data’s integrity. See Concurrency control for guidance.
groupId String Read-only. In search results, identifies the group under which the property version is active. See Data conventions for details on how to omit the ID’s grp_ prefix.
hostname String Read-only. When searching for hostname or edgeHostname, this shows the relevant property hostname to which the active version currently applies.
note String A descriptive log comment.
productId String The product assigned to the property when versioned. See Data conventions for details on how to omit the ID’s prd_ prefix.
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.
propertyId String Read-only. In search results, identifies the property to which the listed version belongs. See Data conventions for details on how to omit the ID’s prp_ prefix.
propertyName String Read-only. In search results, provides the name of the property to which the listed version belongs.
propertyVersion Integer Read-only. A positive integer identifying the incremental version.
ruleFormat String Identifies the rule format currently assigned to the property version’s rule tree.
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 Read-only. The username associated with the new version.
updatedDate String Read-only. The date stamp of the version’s latest update.

CreateVersion

When incrementing a new version, this POST object’s members are not reflected in subsequent Version responses.

Download schema: CreateNewPropertyVersionRequestV0.json

Sample POST request:

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

CreateVersion members

Member Type Required Description
createFromVersion Integer 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. See Concurrency control for guidance.

Hostname

Specifies an edge hostname that is applied to a property version. Writing data to this resource requires that you PUT an array of all the hostname objects, each containing edgeHostnameId, cnameFrom, and cnameTo members. This request array matches the hostnames.items in the response.

Download schema: GetHostnameResponse.json

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

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. See Data conventions for details on how to omit the ID’s ehn_ prefix.

Rule

Specifies the executable logic to apply to cached edge content. The outer Envelope object’s rules object specifies the relevant top-level default rule object. See the Rule Trees section for guidance on how to structure the data.

Download schema: GetRuleResponse.json

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": {
                    "httpPort": 80,
                    "enableTrueClientIp": false,
                    "compress": true,
                    "cacheKeyHostname": "ORIGIN_HOSTNAME",
                    "forwardHostHeader": "REQUEST_HOST_HEADER",
                    "hostname": "origin.test.com",
                    "originType": "CUSTOMER"
                }
            },
            {
                "name": "cpCode",
                "options": {
                    "value": {
                        "id": 12345,
                        "name": "my CP code"
                    }
                }
            }
        ],
        "children": []
    }
}

Rule members

Member Type Required Description
advancedOverride String A block of post-processing XML metadata that your Akamai representative can apply on your behalf. This must be configured separately for each property. Use the more recent customOverride member to apply the same XML metadata to more than one property.
behaviors Rule.behaviors[] A series of behavior objects, which execute after the set of criteria evaluates. Behavior and criteria objects are structured identically. Optional on nested rules.
children Object A series of nested Rule objects that execute after the current rule’s criteria and behaviors.
comment String A descriptive comment to help you track the rule’s function.
criteria Object A series of criteria objects, which form a set of logical tests that may prevent the rule’s behaviors from executing. Behavior and criteria objects are structured identically.
criteriaLocked Boolean Read-only. Within child rules, this prohibits any modifications to criteria objects. Contact your Akamai representative to change the value.
customOverride Rule.customOverride Specifies post-processing XML metadata that your Akamai representative can create on your behalf. Once available with the List custom overrides operation, you can assign an overrideId to more than one property’s default rule. See Custom behaviors and overrides for guidance.
name String A description of the rule. The top-level rule must be named default.
options Rule.options Flags that apply to the top-level rule object.
uuid String A data hash that indicates the rule contains at least one advanced behavior or criteria, each identified with its own uuid member. When this member is present on the rule, you may not remove any advanced features it contains, or change their sequence. You must provide the same uuid value when modifying the rule tree. See Advanced and locked features.
variables Rule.variables[] Declares a variable. See Variables for guidance on how variables may appear within a rule tree.
Rule.behaviors[]: A series of behavior objects, which execute after the set of criteria evaluates. Behavior and criteria objects are structured identically. Optional on nested rules.
locked String Indicates a behavior or criteria that you arrange with your Akamai representative to lock so that you can’t modify it, typically to protect sensitive data from erroneous changes.
name String The name of the behavior.
options Object A variable set of options that configure each behavior. See the PAPI Feature Catalog Reference for details on each.
uuid String Read-only. A data hash that indicates an advanced behavior. When present, you may not modify the contents of the behavior, and must provide the same uuid value when modifying the rule tree. See Advanced and locked features.
Rule.customOverride: Specifies post-processing XML metadata that your Akamai representative can create on your behalf. Once available with the List custom overrides operation, you can assign an overrideId to more than one property’s default rule. See Custom behaviors and overrides for guidance.
name String The name of the custom override, which may vary from what appears in the List custom overrides operation’s response object.
overrideId String A unique identifier for the predefined custom override metadata you want to append to the current rule. See Data conventions for details on how to omit the ID’s cbo_ prefix.
Rule.options: Flags that apply to the top-level rule object.
is_secure Boolean When enabled, serves the property’s content over SSL. Doing so may enable additional rule behaviors.
Rule.variables[]: Declares a variable. See Variables for guidance on how variables may appear within a rule tree.
description String Text for you to keep track of how you use each variable.
hidden Boolean When enabled, the variable is suppressed from session response headers, often used to test content as described in the Debugging variables section.
name String The underlying root name of the variable, which must be unique within the set of variables.
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.
value String Initializes a default value. Omitting this member initializes the variable with an empty string.

A query to search currently active properties. Only one query member is allowed in the POST request.

Download schema: SearchPropertyVersionsBySingleValueRequestV0.json

Sample POST request:

{
    "propertyName": "www.example.com_pm"
}

Search members

Member Type Required Description
edgeHostname String Search for property versions active on a specific edge hostname.
hostname String Search for property versions active on a specific hostname.
propertyName String Search for properties by name.

AvailableFeature

When listing available behaviors or criteria under your current contract, provides details for each.

Download schema: GetAvailableBehaviorResponse.json

AvailableFeature members

Member Type Required Description
name String The name of the currently available behavior or criteria.
schemaLink String A link to the rule format that describes the behavior or criteria. Use the file link to Get a rule format’s schema, then use the appended JSON Pointer expression to navigate to the schema that catalogs its options.

Activation

Activates property versions on a specific network. Relevant response objects appear within the outer Envelope object’s activations.items array.

Download schema: CreateNewActivationOrDeactivationRequestV0.json, GetActivationResponse.json

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-CONTRACT",
    "groupId": "grp_15225",
    "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"
                ],
                "fmaActivationState": "steady",
                "fallbackInfo": {
                    "fastFallbackAttempted": false,
                    "fallbackVersion": 10,
                    "canFastFallback": true,
                    "steadyStateTime": 1506448172,
                    "fastFallbackExpirationTime": 1506451772,
                    "fastFallbackRecoveryState": null
                }
            }
        ]
    }
}

Sample POST request:

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

Activation members

Member Type POST GET Description
accountId String Identifies the account under which the property activated. See Data conventions for details on how to omit the ID’s act_ prefix.
acknowledgeAllWarnings Boolean When POSTing an activation, allows you to skip acknowledging each warning. With this enabled, you can omit the acknowledgeWarnings array.
acknowledgeWarnings Array A list of msg_-prefixed string IDs acknowledging any warnings noted in responses to previous activation requests.
activationId String The activation’s unique identifier. See Data conventions for details on how to omit the ID’s atv_ prefix.
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.
fallbackInfo Activation.fallbackInfo Encapsulates information about fast fallback, which may allow you to fallback to a previous activation when POSTing an activation with useFastFallback enabled.
fastPush Boolean Enable a fast metadata push when activating a new property, true by default.
fmaActivationState Enumeration Read-only. Indicates fast metadata activation state. A value of steady indicates the property is currently active or has been cancelled. Values of received, lived, and deployed represent progressive stages of activation, while cancelling happens either after failing a network safety check or in response to a DELETE operation. Note that the status member indicates whether the activation is live.
groupId String Identifies the group under which the property activated. See Data conventions for details on how to omit the ID’s grp_ prefix.
ignoreHttpErrors Boolean Ignore any HTTP errors when pushing fast metadata activation, true by default.
network Enumeration The network to activate on, either STAGING or PRODUCTION.
note String Assigns a log message to the activation request.
notifyEmails Array A list of email address strings to notify when the activation status changes.
propertyId String Identifies property targeted with activation. See Data conventions for details on how to omit the ID’s prp_ prefix.
propertyName String The name of the property targeted with activation.
propertyVersion Integer The property version targeted with activation. Once activated, you can no longer modify that version of the property.
status Enumeration The activation’s status: ACTIVE if currently serving traffic; INACTIVE if another activation has superseded this one; NEW, PENDING, ZONE_1, ZONE_2, or ZONE_3 if not yet active; ABORTED if the client followed up with a DELETE request in time; FAILED if the activation causes a range of edge network errors that may cause a fallback to the previous activation; PENDING_DEACTIVATION or DEACTIVATED when the activationType is DEACTIVATE to no longer serve traffic.
submitDate String Read-only. A date stamp marking when the activation initiated.
updateDate String Read-only. A date stamp marking when the status last changed.
useFastFallback Boolean After activating a property and finding it causes problems, POSTing another activation within one hour with useFastFallback enabled quickly rolls back to the previous version. This option is only available for activations where canFastFallback is true.
Activation.fallbackInfo: Encapsulates information about fast fallback, which may allow you to fallback to a previous activation when POSTing an activation with useFastFallback enabled.
canFastFallback Boolean Whether the current activation can fallback to a previous version. This is typically false for new properties, or for property versions whose set of hostnames has changed.
fallbackVersion Integer Indicates the property version that activates when a fast fallback succeeds.
fastFallbackAttempted Boolean Whether a fast fallback has already been attempted on this activation.
fastFallbackExpirationTime Integer Epoch second timestamp marking when fast fallback is no longer possible for this activation.
fastFallbackRecoveryState String, Null Represents additional information available for any attempted fallback.
propertyVersion Integer The version for which fast fallback may be available.
steadyStateTime Integer Epoch second timestamp marking when the activation completed, signaled by an fmaActivationState of steady.

BulkSearch

A bulk search job. The request specifies JSONPath search queries, and the response includes JSON path locations within matching rule trees. Check the searchTargetStatus of potentially long-running asynchronous jobs for when they are COMPLETE. See Bulk Search and Update for guidance on how to use this object.

Download schema: CreateNewBulkSearchRequestV0.json, GetBulkSearchResponse.json

Sample POST request:

{
    "bulkSearchQuery": {
        "syntax": "JSONPATH",
        "match": "$..conditions[?(@.name == \"ext\" && \"mp3\" in @.options.value && \"mp4\" nin @.options.value)].options.value[?(@ == \"mp3\")]",
        "bulkSearchQualifiers": [
            "$.options[?(@.secure==\"true\")]",
            "$..features[?(@.name==\"origin\")].options[?(@.hostname==\"old.origin.example.com\")]"
        ]
    }
}

Sample GET response:

{
    "bulkSearchId": 5,
    "searchTargetStatus": "COMPLETE",
    "searchSubmitDate": "2018-01-18T00:00:00Z",
    "searchUpdateDate": "2018-01-18T00:01:00Z",
    "bulkSearchQuery": {
        "syntax": "JSONPATH",
        "match": "$..conditions[?(@.name == \"ext\" && \"mp3\" in @.options.value && \"mp4\" nin @.options.value)].options.value[?(@ == \"mp3\")]",
        "bulkSearchQualifiers": [
            "$.options[?(@.secure==\"true\")]",
            "$..features[?(@.name==\"origin\")].options[?(@.hostname==\"old.origin.example.com\")]"
        ]
    },
    "results": [
        {
            "propertyId": "prp_1",
            "propertyVersion": 1,
            "propertyName": "example1.example.com",
            "stagingStatus": "ACTIVE",
            "productionStatus": "INACTIVE",
            "isLatest": true,
            "isLocked": true,
            "isSecure": true,
            "accountId": "1-abcdef",
            "matchLocations": [
                "/rules/children/1/features/0",
                "/rules/children/1/features/3"
            ],
            "lastModifiedTime": "2018-01-18T00:00:00Z"
        },
        {
            "propertyId": "prp_15",
            "propertyVersion": 2,
            "propertyName": "example2.example.com",
            "stagingStatus": "INACTIVE",
            "productionStatus": "INACTIVE",
            "isLatest": false,
            "isLocked": false,
            "isSecure": true,
            "accountId": "1-abcdef",
            "matchLocations": [
                "/rules/children/1/children/0/features/1"
            ],
            "lastModifiedTime": "2018-01-18T00:00:00Z"
        },
        {
            "propertyId": "prp_3",
            "propertyVersion": 10,
            "propertyName": "example3.example.com",
            "stagingStatus": "INACTIVE",
            "productionStatus": "ACTIVE",
            "isLatest": true,
            "isLocked": true,
            "isSecure": true,
            "accountId": "1-abcdef",
            "matchLocations": [
                "/rules/children/0/children/1/children/2/features/1"
            ],
            "lastModifiedTime": "2018-01-18T00:00:00Z"
        }
    ]
}

BulkSearch members

Member Type POST GET Description
bulkSearchId Integer Identifies each bulk search process.
bulkSearchQuery BulkSearch.bulkSearchQuery Specifies the set of bulk search criteria.
results BulkSearch.results[] Search results based on the original bulk search request’s bulkSearchQuery, one for each property version.
searchSubmitDate String An ISO–8601 timestamp marking when the bulk search request occurred.
searchTargetStatus Enumeration Indicates progress for the entire bulk search process, either PENDING, SUBMITTED, IN_PROGRESS, or finally COMPLETE. In some cases, progress may fail due to an ERROR.
searchUpdateDate String An ISO–8601 timestamp marking when the searchTargetStatus for the bulk search process last changed.
BulkSearch.bulkSearchQuery: Reflects the bulk search request’s bulkSearchQuery object.
bulkSearchQualifiers Array An additional set of JSON Path test expressions that must succeed for the main match on the rule tree to yield results.
match String The JSON Path expression to search within available rule trees.
syntax Enumeration Identifies the query syntax for the search. The only currently supported syntax system is JSONPATH.
BulkSearch.results[]: Search results based on the original bulk search request’s bulkSearchQuery, one for each property version.
accountId String Identifies the specific field whose rule tree matches the search result.
isLatest Boolean Indicates whether this property version is the most recently modified, regardless of whether it is active. The most recently modified version appears along with active versions in bulk search results.
isLocked Boolean Indicates whether the property version is editable. The value is false if it is active or has ever been activated.
isSecure Boolean Identifies the specific field whose rule tree matches the search result.
lastModifiedTime String An ISO–8601 timestamp indicating when the matching property version was last modified.
matchLocations Array JSON path expressions for each matching node in the property version’s rule tree.
productionStatus Enumeration The matching property version’s activation status on the production network. Bulk search matches property versions currently active on production and staging networks. Values match those of the Activation object: ACTIVE, INACTIVE, NEW, PENDING, ZONE_1, ZONE_2, ZONE_3, ABORTED, FAILED, PENDING_DEACTIVATION or DEACTIVATED.
propertyId String Identifies the matching property. See Data conventions for details on how to omit the ID’s prp_ prefix.
propertyName String Identifies the specific property name whose rule tree matches the search query.
propertyVersion Integer Identifies the specific property version whose rule tree matches the search query.
stagingStatus Enumeration The matching property version’s activation status on the staging network. Bulk search matches property versions currently active on production and staging networks. Values match those of the Activation object: ACTIVE, INACTIVE, NEW, PENDING, ZONE_1, ZONE_2, ZONE_3, ABORTED, FAILED, PENDING_DEACTIVATION or DEACTIVATED.

BulkVersion

Encapsulates a set of properties from which to bulk create new versions. See Bulk Search and Update for guidance on this feature.

Download schema: CreateNewBulkPropertyVersionRequestV0.json, GetBulkPropertyVersionResponse.json

Sample POST request:

{
    "createPropertyVersions": [
        {
            "propertyId": "prp_1",
            "createFromVersion": 1,
            "createFromVersionEtag": "2641910c585cf67b"
        },
        {
            "propertyId": "prp_15",
            "createFromVersion": 2,
            "createFromVersionEtag": "343410c585cf67fc"
        },
        {
            "propertyId": "prp_3",
            "createFromVersion": 10,
            "createFromVersionEtag": "6c7v5c65c6cvcv65"
        }
    ]
}

Sample GET response:

{
    "bulkCreateId": 9,
    "bulkCreateVersionsStatus": "IN_PROGRESS",
    "bulkCreateVersionSubmitDate": "2018-01-18T00:00:00Z",
    "bulkCreateVersionUpdateDate": "2018-01-18T00:00:00Z",
    "createPropertyVersions": [
        {
            "propertyId": "prp_1",
            "createFromVersion": 1,
            "createFromVersionEtag": "343410c585cf67fb",
            "propertyVersion": 2,
            "createVersionStatus": "PENDING",
            "createVersionSubmitDate": "2018-01-18T00:00:00Z",
            "createVersionUpdateDate": "2018-01-18T00:00:00Z"
        },
        {
            "propertyId": "prp_15",
            "createFromVersion": 2,
            "createFromVersionEtag": "343410c585cf67fc",
            "propertyVersion": 3,
            "createVersionStatus": "IN_PROGRESS",
            "versionLink": null,
            "createVersionSubmitDate": "2018-01-18T00:00:00Z",
            "createVersionUpdateDate": "2018-01-18T00:00:00Z"
        },
        {
            "propertyId": "prp_3",
            "createFromVersion": 10,
            "createFromVersionEtag": "6c7v5c65c6cvcv65",
            "propertyVersion": 11,
            "createVersionStatus": "COMPLETE",
            "versionLink": "/papi/v1/properties/prp_3/versions/11?contractId=ctr_1-TJZFW&groupId=grp_15166",
            "createVersionSubmitDate": "2018-01-18T00:00:00Z",
            "createVersionUpdateDate": "2018-01-18T00:00:00Z"
        }
    ]
}

BulkVersion members

Member Type POST GET Description
bulkCreateId Integer Identifies each bulk-versioning process.
bulkCreateVersionsStatus Enumeration Tracks the status of the overall bulk versioning request, either PENDING, IN_PROGRESS, or COMPLETE.
bulkCreateVersionSubmitDate String An ISO–8601 timestamp indicating when the bulk versioning request occurred.
bulkCreateVersionUpdateDate String, Null An ISO–8601 timestamp indicating when the bulk versioning request most recently updated with changes to versions’ status. The value may be null when the bulk version request first occurs.
createPropertyVersions BulkVersion.createPropertyVersions[] Encapsulates information about each new property version to create.
BulkVersion.createPropertyVersions[]: Encapsulates information about each new property version to create.
createFromVersion Integer 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. If the digest doesn’t match the current state of the version, batch-versioning fails for this property. See Concurrency control for guidance.
createVersionStatus Enumeration Tracks the status of the versioning request for this property, either PENDING, SUBMITTED, IN_PROGRESS, or COMPLETE, indicating success. A SUBMISSION_ERROR means the versioning failed, for example, if the createFromVersionEtag didn’t reflect the version’s current state. A value of INTERRUPTED indicates a server error.
createVersionSubmitDate String, Null An ISO–8601 timestamp indicating when the request for a new version occurred. Note that this occurs asynchronously, and does not match when the overall bulk versioning request occurred.
createVersionUpdateDate String, Null An ISO–8601 timestamp indicating when the createVersionStatus last updated.
etag String, Null A digest with which to check the integrity of the newly created version’s data when making any subsequent modifications. See Concurrency control for guidance. The value may appear as null prior to the new version’s creation.
propertyId String Identifies the property for which to create a new version.
propertyVersion Integer Reflects the new version for this property resulting from the batch-versioning request.
propertyVersionLink String, Null Provides an API hypermedia link to each newly created property version. Prior to creation, the value is null.

BulkPatch

Encapsulates customized JSON patch instructions to run on a set of JSON path locations within various property versions’ rule trees. See Bulk Search and Update for guidance on this feature.

Download schema: GetBulkPatchResponse.json

Sample POST request:

{
    "patchPropertyVersions": [
        {
            "propertyId": "prp_1",
            "propertyVersion": 1,
            "patches": [
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/1/features/3/option/enabled"
                },
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/1/features/0/option/enabled"
                }
            ],
            "etag": "a87v5c65c6821bc"
        },
        {
            "propertyId": "prp_15",
            "propertyVersion": 2,
            "patches": [
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/1/children/0/features/1/enabled"
                }
            ],
            "etag": "6c7v5c65c6cvcv65"
        },
        {
            "propertyId": "prp_3",
            "propertyVersion": 10,
            "patches": [
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/0/children/1/children/2/features/1/enabled"
                }
            ],
            "etag": "1f8903bcde2f3"
        }
    ]
}

Sample GET response:

{
    "bulkPatchId": 7,
    "bulkPatchStatus": "COMPLETE",
    "bulkPatchSubmitDate": "2018-01-18T00:00:00Z",
    "bulkPatchUpdateDate": "2018-01-18T01:00:00Z",
    "patchPropertyVersions": [
        {
            "patchPropertyId": "prp_1",
            "patchPropertyVersion": 2,
            "patches": [
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/1/features/3/option/enabled"
                },
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/1/features/0/option/enabled"
                }
            ],
            "patchPropertyVersionStatus": "COMPLETE",
            "patchSubmitDate": "2018-01-18T00:00:00Z",
            "patchUpdateDate": "2018-01-18T00:00:00Z",
            "etag": "etag etag etag",
            "propertyVersionRulesLink": "/papi/v1/properties/prp_1/versions/1/rules",
            "papiErrors": [
                {
                    "type": "https://problems.luna.akamaiapis.net/papi/v1/validation/attribute_required",
                    "title": "Attribute not specified",
                    "detail": "The Verification Settings option on the `Origin Server` behavior is required.",
                    "instance": "https://control.sqa2.qa.akamai.com/papi/v1/bulk/activations/1?contractId=ctr_1-1TJZH5&groupId=grp_15225#853080b7-e411-432d-99ae-967e56b50d72",
                    "errorLocation": "#/rules/behaviors/0/options/verificationMode"
                }
            ],
            "papiWarnings": [
                {
                    "type": "https://problems.luna.akamaiapis.net/papi/v1/validation/product_behavior_issue.cpcode_incorrect_product",
                    "title": "Unstable rule format",
                    "detail": "The CP Code within `Content Provider Code` is not configured for use with the product used by this property, Dynamic Site Accelerator. Traffic for this property might not show up under the correct traffic reports.",
                    "instance": "https://control.sqa2.qa.akamai.com/papi/v1/bulk/activations/1?contractId=ctr_1-1TJZH5&groupId=grp_15225#853080b7-e411-432d-99ae-967e56b50d72",
                    "errorLocation": "#/rules/behaviors/1/options/value"
                }
            ]
        },
        {
            "patchPropertyId": "prp_15",
            "patchPropertyVersion": 3,
            "patches": [
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/1/children/0/features/1/enabled"
                }
            ],
            "patchPropertyVersionStatus": "SUBMISSION_ERROR",
            "patchSubmitDate": "2018-01-18T00:00:00Z",
            "patchUpdateDate": "2018-01-18T00:00:00Z",
            "fatalError": "BAD SYNTAX UNABLE TO SAVE"
        },
        {
            "patchPropertyId": "prp_3",
            "patchPropertyVersion": 11,
            "patches": [
                {
                    "op": "replace",
                    "value": "on",
                    "path": "/rules/children/0/children/1/children/2/features/1/enabled"
                }
            ],
            "patchPropertyVersionStatus": "COMPLETE",
            "patchSubmitDate": "2018-01-18T00:00:00Z",
            "patchUpdateDate": "2018-01-18T00:00:00Z",
            "etag": "etag etag etag",
            "propertyVersionRulesLink": "/papi/v1/properties/prp_3/versions/1/rules"
        }
    ]
}

BulkPatch members

Member Type Required Description
bulkPatchId Integer Identifies each bulk patch process.
bulkPatchStatus Enumeration Reflects the status of the entire bulk update request, either PENDING, IN_PROGRESS, or COMPLETE.
bulkPatchSubmitDate String An ISO–8601 timestamp indicating when you first made the bulk patch request.
bulkPatchUpdateDate String An ISO–8601 timestamp indicating when any of the property versions’ status value last changed.
patchPropertyVersions BulkPatch.patchPropertyVersions[] Specifies JSON patch instructions to modify each property version.
BulkPatch.patchPropertyVersions[]: Specifies JSON patch instructions to modify each property version.
etag String An etag value that matches the state of the property you want to modify. When specified as part of the bulk patch request, it causes this property’s update to fail if someone else modifies the property in the meantime. See Concurrency control for guidance on this feature.
fatalError String Indicates an error that prevented this property version from updating, such as malformed JSON Patch instructions or resulting rule tree data formatting. This type of error is not the same as the papiErrors you are allowed to save on a property version, but not to activate.
papiErrors BulkPatch.patchPropertyVersions[].papiErrors[] Lists any validation errors resulting from the bulk update, which would prevent you from including this property version in a bulk activation. These are the same type of validation errors PAPI allows you to save in a property version, not to be confused with a fatalError that prevents it from being saved.
papiWarnings BulkPatch.patchPropertyVersions[].papiWarnings[] Lists any validation warnings resulting from the bulk update, which you would need to acknowledge when bulk-activating property versions.
patches BulkPatch.patchPropertyVersions[].patches[] Represents each instruction to modify part of a rule tree.
patchPropertyId String Identifies the property you want to modify as part of the bulk patch.
patchPropertyVersion Integer The version of the property you want to modify as part of the bulk patch.
patchPropertyVersionStatus Enumeration Indicates progress for the update to this property version’s rule tree, either PENDING, SUBMITTED, IN_PROGRESS, or COMPLETE for success. A SUBMISSION_ERROR typically indicates that replacement values caused a schema violation, not a new set of errors that you would ordinarily be able to save on rule trees. A value of INTERRUPTED indicates a server error.
patchSubmitDate String An ISO–8601 timestamp indicating when the request to modify this property version’s rule tree occurred.
patchUpdateDate String An ISO–8601 timestamp indicating when this property version’s status last changed, usually indicating when the update completed.
propertyVersionRulesLink String An API hypermedia link to retrieve specific rule trees after they are updated.
BulkPatch.patchPropertyVersions[].papiErrors[]: Lists any validation errors resulting from the bulk update, which would prevent you from including this property version in a bulk activation. These are the same type of validation errors PAPI allows you to save in a property version, not to be confused with a fatalError that prevents it from being saved.
detail String Provides context for the problem that triggered the error.
errorLocation String A JSON Path expression that locates the rule tree node where the problem occurred.
instance String A URI that identifies each error’s occurrence, possibly useful when communicating with Akamai customer support.
title String A descriptive label for each type of error.
type String A URI that identifies each error case. See the Errors section for details on each.
BulkPatch.patchPropertyVersions[].papiWarnings[]: Lists any validation warnings resulting from the bulk update, which you would need to acknowledge when bulk-activating property versions.
detail String Provides context for the problem that triggered the warning.
errorLocation String A JSON Path expression that locates the rule tree node where the problem occurred.
instance String A URI that identifies each warning’s occurrence, possibly useful when communicating with Akamai customer support.
title String A descriptive label for each type of warning.
type String A URI that identifies each warning case. See the Errors section for details on each.
BulkPatch.patchPropertyVersions[].patches[]: Represents each instruction to modify part of a rule tree.
op Enumeration The JSON Patch operation to perform, for which the only available option is replace.
path String A JSONPath expression that locates the value to replace within the rule tree.
value String, Number, Boolean Specifies the replacement value. This needs to correspond to the original matched value’s data type, or the rule tree will fail to update.

BulkActivation

Encapsulates each batch of bulk activations. While essentially a wrapper for an Activation object array, this specifies additional settings to apply to all activations within the batch. See Bulk Search and Update for guidance on this feature.

Download schema: CreateNewBulkActivationOrDeactivationRequestV0.json, GetBulkActivationResponse.json

Sample POST request:

{
    "defaultActivationSettings": {
        "notifyEmails": [
            "you@example.com",
            "them@example.com"
        ],
        "acknowledgeAllWarnings": true,
        "useFastFallback": false,
        "fastPush": true
    },
    "activatePropertyVersions": [
        {
            "propertyId": "prp_1",
            "propertyVersion": 2,
            "network": "STAGING",
            "activateFromEtag": "93090516bde891d00923464",
            "note": "Some activation note"
        },
        {
            "propertyId": "prp_15",
            "propertyVersion": 3,
            "notifyEmails": [
                "someoneElse@somewhere.com"
            ],
            "network": "STAGING",
            "activateFromEtag": "a9dfe78cf93090516bde891d009eaf57",
            "note": "Sample activation"
        },
        {
            "propertyId": "prp_3",
            "propertyVersion": 11,
            "network": "PRODUCTION",
            "acknowledgeAllWarnings": false,
            "activateFromEtag": "e891d234009eaf57",
            "note": "created by xyz"
        }
    ]
}

Sample GET response:

{
    "bulkActivationId": 234,
    "bulkActivationStatus": "COMPLETE",
    "bulkActivationSubmitDate": "2018-01-18T00:00:00Z",
    "bulkActivationUpdateDate": "2018-01-18T01:00:00Z",
    "defaultActivationSettings": {
        "acknowledgeAllWarnings": true,
        "useFastFallback": false,
        "fastPush": true
    },
    "activatePropertyVersions": [
        {
            "propertyId": "prp_1",
            "propertyVersion": 2,
            "notifyEmails": [
                "you@example.com",
                "them@example.com"
            ],
            "acknowledgeAllWarnings": true,
            "useFastFallback": false,
            "fastPush": true,
            "network": "STAGING",
            "activateFromEtag": "93090516bde891d00923464",
            "note": "Some activation note",
            "taskStatus": "COMPLETE",
            "activationStatus": "NEW",
            "activationSubmitDate": "2018-01-18T00:00:00Z",
            "activationUpdateDate": "2018-01-18T00:00:00Z",
            "propertyActivationLink": "/papi/v1/properties/prp_1/activations/act_1"
        },
        {
            "propertyId": "prp_15",
            "propertyVersion": 3,
            "notifyEmails": [
                "someoneElse@somewhere.com"
            ],
            "acknowledgeAllWarnings": true,
            "useFastFallback": false,
            "fastPush": true,
            "network": "STAGING",
            "activateFromEtag": "516bde891d00923464",
            "note": "Sample activation",
            "taskStatus": "COMPLETE",
            "activationStatus": "NEW",
            "activationSubmitDate": "2018-01-18T00:00:00Z",
            "activationUpdateDate": "2018-01-18T00:00:00Z",
            "propertyActivationLink": "/papi/v1/properties/prp_1/activations/act_1",
            "numberOfWarningsFromActivation": 5
        },
        {
            "propertyId": "prp_3",
            "propertyVersion": 11,
            "notifyEmails": [
                "you@example.com",
                "them@example.com"
            ],
            "useFastFallback": false,
            "fastPush": true,
            "network": "PRODUCTION",
            "acknowledgeAllWarnings": false,
            "activateFromEtag": "93090591d00923464",
            "note": "created by xyz",
            "taskStatus": "COMPLETE",
            "activationStatus": "NEW",
            "activationSubmitDate": "2018-01-18T00:00:00Z",
            "activationUpdateDate": "2018-01-18T00:00:00Z",
            "propertyActivationLink": "/papi/v1/properties/prp_1/activations/act_1"
        },
        {
            "propertyId": "prp_4",
            "propertyVersion": 2,
            "notifyEmails": [
                "you@example.com",
                "them@example.com"
            ],
            "acknowledgeAllWarnings": false,
            "useFastFallback": false,
            "fastPush": true,
            "network": "STAGING",
            "activateFromEtag": "930900498abj891d00923464",
            "note": "Some activation note",
            "taskStatus": "SUBMISSION_ERROR",
            "activationStatus": "NEW",
            "activationSubmitDate": "2018-01-18T00:00:00Z",
            "activationUpdateDate": "2018-01-18T00:00:00Z",
            "propertyActivationLink": "/papi/v1/properties/prp_1/activations/act_1",
            "activationWarnings": [
                {
                    "type": "https://problems.luna.akamaiapis.net/papi/v1/validation/product_behavior_issue.cpcode_incorrect_product",
                    "detail": "The CP Code within `Content Provider Code` is not configured for use with the product used by this property, Dynamic Site Accelerator. Traffic for this property might not show up under the correct traffic reports.",
                    "messageId": "msg_48d27043qr3r2322781ac6dd06763470987ed7a5d"
                }
            ]
        },
        {
            "propertyId": "prp_5",
            "propertyVersion": 3,
            "acknowledgeAllWarnings": true,
            "useFastFallback": false,
            "fastPush": true,
            "network": "STAGING",
            "activateFromEtag": "93090516bde891d923797294",
            "note": "Some activation note",
            "taskStatus": "SUBMISSION_ERROR",
            "activationStatus": "NEW",
            "activationSubmitDate": "2018-01-18T00:00:00Z",
            "activationUpdateDate": "2018-01-18T00:00:00Z",
            "propertyActivationLink": "/papi/v1/properties/prp_1/activations/act_1",
            "fatalError": "activation requires a valid notifyEmail"
        }
    ]
}

BulkActivation members

Member Type POST GET Description
activatePropertyVersions BulkActivation.activatePropertyVersions[] Specifies each property version to include in the bulk activation. Following bulk activation, this reflects the activation state for each property.
bulkActivationId Integer Unique identifier for each bulk activation request.
bulkActivationStatus Enumeration Reflects the status of the entire bulk update request, either PENDING, IN_PROGRESS, or COMPLETE.
bulkActivationSubmitDate String An ISO–8601 timestamp indicating when the bulk activation process initiated.
bulkActivationUpdateDate String An ISO–8601 timestamp indicating when the bulkActivationStatus last changed.
defaultActivationSettings BulkActivation.defaultActivationSettings Specifies activation settings to apply to all properties.
BulkActivation.activatePropertyVersions[]: Specifies each property version to include in the bulk activation. Following bulk activation, this reflects the activation state for each property.
acknowledgeAllWarnings Boolean Indicates whether acknowledgeAllWarnings was specified as part of the bulk activation request’s defaultActivationSettings, thus allowing this and other properties to activate despite any warnings.
activateFromEtag String An etag value that matches the state of the property you want to activate. When specified as part of the bulk activation request, it causes this property activation to fail if someone else modifies the property in the meantime. See Concurrency control for guidance on this feature.
activationStatus Enumeration This property’s initial activation status usually NEW. Values match those of the Activation object: ACTIVE, INACTIVE, NEW, PENDING, ZONE_1, ZONE_2, ZONE_3, ABORTED, FAILED, PENDING_DEACTIVATION or DEACTIVATED.
activationSubmitDate String An ISO–8601 timestamp indicating when activation initiated for this property.
activationUpdateDate String An ISO–8601 timestamp indicating when this property’s activationStatus last changed.
activationWarnings BulkActivation.activatePropertyVersions[].activationWarnings[] Lists any validation warnings resulting from the bulk activation, which you would need to acknowledge when bulk-activating property versions.
fastPush Boolean Indicates whether fastPush was specified as part of the bulk activation request’s defaultActivationSettings, thus allowing this and other properties to rely on fast metadata push.
fatalError String Indicates an error that prevented this property version from activating.
network Enumeration The network on which to activate this property, either STAGING or PRODUCTION.
note String An optional log message for this property’s activation.
notifyEmails Array A list of email address strings to notify when this property’s activationStatus changes. Note that these may supplement the set of notifyEmails specified within the bulk activation request’s defaultActivationSettings.
propertyActivationLink String Provides an API hypermedia link to each activation within the bulk activation job.
propertyId String Identifies each property targeted for activation. See Data conventions for details on how to omit the ID’s prp_ prefix.
propertyName String Identifies the property name targeted for activation within the bulk activation job. Once activated.
propertyVersion Integer The property version targeted for activation. Once activated, you can no longer modify that version of the property.
taskStatus Enumeration This property’s initial task status usually NEW. Values match those of the Activation object: PENDING, IN_PROGRESS, SUBMITTED, INTERRUPTED, SUBMISSION_ERROR, and COMPLETE.
useFastFallback Boolean Indicates whether useFastFallback was specified as part of the bulk activation request’s defaultActivationSettings, thus allowing this and other properties to quickly fall back to the previous activation.
BulkActivation.activatePropertyVersions[].activationWarnings[]: Lists any validation warnings resulting from the bulk activation, which you would need to acknowledge when bulk-activating property versions.
detail String Provides context for the problem that triggered the warning.
messageId String Provides messageIds for the warnings, which you would need to acknowledge when bulk-activating property versions.
type String A URI that identifies each warning case. See the Errors section for details on each.
BulkActivation.defaultActivationSettings: Common settings to apply to all activations in the batch.
acknowledgeAllWarnings Boolean For all activations, skip acknowledging any warnings for all properties within the bulk activation job.
fastPush Boolean Enable fast metadata push when bulk activating properties, true by default.
notifyEmails Array A list of email address strings to notify when the activation status changes for any property within the bulk activation. Note that you can supplement additional email addresses for each property you activate.
useFastFallback Boolean When enabled, rolls back to the previous activation of each property included in the bulk activation job. If you bulk activate a set of properties, and then within one hour discover a serious problem you didn’t previously detect, enabling this in a follow-up bulk activation request effectively cancels all the activations. See Fast Validation and Activation for guidance. Note that while the fast fallback option ordinarily does not apply to activations that affect a different set of hostnames, this scenario is unlikely when bulk-modifying properties.

CustomBehavior

Represents a customized XML metadata Akamai sets up on your behalf, and which you can invoke in a customBehavior within a rule tree. Relevant response objects appear within the outer Envelope object’s customBehaviors.items array. See Custom behaviors and overrides for guidance.

Download schema: GetCustomBehaviorResponse.json

Sample GET response:

{
    "customBehaviors": {
        "items": [
            {
                "behaviorId": "cbe_12345",
                "name": "DLR",
                "displayName": "Custom Download Receipt",
                "description": "Setting custom download receipt. Uses PMUSER_LOG variable.",
                "status": "ACTIVE",
                "xml": "<reporting:edge-logging.send-receipt name=\"DLR\"><hostname>logs.customer.com</hostname><url>/dlr</url><allow-cacheh>off</allow-cacheh><status>on</status><port>443</port><format>stuff=%(PMUSER_LOG)&amp;time=%t&amp;url=%u</format><method>POST</method></reporting:edge-logging.send-receipt>",
                "updatedDate": "2017-04-24T12:34:56Z",
                "updatedByUser": "jsikkela"
            }
        ]
    }
}

CustomBehavior members

Member Type Required Description
behaviorId String The unique identifier for the custom XML metadata that you reference from a customBehavior to insert it in a rule tree. See Data conventions for details on how to omit the ID’s cbe_ prefix.
description String Descriptive text for the custom metadata.
displayName String A display label for the custom metadata.
name String A name for the custom metadata.
status Enumeration Current deployment status for the custom metadata. By the time it is available to customers, the only possible value is ACTIVE.
updatedByUser String The name of the Akamai representative who last updated the custom metadata.
updatedDate String The date stamp of the custom metadata’s latest update.
xml String The customized XML metadata to inject within the rule.

CustomOverride

Represents a customized XML metadata Akamai sets up on your behalf, and which you can invoke in a Rule.customOverride object within the top-level default rule tree to make it execute after all other rules, typically to restore a desired state. Relevant response objects appear within the outer Envelope object’s customOverrides.items array. See Custom behaviors and overrides for guidance on custom overrides.

Download schema: GetCustomOverrideResponse.json

Sample GET response:

{
    "customOverrides": {
        "items": [
            {
                "overrideId": "cbo_12345",
                "displayName": "MDC Behavior",
                "description": "Multiple Domain Configuration can be used to ...",
                "name": "mdc",
                "status": "ACTIVE",
                "updatedByUser": "jsikkela",
                "updatedDate": "2017-04-24T12:34:56Z",
                "xml": "<comment:info>This is where the XML goes</comment:info>"
            }
        ]
    }
}

CustomOverride members

Member Type Required Description
description String Description for the custom override.
displayName String Display label for the custom override.
name String Name for the custom override.
overrideId String The unique identifier for the custom XML override that you reference from a Rule.customOverride object to append it to a rule tree. See Data conventions for details on how to omit the ID’s cbo_ prefix.
status Enumeration Current deployment status for the custom override. By the time it is available to customers, the only possible value is ACTIVE.
updatedByUser String The name of the Akamai representative who last updated the custom override.
updatedDate String The date stamp of the custom metadata’s latest update.
xml String The customized XML metadata to append to the rule tree.

ClientSettings

Specifies default settings for an API client.

Download schema: SetClientSettingsRequestV0.json

Sample GET response:

{
    "ruleFormat": "v2015-08-08",
    "usePrefixes": true
}

ClientSettings members

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. This specifies the default rule format version to apply to new properties. See API versioning for more information.
usePrefixes Boolean Whether ID values in response data should feature three-letter prefixes to indicate their type. You can set the PAPI-Use-Prefixes header to override the client’s default for each request. See Data conventions for more information.

Build

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

All object members are read-only, and always present.

Download schema: GetBuildResponse.json

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

Member Type Description
catalogGitInfo Build.catalogGitInfo Specifies internal tracking data.
coreGitInfo Build.coreGitInfo Specifies internal tracking data.
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.
Build.catalogGitInfo: Specifies internal tracking data.
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.
Build.coreGitInfo: Specifies internal tracking data.
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.

Provides a hypermedia link to a newly created resource.

All object members are read-only.

Download schema: PostActivationResponse.json, PostCpCodeResponse.json, PostEdgeHostnameResponse.json, PostPropertyResponse.json, PostVersionResponse.json

ResponseLink members

Member Type Required Description
activationLink String Links the new activation.
cpcodeLink String Links the newly created CP code.
edgeHostnameLink String Links the newly created edge hostname.
propertyLink String Links the newly created property.
versionLink String Links the newly created property version.

Envelope

A common outer wrapping object structure that provides additional contextual details for a set of requested data. The data itself is available under various inner members’ items array, even individual items. See Data conventions for more information.

All object members are read-only.

Download schema: GetActivationResponse.json, GetAvailableBehaviorResponse.json, GetAvailableCriteriaResponse.json, GetContractResponse.json, GetCpCodeResponse.json, GetCustomBehaviorResponse.json, GetCustomOverrideResponse.json, GetEdgeHostnameResponse.json, GetGroupResponse.json, GetHostnameResponse.json, GetProductResponse.json, GetPropertyResponse.json, GetRuleFormatResponse.json, GetRuleResponse.json, GetVersionResponse.json

Envelope members

Member Type Required Description
accountId String Identifies the prevailing account under which the data was requested. See Data conventions for details on how to omit the ID’s act_ prefix.
accountName String A descriptive name for the account.
activations Activation Array The set of requested activations, available within an items array.
assetId String An alternative property identifier, for internal use.
availableBehaviors AvailableFeature array The set of available behaviors, available within an items array.
availableCriteria AvailableFeature array The set of available criteria, available within an items array.
contractId String A unique identifier for the prevailing contract under which the data was requested. See Data conventions for details on how to omit the ID’s ctr_ prefix.
contracts Contract Array The set of requested contracts, available within an items array.
cpcodes CpCode Array The set of requested CP codes, available within an items array.
customBehaviors CustomBehavior Array The set of requested custom behaviors, available within an items array.
customOverrides CustomOverride Array The set of requested custom overrides, available within an items array.
edgeHostnames EdgeHostname Array The set of requested edge hostnames, available within an items array.
etag String A digest with which to check the data’s integrity.
groupId String A unique identifier for the prevailing group under which the data was requested. See Data conventions for details on how to omit the ID’s grp_ prefix.
groups Group Array The set of requested groups, available within an items array.
hostnames Hostname Array The set of requested property hostnames, available within an items array.
productId String When listing available behaviors or criteria under your current contract, identifies the product under which the property was created.
products Product Array The set of requested products, available within an items array.
properties Property Array The set of requested properties, available within an items array.
propertyId String A unique identifier for the property associated with this property version, or its component rules or hostnames. See Data conventions for details on how to omit the ID’s prp_ prefix.
propertyName String A descriptive name for the property associated with this property version.
propertyVersion Integer The version of the property that a rule tree represents.
ruleFormat String Indicates the versioned set of features and criteria that are currently applied to a rule tree. See API versioning for more information.
ruleFormats String The set of requested rule formats, strings available within an items array.
rules Rule Specifies the executable logic to apply to cached edge content. The outer Envelope object’s rules object specifies the relevant top-level default rule object. See the Rule Trees section for guidance on how to structure the data.
versions Version Array The set of requested property versions, available within an items array.

Rule Trees

A property’s main functionality is encapsulated in its set of rules. This section details how rules operate, how to configure prerequisite features, and how to structure the rest of a rule tree from the root down. It also shows how to deal with special read-only features, and 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 how 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 behaviors may only be available within the rule 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/v1/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 may 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.

Higher-level Rule objects may also indicate the presence of these 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.

Custom behaviors and overrides

The main problem with the advanced features described above is that they need to be customized separately for each property in which they appear. To address this issue, PAPI’s alternative custom features are defined outside the rule tree. You can reference these common objects from within many different rule trees.

Suppose you have an advanced behavior whose xml does something useful:

{
  "name": "advanced",
  "options": {
    "description": "Setting custom download receipt. Uses PMUSER_LOG variable.",
    "xml": "<reporting:edge-logging.send-receipt name=\"DLR\"><hostname>logs.customer.com</hostname><url>/dlr</url><allow-cacheh>off</allow-cacheh><status>on</status><port>443</port><format>stuff=%(PMUSER_LOG)&amp;time=%t&amp;url=%u</format><method>POST</method></reporting:edge-logging.send-receipt>"
  },
  "uuid": "6c192451-f35f-4a8d-ad70-0e8fec521d99"
}

To apply it to many properties, contact your Akamai representative to configure the XML as a custom behavior. Once ready, you run the List custom behaviors operation, choose the appropriate custom behavior, and store its behaviorId value:

{
    "accountId": "act_1-1TJZFB",
    "customBehaviors": {
        "items": [
            {
                "behaviorId": "cbe_12345",
                "name": "DLR",
                "displayName": "Custom Download Receipt",
                "description": "Setting custom download receipt. Uses PMUSER_LOG variable.",
                "status": "ACTIVE",
                "xml": "<reporting:edge-logging.send-receipt name=\"DLR\"><hostname>logs.customer.com</hostname><url>/dlr</url><allow-cacheh>off</allow-cacheh><status>on</status><port>443</port><format>stuff=%(PMUSER_LOG)&amp;time=%t&amp;url=%u</format><method>POST</method></reporting:edge-logging.send-receipt>",
                "updatedDate": "2017-04-24T12:34:56Z",
                "updatedByUser": "jsikkela"
            }
        ]
    }
}

You can then insert a customBehavior to reference the common metadata from within any rule tree, with no need to preserve a uuid value when exchanging the rule:

{
    "name": "customBehavior",
    "options": {
        "behaviorId": "cbe_12345",
        "name": "mdc"
    }
}

Custom overrides work much the same way as custom behaviors, but are meant to execute last in the rule tree, typically to restore some state that the rule tree may have modified along the way. Your Akamai representative creates a custom override on your behalf, which you then access with the List custom overrides operation. After choosing an overrideId from the list, you insert it into a customOverride region directly on the outer Rule object:

{
    "rules": {
        "name": "default",
        "options": {
            "is_secure": false
        }
    },
    "customOverride": {
        "overrideId": "cbo_12345",
        "name": "mdc"
    }
}

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 references detail 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.

Variables

This section shows how to manage variables, custom text values that interpret throughout a rule tree when the property executes at runtime. You can embed built-in variables to capture contextual information about the client’s request, or create your own variables based on a variety of inputs. You can perform conditional logic based on the variable’s value, and catch any unforeseen errors that execute on the edge at runtime.

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

Inserting variables

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_FIREWALL_MITIGATED_RULES A colon-separated list of IDs for firewall rules that were mitigated for the current request.
AK_FIREWALL_TRIGGERED_RULES A colon-separated list of IDs for firewall rules that were triggered for the current 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_MAPRULE The maprule for the incoming request, such as a123.g.akamai.net.
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_ORIGIN_DNS_NAME The hostname the Akamai server resolved to go forward to the origin.
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 in the Modifying variables section.

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": []
    }
}

For details on the members included in each variable declaration object, see Rule.variables[].

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, 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 variables 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.

Bulk Search and Update

This section describes PAPI’s new bulk search and update feature. With bulk search and update, you are no longer limited to modifying your property configurations one at a time. Maintaining a large set of properties, you can keep important behaviors synchronized with a few API calls.

This section shows you how to search across all your properties, then create a new set of editable property versions based on the results. It shows you how to patch a set of configurations to modify them, then activate the entire set of modified properties on Akamai’s staging and production networks.

Note. The new bulk search and update feature is in beta release. Contact Akamai if you are interested in joining the beta program.

The following provides a detailed reference for each API operation discussed here, and schema specifications for the JSON data the API exchanges. In each phase of the bulk update procedure, you run a pair of operations, the first to launch a request, and the second to poll the asynchronous results:

POST request… …followed by GET response Object type
Bulk search a set of properties List bulk search results BulkSearch
Bulk version a set of properties List bulk-versioned properties BulkVersion
Bulk patch a set of properties List bulk-patched properties BulkPatch
Bulk activate a set of properties List bulk-activated properties BulkActivation

Sample workflow

This simplified workflow provides pointers to more detailed steps below:

  1. Prepare a bulk search request by specifying a search expression. Optionally specify additional searches to reduce the set of search results.

  2. Launch the bulk search, storing the response’s search ID.

  3. Use the ID to check the search results, repeating if they’re not yet complete. The results include any active property version, along with the most recently modified version if inactive.

  4. If you want to further update a set of property versions that are active, bulk-create a new set of versions and store the new set of version numbers from the completed results.

  5. Use data from the search results and any newly created version numbers to form a bulk patch request. Specify a replacement value as part of the patch.

  6. Launch a request to patch all the configurations, storing the response’s patch ID.

  7. Use the patch ID to check the patch results, repeating if they’re not yet complete.

  8. Use the property IDs and versions from the bulk patch results to launch a bulk activation, storing the response’s activation ID.

Once you confirm the bulk activation is complete, your updated properties are live.

Sample bulk updates

This section summarizes some of the more useful searches you may want to run, along with the JSONPath syntax needed for the bulk search request, and sample replacement values.

Most of these searches match anywhere within the configuration. See the Contextual searches section below if you need help searching more specific locations within the configuration. See the PAPI Feature Catalog Reference for a full reference of all behavior and criteria options you can update within your configurations.

Match JSONPath search Replacement
Default origin hostname $.behaviors[?(@.name == 'origin')].options.hostname "www.example.com"
Any origin hostname set to old.example.com $..behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname "new.example.com"
Default caching TTL $.behaviors[?(@.name == 'caching')].options.defaultTtl "12h"
Any caching TTL value other than 1 day $..behaviors[?(@.name == 'caching')].options[?(@.defaultTtl != '1d')].defaultTtl "1d"
Any CP code $..behaviors[?(@.name == 'cpCode'].options.value.id 12345
CP code set to 12345 $..behaviors[?(@.name == 'cpCode'].options.value[?(@.id == 12345)].id 54321
Edge Redirector, enabled or disabled $..behaviors[?(@.name == 'edgeRedirector')].options.enabled false
Forward rewrite, disabled $..behaviors[?(@.name == 'forwardRewrite'].options[?(@.enabled == false)].enabled true
SureRoute test URL $..behaviors[?(@.name == 'sureRoute')].options.testObjectUrl "/new-object"
ID of custom behavior named customized $..behaviors[?(@.name == 'customBehavior')].options[?(@.name == 'customized')].behaviorId "myCustomRedirect"
Change one of the path match values from /catalog to /shop $..criteria[?(@.name == 'path')].options.value[?(@ == '/catalog')] "/shop"

Tip. All JSONPath expressions evaluate within the rules section of a property configuration, available as JSON from PAPI’s Get a rule tree operation.

Bulk searches

All the steps discussed below focus on a simple task: searching for a set of origin behaviors in the configuration’s top-level rule, changing the origin server’s hostname from old.example.com to new.example.com.

Tip. If you intend to use search results for a bulk update, make sure nobody else is modifying any of the property configurations before launching your search.

The following simplified object shows the type of rule you want to match, available from the Get a rule tree operation’s response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_173136",
    "propertyVersion": 3,
    "etag": "a9dfe78cf93090516bde891d009eaf57",
    "ruleFormat": "v2018-02-27",
    "rules": {
        "name": "default",
        "criteria": [],
        "behaviors": [
            {
                "name": "origin",
                "options": {
                    "httpPort": 80,
                    "enableTrueClientIp": false,
                    "compress": true,
                    "cacheKeyHostname": "ORIGIN_HOSTNAME",
                    "forwardHostHeader": "REQUEST_HOST_HEADER",
                    "hostname": "old.example.com",
                    "originType": "CUSTOMER"
                }
            },
            {
                "name": "cpCode",
                "options": {
                    "value": {
                        "id": 12345,
                        "name": "my CP code"
                    }
                }
            }
        ],
        "children": []
    }
}

Prepare a search

To match the specific hostname value within the origin behavior, you need a JSONPath expression such as the following:

$.behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname

The Sample bulk updates section above lists other types of search, and the Contextual searches section below provides more guidance on the syntax. This expression applies two filters to a set of behaviors on the default rule. The first tests its name, and the second tests the value of its hostname option.

Specify the JSONPath expression as a match in a BulkSearch POST request object, such as the one below:

{
    "bulkSearchQuery": {
        "syntax": "JSONPATH",
        "match": "$.behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname"
    }
}

The bulkSearchQuery area collects all the details about your search. The only available syntax is JSONPATH. Make sure any double-quote characters in the match JSONPath value are escaped with backslashes, otherwise you can use single quotes, as in the example above.

See BulkSearch for more details on this object.

Qualify a search

Specifying additional search criteria can help you narrow down the scope of the search to a smaller set of property configurations.

Suppose you want all origins where the hostname is old.example.com, but only those tracked under a specific CP code. The information you want to test appears within the default rule as the cpCode behavior. Form another JSONPath expression with logic such as the following:

$.behaviors[?(@.name == 'cpCode'].options.value[?(@.id == 12345)].id

Specify this as bulkSearchQualifiers criteria. For the search to produce results, the match criteria must yield results, but only those where the full set of bulkSearchQualifiers also matches the configuration:

{
    "bulkSearchQuery": {
        "syntax": "JSONPATH",
        "match": "$.behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname",
        "bulkSearchQualifiers": [
            "$.behaviors[?(@.name == 'cpCode'].options.value[?(@.id == 12345)].id"
        ]
    }
}

These additional qualifiers test the configuration independently from the match, and the locations they match within the rules do not appear as search results themselves.

Tip. There may be cases where a single match may be able to combine all the logic you want within a single expression. But in some cases, specifying a separate set of bulkSearchQualifiers may allow you to simplify the main match syntax.

Launch a search

To launch the search, POST the BulkSearch object discussed above to this URL:

POST /papi/v1/bulk/rules-search-requests

Add optional contractId or groupId parameters if you want to narrow down the set of results:

POST /papi/v1/bulk/rules-search-requests?contractId=1-1TJZFW&groupId=15166

The response’s Location header, or the response JSON’s bulkSearchLink member, both provide a navigable link to call the next operation. Store this URL path value before proceeding to the next step:

{
    "bulkSearchLink": "/papi/v1/bulk/rules-search-requests/737"
}

For full details on the POST operation, see Bulk search a set of properties.

Note. If you provision an ordinary Akamai API token, search results apply to a single account. Review Getting started for a way to provision your API token to search properties across all your accounts.

Check search results

After launching the bulk search, make a GET call on the link provided in the POST response. For example:

GET /papi/v1/bulk/rules-search-requests/737

For details on this GET operation, see List bulk search results.

The response object reflects back the original request’s bulkSearchQuery, to provide you context to help interpret the additional search results, which span all properties available to you in any account:

{
    "bulkSearchId": 5,
    "searchTargetStatus": "IN_PROGRESS",
    "searchSubmitDate": "2018-01-18T00:00:00Z",
    "searchUpdateDate": "2018-01-18T00:01:00Z",
    "bulkSearchQuery": {
        "syntax": "JSONPATH",
        "match": "$.behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname"
    },
    "results": [
        {
            "propertyId": "prp_15",
            "propertyVersion": 2,
            "stagingStatus": "INACTIVE",
            "productionStatus": "ACTIVE",
            "lastModifiedTime": "2018-01-18T00:00:00Z",
            "matchLocations": [
                "/rules/behaviors/0/options/hostname"
            ]
        }
    ]
}

Check the searchTargetStatus value:

  • If it is either PENDING or IN_PROGRESS, the search results are not yet finalized. Wait some time, then run the GET operation again to poll the result.

  • Once it is COMPLETE, search results are ready. The amount of time it takes to get a set of COMPLETE results depends on the number of properties you’re searching, the size of the configuration, and the complexity of the match expression.

The results include up to three versions for each propertyId:

  • active on the staging network
  • active on the production network
  • most recently modified version

This simplified example features only two search results:

{
    "bulkSearchId": 5,
    "searchTargetStatus": "COMPLETE",
    "searchSubmitDate": "2018-01-18T00:00:00Z",
    "searchUpdateDate": "2018-01-18T00:01:00Z",
    "bulkSearchQuery": {
        "syntax": "JSONPATH",
        "match": "$.behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname"
    },
    "results": [
        {
            "propertyId": "prp_1",
            "propertyVersion": 1,
            "stagingStatus": "ACTIVE",
            "productionStatus": "INACTIVE",
            "lastModifiedTime": "2018-01-18T00:00:00Z",
            "matchLocations": [
                "/rules/behaviors/0/options/hostname"
            ]
        },
        {
            "propertyId": "prp_15",
            "propertyVersion": 2,
            "stagingStatus": "INACTIVE",
            "productionStatus": "ACTIVE",
            "lastModifiedTime": "2018-01-18T00:00:00Z",
            "matchLocations": [
                "/rules/behaviors/0/options/hostname"
            ]
        }
    ]
}

The matchLocations provides a set of JSON Pointer values, whose path expressions locate where within the rules the old.example.com value appears. This example shows a single match location. Other types of search may yield additional matches within the configuration.

Tip. The matchLocations included in the search results do not indicate the current value at each location. If you intend to use the search results to bulk-update your configurations, compare them to the originally specified match to confirm the scope of your initial search is what you intend.

You can use bulk search simply as a research tool, using the propertyId and propertyVersion values to modify individual configurations.

Assuming you want to update the configurations, save the results array, which you will need to bulk patch them. If you want to update currently active versions, you first need to use the data to create a new set of editable property versions.

Bulk versioning

This section shows you how to bulk-create a new set of property versions based on search results discussed above. You only need to bulk-version active properties, because you can’t edit them once you activate them.

Launch a bulk versioning job

Once you have a set of search results, create a new BulkVersion POST object such as the one below. Reflect each pair of propertyId and propertyVersion values from the search results as propertyId and createFromVersion values within the array:

{
    "createPropertyVersions": [
        {
            "propertyId": "prp_1",
            "createFromVersion": 1
        },
        {
            "propertyId": "prp_15",
            "createFromVersion": 2
        }
    ]
}

POST the object to the following URL:

POST /papi/v1/bulk/property-version-creations

Just like the initial bulk search request, the bulk versioning request executes asynchronously, and its results are available in a separate GET operation. The link to the URL is available in the response’s Location header, or in the JSON response’s bulkCreateVersionLink. Store the value:

{
    "bulkCreateVersionLink": "/papi/v1/bulk/property-version-creations/737"
}

Check bulk versioning status

Go ahead and GET the URL from the step above. The GET response reflects back all the originally requested set of createPropertyVersions, but filled out with more data:

{
    "bulkCreateId": 9,
    "bulkCreateVersionsStatus": "IN_PROGRESS",
    "bulkCreateVersionSubmitDate": "2018-01-18T00:00:00Z",
    "bulkCreateVersionUpdateDate": null,
    "createPropertyVersions": [
        {
            "propertyId": "prp_15",
            "createFromVersion": 2,
            "createFromVersionEtag": "343410c585cf67fc",
            "propertyVersion": 3,
            "createVersionStatus": "CREATING",
            "propertyVersionLink": null,
            "etag": null,
            "createVersionSubmitDate": "2018-01-18T00:00:00Z",
            "createVersionUpdateDate": null
        },
        {
            "propertyId": "prp_3",
            "createFromVersion": 10,
            "createFromVersionEtag": "6c7v5c65c6cvcv65",
            "propertyVersion": 11,
            "createVersionsStatus": "CREATED",
            "propertyVersionLink": "/papi/v1/properties/prp_3/versions/11?contractId=1-1TJZFW&groupId=15166",
            "etag": "3333333c33cc333",
            "createVersionSubmitDate": "2018-01-18T00:00:00Z",
            "createVersionUpdateDate": "2018-01-18T00:00:00Z"
        }
    ]
}

Just like the initial bulk search request, you may again need to wait for the entire bulk versioning job to complete. Check the top-level bulkCreateVersionsStatus for a value of COMPLETE. If it’s not yet ready, run the operation again later.

For all newly created versions:

  • Map the original createFromVersion to the newly created propertyVersion, for use in the subsequent bulk patch operation. Note that the version number is not necessarily incremented.

  • Optionally store the new version’s etag value. Including this value in the subsequent bulk patch operation ensures that your update doesn’t overwrite anyone else’s changes. To avoid the issue, make sure to first inform anyone else who may modify the properties that you want to bulk update them.

Bulk patches

Based on the set of search results from the steps above and any new property versions you needed to create, you can now launch a bulk patch to modify them.

Caution. If you run a bulk patch that misconfigures your properties, it can adversely affect the performance of your web content. Make sure to thoroughly test any bulk patches on the staging network before activating on production.

Launch a bulk patch job

Review the results array from the earlier bulk search GET response. You’ll need to build a simple JSON Patch operation for each of the matchLocations, and apply it to the newly created version:

[
    {
        "propertyId": "prp_1",
        "propertyVersion": 1,
        "stagingStatus": "ACTIVE",
        "productionStatus": "INACTIVE",
        "lastModifiedTime": "2018-01-18T00:00:00Z",
        "matchLocations": [
            "/rules/behaviors/0/options/hostname"
        ]
    },
    {
        "propertyId": "prp_15",
        "propertyVersion": 2,
        "stagingStatus": "INACTIVE",
        "productionStatus": "ACTIVE",
        "lastModifiedTime": "2018-01-18T00:00:00Z",
        "matchLocations": [
            "/rules/behaviors/0/options/hostname"
        ]
    }
]

Create a new BulkPatch POST request, such as the one below. For each pairing of property ID and version from the original results, specify an object with:

  • the propertyId.

  • the newly created propertyVersion number, or the original value if no versioning was necessary.

  • an optional etag for any bulk-versioned properties.

From the property ID and version pairings in the original search results, you need the JSON pointer expressions that appear in the matchLocations to build a series of patches with corresponding JSON Patch operations. Pass in the original value from the matchLocations as the path. Also specify the new value you want to change it to. Specify the JSON Patch operation (op) as replace:

{
    "patchPropertyVersions": [
        {
            "propertyId": "prp_15",
            "propertyVersion": 3,
            "etag": "343410c585cf67fc",
            "patches": [
                {
                    "op": "replace",
                    "path": "/rules/behaviors/0/options/hostname",
                    "value": "new.example.com"
                }
            ]
        },
        {
            "propertyId": "prp_3",
            "propertyVersion": 11,
            "etag": "3333333c33cc333",
            "patches": [
                {
                    "op": "replace",
                    "path": "/rules/behaviors/0/options/hostname",
                    "value": "new.example.com"
                }
            ]
        }
    ]
}

Tip. Make sure that the replacement value specifies the same JSON data type as the original match, or the update will fail.

Once you refine your set of patches, POST the object to the URL below:

POST /papi/v1/bulk/rules-patch-requests

See Bulk patch a set of properties for details on the operation. It repeatedly invokes a lower-level Patch a rule tree operation, which you can use to modify an individual configuration.

Again, once you launch the bulk patch process, the response’s Location header and JSON response object provides a navigable link to check on its progress:

{
    "bulkPatchLink": "/papi/v1/bulk/rules-patch-requests/42"
}

Check bulk patch status

Once you have launched a bulk patch request as described above, GET the response’s bulkPatchLink URL to check on progress. For details on this operation, see List bulk-patched properties:

{
    "bulkPatchId": 7,
    "bulkPatchStatus": "COMPLETE",
    "bulkPatchSubmitDate": "2018-01-18T00:00:00Z",
    "bulkPatchUpdateDate": "2018-01-18T01:00:00Z",
    "patchPropertyVersions": [
        {
            "propertyId": "prp_15",
            "propertyVersion": 3,
            "etag": "343410c585cf67fc",
            "patches": [
                {
                    "op": "replace",
                    "path": "/rules/behaviors/0/options/hostname",
                    "value": "new.example.com"
                }
            ],
            "status": "UPDATED",
            "patchSubmitDate": "2018-01-18T00:00:00Z",
            "patchUpdateDate": "2018-01-18T00:00:00Z",
            "propertyVersionRulesLink": "/papi/v1/properties/prp_1/versions/1/rules"
        },
        {
            "propertyId": "prp_3",
            "propertyVersion": 11,
            "patches": [
                {
                    "op": "replace",
                    "path": "/rules/behaviors/0/options/hostname",
                    "value": "new.example.com"
                }
            ],
            "status": "FATAL_ERROR",
            "patchSubmitDate": "2018-01-18T00:00:00Z",
            "patchUpdateDate": "2018-01-18T00:00:00Z",
            "fatalError": "BAD SYNTAX UNABLE TO SAVE"
        }
    ]
}

Following the same pattern of other asynchronous responses, the response reflects back the original set of requested patchPropertyVersions, but with additional status for each property version’s update progress. The bulkPatchStatus reflects the status of the overall bulk patch process. If its value is not yet COMPLETE when you poll the operation, wait some time and call the operation again later.

Tip. Once you complete a single bulk patch operation, you can run additional bulk searches to update other values. From the search results, remove any active property versions. Doing so confines further updates to the set you just modified.

Possible bulk patch errors

Once the bulkPatchStatus of the bulk patch’s GET response is COMPLETE, there may still be problems with individual updates. For each object in the patchPropertyVersions array, check the patchPropertyVersionStatus value:

  • If it is FATAL_ERROR, something prevented the property from updating, and an additional fatalError member provides guidance. The problem may be caused by:

    • invalid JSON Patch syntax
    • an invalid replacement value
    • a mismatching etag digest

    In the example discussed above, patching in a replacement value that’s not a valid hostname would cause a fatal error.

  • If it is UPDATED, and no papiWarnings or papiErrors are present, you can go ahead and activate the property as discussed in the next section.

  • If it is UPDATED but there is a papiErrors array, the property was saved, but you can’t activate it in its current state with errors present. Either modify each configuration individually to remove the error, or remove them from the batch to activate.

  • If it is UPDATED but there is a papiWarnings and with no accompanying papiErrors, you can activate the property in the next step by acknowledging all the warnings. Warnings do not necessarily indicate an actual problem. You can GET the propertyVersionRulesLink URL and scrutinize the warnings from the configuration to research the issue.

For details on the range of errors and warnings that may appear in PAPI configurations, see the Errors section.

Bulk activations

Once you bulk patch a set of property versions, you can bulk activate them.

Launch a bulk activate job

Build a BulkActivation POST object like the one shown below. From the set of patchPropertyVersions you updated earlier, pass in this data:

  • propertyId
  • propertyVersion
  • optional etag value
  • any note you want to include for each property’s activation
  • the network to activate on, either STAGING or PRODUCTION

Tip. Bulk activate to STAGING and test thoroughly on more than one property before bulk activating to PRODUCTION.

In addition to the properties you want to activate, you also need to specify global settings that apply to all the activations. Specify these defaultActivationSettings:

  • a common set of notifyEmails to inform people of changes to activation status.

  • "acknowledgeAllWarnings":true if configurations include any routine warnings.

{
    "defaultActivationSettings": {
        "acknowledgeAllWarnings": true,
        "notifyEmails": [
            "you@example.com",
            "them@example.com"
        ]
    },
    "activatePropertyVersions": [
        {
            "propertyId": "prp_15",
            "propertyVersion": 3,
            "activateFromEtag": "343410c585cf67fc",
            "note": "Testing new origin host for 'prp_15' v3",
            "network": "STAGING"
        },
        {
            "propertyId": "prp_3",
            "propertyVersion": 11,
            "activateFromEtag": "621410b95c8c5f76",
            "note": "Testing new origin host for 'prp_3' v11",
            "network": "STAGING"
        }
    ]
}

Once you have built the BulkActivation object such as the one above, POST it the following URL:

POST /papi/v1/bulk/activations

For details on this operation, see Bulk activate a set of properties

As with all bulk POST operations, the response object includes a URL link to poll for status on the activations. This bulkActivationLink is also available in the response’s Location header:

{
    "bulkActivationLink": "/papi/v1/bulk/activations/311"
}

Note. You are limited to 100 activations for both the staging and production networks for each day within an account. Make sure your bulk activation request does not exceed that limit, which includes conventional non-bulk activation requests over the same period. See Rate and resource limiting for details.

Check bulk activate status

GET the URL link from the response discussed above to check bulk activation progress. (For details on this operation, see List bulk-activated properties.)

As with all bulk operations, the GET response features all the original requested data, but with additional data to reflect the status of the activations. Some of the global defaultActivationSettings are also repeated within each of the activatePropertyVersions:

{
    "bulkActivationId": 234,
    "bulkActivationStatus": "NEW",
    "bulkActivationSubmitDate": "2018-01-18T00:00:00Z",
    "bulkActivationUpdateDate": "2018-01-18T01:00:00Z",
    "defaultActivationSettings": {
        "acknowledgeAllWarnings": true,
        "useFastFallback": false,
        "fastPush": true,
        "notifyEmails": [
            "you@example.com",
            "them@example.com"
        ]
    },
    "activatePropertyVersions": [
        {
            "propertyId": "prp_15",
            "propertyVersion": 3,
            "activateFromEtag": "343410c585cf67fc",
            "note": "Testing new origin host for 'prp_15' v3",
            "network": "STAGING",
            "notifyEmails": [
                "you@example.com",
                "them@example.com"
            ],
            "acknowledgeAllWarnings": true,
            "activationStatus": "ACTIVATED",
            "activationSubmitDate": "2018-01-18T00:00:00Z",
            "activationUpdateDate": "2018-01-18T00:00:00Z",
            "fastPush": true,
            "propertyActivationLink": "/papi/v1/properties/prp_1/activations/act_1",
            "useFastFallback": false,
        },
        {
            "propertyId": "prp_3",
            "propertyVersion": 11,
            "activateFromEtag": "621410b95c8c5f76",
            "note": "Testing new origin host for 'prp_3' v11",
            "network": "STAGING",
            "notifyEmails": [
                "you@example.com",
                "them@example.com"
            ],
            "acknowledgeAllWarnings": true,
            "activationStatus": "ACTIVATING",
            "activationSubmitDate": "2018-01-18T00:00:00Z",
            "activationUpdateDate": null,
            "fastPush": true,
            "propertyActivationLink": "/papi/v1/properties/prp_1/activations/act_2",
            "useFastFallback": false,
        }
    ]
}

As with all of PAPI’s bulk operations, the GET response’s top-level object indicates the status of the overall bulk job. If the bulkActivationStatus is not yet COMPLETE, GET it again later. Once the bulkActivationStatus is COMPLETE, check each activatePropertyVersions object. If the activationStatus is ACTIVATED, the property is serving live traffic. Your bulk update is complete.

Contextual searches

The Sample bulk updates section above briefly summarizes some of the PAPI behaviors you may want to search for in your configuration. This section provides a fuller set of examples showing different techniques to help refine your search.

Examples in the table below demonstrate how to restrict matches to top-level default rules, child rules, or match based on nearby criteria or behaviors. It shows how to match or exclude string values, pattern-match a regular expression, or test boolean, numeric, or array values.

The additional Match errors section below provides further guidance on potential conceptual errors to help you avoid matching content incorrectly.

Match JSONPath syntax
Location within rules
Origin hostname in top-level default rule $.behaviors[?(@.name == 'origin')].options.hostname
Origin hostname in any rule $..behaviors[?(@.name == 'origin')].options.hostname
Origin hostname, only in child rules $..children[*].behaviors[?(@.name == 'origin')].options.hostname
Boolean values
Toggle HTTP/2, when either enabled or disabled $..behaviors[?(@.name == 'http2')].options.enabled
Edge Redirector, disabled $..behaviors[?(@.name == 'edgeRedirector')].options[?(@.enabled == false)].enabled
Edge Redirector, enabled $..behaviors[?(@.name == 'edgeRedirector')].options[?(@.enabled == true)].enabled
Forward Rewrite or Edge Redirector, enabled or disabled $..behaviors[?(@.name == 'forwardRewrite' || @.name == 'edgeRedirector')].options.enabled
String values
Origin hostname of www.example.com $..behaviors[?(@.name == 'origin')].options[?(@.hostname == 'www.example.com')].hostname
Any origin hostname that matches an example.com substring $..behaviors[?(@.name == 'origin')].options[?(@.hostname =~ /example.com/)].hostname
Any origin hostname that starts with www. and ends .com $..behaviors[?(@.name == 'origin')].options[?(@.hostname =~ /www\..*\.com/)].hostname
Default caching TTL $..behaviors[?(@.name == 'caching')].options.defaultTtl
Same, but cached 1 to 9 hours $..behaviors[?(@.name == 'caching' && @.options.defaultTtl =~ /^[1-9]h$/)].options.defaultTtl
Numeric values
Any response code $..behaviors[?(@.name == 'responseCode')].options.statusCode
Response code is 200 $..behaviors[?(@.name == 'responseCode')].options[@.statusCode == 200].statusCode
Error response codes $..behaviors[?(@.name == 'responseCode')].options[?(@.statusCode >= 400)].statusCode
Redirect responses in 3xx range $..behaviors[?(@.name == 'responseCode')].options[?(@.statusCode >= 300 && @.statusCode < 400)].statusCode
Array values
Path criteria match that includes /catalog $..criteria[?(@.name == 'path')].options.value[?(@ == '/catalog')]
All path match values except /catalog $..criteria[?(@.name == 'path')].options.value[?(@ != '/catalog')]
All path match values $..criteria[?(@.name == 'path')].options.value[*]
First path match value $..criteria[?(@.name == 'path')].options.value[0]
Last path match value $..criteria[?(@.name == 'path')].options.value[-1]
Any /catalog path value in the same set as an /about value $..criteria[?(@.name == 'path')].options[?('/about' in @.value)].value[?(@ == '/catalog')]
Any /catalog path value where /blog is not in the same set $..criteria[?(@.name == 'path')].options[?('/blog' nin @.value)].value[?(@ == '/catalog')]
Specific set of path values $..criteria[?(@.name == 'path')].options.value[?(@ == '/catalog' || @ == '/about')]
Relative location
Toggle Image Manager within any rule with image in its name. $..children[?(@.name =~ /[Ii]mage/)].behaviors[?(@.name == 'imageManager')].options.enabled
Toggle an edge redirector within a path match $..children[?(@.criteria[?(@.name == 'path')].behaviors[?(@.name == 'edgeRedirector')].options.enabled
Same, but where one of the specified paths is /catalog $..children[?(@.criteria[?(@.name == 'path' && @.options.value[?(@ == '/catalog')].behaviors[?(@.name == 'edgeRedirector')].options.enabled

Match errors

This section summarizes potential errors you may encounter when crafting search queries. Unlike deeper JSONPath parse errors for which you receive an explicit error response, these conceptual errors may result in an empty set of search results, or far more search results than you intend:

  • Testing a location vs. its value. The first expression below matches all origin hostname values. If you want to change a specific value, make sure to specify it, as in the second expression. Otherwise the range of your search results and subsequent patch operation may be wider than you intend:

    $..behaviors[?(@.name == 'origin')].options.hostname
    $..behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname
    
  • Testing existence vs. truth. The first match expression below tests whether the enabled option exists, not as a shorthand for whether it evaluates as boolean true as in many programming environments. Like the second match expression, it matches both true and false values, likely a wider match than intended. Use the third type of expression to refine the test:

    $..behaviors[?(@.name == 'http2'].options[?(@.enabled)].enabled
    $..behaviors[?(@.name == 'http2'].options.enabled
    $..behaviors[?(@.name == 'http2'].options[?(@.enabled == true)].enabled
    
  • Mismatching type. The data type of any matched value must be the same as that of the value within the rule configuration. The following match yields no results because it matches a 'true' string value rather than true boolean value:

    $..behaviors[?(@.name == 'http2')].options[?(@.enabled == 'true')].enabled
    
  • Mismatching case. String matches and regular expression tests are case-sensitive. The first match below yields no data because the behavior is named cpCode, not cpcode. The second pattern match would yield either name, if you’re not sure:

    $..behaviors[?(@.name == 'cpcode'].options.value.id
    $..behaviors[?(@.name =~ /cp[Cc]ode/].options.value.id
    
  • Object values. PAPI’s implementation of JSONPath does not allow you to test an object’s scalar value directly on the matched node. The first match below fails, but the second succeeds:

    $.behaviors[?(@.name == 'origin')].options.hostname[?(@ == 'old.example.com')]
    $.behaviors[?(@.name == 'origin')].options[?(@.hostname == 'old.example.com')].hostname
    
  • Matches execute within rules. All JSONPath matches execute within a configuration’s set of rules, not the outermost object from the Get a rule tree JSON response. The following match fails to match the top-level default rule, because the expression’s initial rules segment is unnecessary:

    $.rules.behaviors[?(@.name == 'origin')].options.hostname[?(@ == 'old.example.com')]
    

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 with an empty set of hostnames, running List 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/v1/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/v1/properties/prp_173136/versions/3/rules#err_100",
            "behaviorName": "cpCode"
        },
        {
            "type": "/papi/v1/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/v1/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 Fast validation, activation, and fallback 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 Advanced and locked features 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/v1/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 requires you to acknowledge each warning before you activate a property. Pay careful attention to any warnings 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 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/v1/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.
400 search/extra-request-body-fields Only a single key/value pair is allowed in the search request. Learn more.
400 search/missing-request-body-field A required key/value pair is missing from the request. Learn more.
400 search/missing-request-body A request body object is required for the search. Learn more.
400 search/unrecognized-request-body-field The JSON member in the request is unrecognized. Learn more.

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.enhancedtls_module_standard_cert Your contract features the Enhanced TLS module, but the property hostname uses a standard certificate, a potential PCI violation.
hostnames.hostname_contains_underscore Avoid underscore characters in hostnames, which may cause problems for some DNS resolvers.
hostnames.hostname_overlapping_certs Some domains are covered by both Enhanced TLS and Standard TLS certificates. Avoid this unless you are migrating properties.
hostnames.insecure_module_standard_cert Your contract requires the Standard TLS module to select a hostname with a standard certificate.
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.non_enhancedtls_module_enhanced_cert Your contract requires the Enhanced TLS module to select a hostname with an enhanced certificate.
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.secure_property_without_secure_modules Your contract requires secure modules to deploy a 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/cachewipe-error-possible The activation failed because an affected hostname migrated from one account to another. The error response provides details for when you can activate the property.
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.
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.
422 deactivation/not-active-in-production The property is not active on the production network, so you can’t deactivate it.
422 deactivation/not-active-in-staging The property is not active on the staging network, so you can’t deactivate it.
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_badly_formatted_xml The advanced override metadata features invalid XML.
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
400 problem-extracting-contract-group Unable to calculate the contract or group associated with a property, in which case you need to provide both contractId and groupId as query parameters.
403 cpcode/invalid-services The current product does not allow you to create CP codes.
429 cpcode/rate-limit-reached You made too many CP code requests. Try again later.

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.
general_warning The criteria match may negatively affect performance. Test thoroughly on staging before deploying to production.
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.
purge_warning The requestMethod match on AKAMAI_PURGE or AKAMAI_TRANSLATE values requires familiarity with Akamai’s edge content purge system. Test thoroughly on staging before deploying to production.
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 cacheable 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 optimization 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 lists miscellaneous errors:

Code Type Problem
400 arl-data-xml-invalid XML data is invalid. The response indicates which line caused the parse error.
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.
404 custom-behavior-not-found Unable to locate the requested custom behavior.
404 route-not-found Unable to locate the requested resource.
404 user-not-present-to-create-custom-behavior Can’t create a custom behavior not associated with a user.
422 custom-behavior-name-in-use A custom behavior with that name already exists.

The following fallback errors may occur when modifying a rule tree:

Type Description
unknown_message Unknown rule tree validation error.
unknown_validation_type Unknown value error.

Last modified: 10/25/2018