The Property Manager API

NOTE: This most recent API version 1 supersedes the earlier beta version 0. Upgrade to this new version of the API at your earliest opportunity, mainly by updating to v1 in all request URLs. Version 1 is backwards compatible with v0, so your code will work as before, but you need to upgrade to v1 to take advantage of many upcoming features. A deprecation notice for PAPI v0 will be posted in early July, 2017. The v0 endpoints will continue to work until January, 2018. Use this v1 API guide as your authoritative source of information for any new features.

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.

Getting Started

Before using PAPI for the first time:

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

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

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

  • Review the API’s Known Issues.

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

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

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

PAPI Concepts

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

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

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

  • 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 cancel an activation shortly after enabling it, making it the only PAPI object you can delete.

  • 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 Criteria Reference for information on all criteria the API makes available, and see the Rules 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 Behaviors Reference for information on all behaviors the API makes available, and see the Rules section for instructions on how to arrange them within JSON payloads.)

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

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

  • Advanced Features: Most PAPI features translate to edge metadata in clearly prescribed ways. Functionality that falls outside what these predefined behaviors and criteria can do may be implemented as customized metadata. Advanced features are read-only, and require Akamai Professional Services to configure for you. In addition, you may request any feature with sensitive data to be locked for you. (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 and 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 over HTTP or over secure HTTPS. For example, your source hostname corresponds by default to the edge hostname 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.

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 Behaviors and Criteria sections. For documentation 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 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 always specify these IDs as input parameters or JSON data with or without the prefixes.

    There are two exceptions. Rule trees that specify cbe_ for a custom behavior’s behaviorId, and cbo_ for a custom override’s overrideId, must retain 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 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

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

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

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

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

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

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

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

PAPI reports the following set of contextual HTTP headers:

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

Concurrency Control

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

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

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

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

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

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

PAPI 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 and Activation

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

Last modified: 4/3/2018