Property Manager API 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 below.) 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

Operation Method Endpoint
Groups   (download RAML)
List Groups GET /papi/v1/groups
Contracts   (download RAML)
List Contracts GET /papi/v1/contracts
Products   (download RAML)
List Products GET /papi/v1/products{?contractId}
CP Codes   (download RAML)
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   (download RAML)
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   (download RAML)
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   (download RAML)
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   (download RAML)
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   (download RAML)
Get a Rule Tree GET /papi/v1/properties/{propertyId}/versions/{propertyVersion}/rules{?contractId,groupId,validateRules,validateMode,dryRun}
Update a Rule Tree PUT /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,dryRun}
Property Activations   (download RAML)
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   (download RAML)
Search Properties POST /papi/v1/search/find-by-value
Custom Behaviors   (download RAML)
List Custom Behaviors GET /papi/v1/custom-behaviors
Create a New Custom Behavior POST /papi/v1/custom-behaviors
Get a Custom Behavior GET /papi/v1/custom-behaviors/{behaviorId}
Lock a Custom Behavior DELETE /papi/v1/custom-behaviors/{behaviorId}
Custom Overrides   (download RAML)
List Custom Overrides GET /papi/v1/custom-overrides
Create a New Custom Override POST /papi/v1/custom-overrides
Get a Custom Override GET /papi/v1/custom-overrides/{overrideId}
Lock a Custom Override DELETE /papi/v1/custom-overrides/{overrideId}
Rule Formats   (download RAML)
List Rule Formats GET /papi/v1/rule-formats
Schemas   (download RAML)
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   (download RAML)
Get Client Settings GET /papi/v1/client-settings
Update Client Settings PUT /papi/v1/client-settings
Build   (download RAML)
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: false

Status 200 application/json

Response Body:

{
    "accountId": "act_1-1TJZFB",
    "groups": {
        "items": [
            {
                "groupName": "Example.com-1-1TJZH5",
                "groupId": "grp_15225",
                "contractIds": [
                    "ctr_1-1TJZH5"
                ]
            },
            {
                "groupName": "Test",
                "parentGroupId": "grp_15225",
                "groupId": "grp_15231",
                "contractIds": [
                    "ctr_1-1TJZH5"
                ]
            },
            {
                "groupName": "TomTest",
                "parentGroupId": "grp_15225",
                "groupId": "grp_41443",
                "contractIds": [
                    "ctr_1-1TJZH5"
                ]
            }
        ]
    },
    "accountName": "Example.com"
}
  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 grp_-prefixed groupId.

List Contracts

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

GET /papi/v1/contracts

Headers:

PAPI-Use-Prefixes: false

Status 200 application/json

Response Body:

{
    "contracts": {
        "items": [
            {
                "contractTypeName": "Direct Customer",
                "contractId": "ctr_1-1TJZH5"
            }
        ]
    },
    "accountId": "act_1-1TJZFB"
}
  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 ctr_-prefixed contractId.

List Products

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

GET /papi/v1/products{?contractId}

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

Headers:

PAPI-Use-Prefixes: false
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",
    "products": {
        "items": [
            {
                "productName": "Alta",
                "productId": "prd_Alta"
            }
        ]
    },
    "contractId": "ctr_1-1TJZH5"
}
  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 prd_-prefixed productId.

List CP Codes

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

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

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

Headers:

PAPI-Use-Prefixes: false
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",
    "groupId": "grp_15225",
    "cpcodes": {
        "items": [
            {
                "cpcodeName": "SME WAA",
                "productIds": [
                    "prd_Web_App_Accel"
                ],
                "cpcodeId": "cpc_33190",
                "createdDate": "2015-03-02T15:06:13Z"
            }
        ]
    },
    "contractId": "ctr_1-1TJZFW"
}
  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 cpc_-prefixed cpcodeId.

Create a New CP Code

To create a new CP code, you need to associate it with a product. You can assign any CP code within a property’s rule tree as detailed in the Rules 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: false

Content-Type: application/json

Request Body:

{
    "cpcodeName": "SME WAA",
    "productId": "prd_Web_App_Accel"
}
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: false
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",
    "groupId": "grp_15166",
    "cpcodes": {
        "items": [
            {
                "cpcodeName": "SME WAA",
                "productIds": [
                    "prd_Web_App_Accel"
                ],
                "cpcodeId": "cpc_33190",
                "createdDate": "2015-03-02T15:06:13Z"
            }
        ]
    },
    "contractId": "ctr_1-1TJZFW"
}
  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 and store the relevant cpcodeId.

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

  5. Store the object’s cpc_-prefixed 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: false
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:

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

Content-Type: application/json

Request Body:

{
    "domainSuffix": "edgesuite.net",
    "secure": true,
    "domainPrefix": "www.example.com",
    "productId": "prd_PPP",
    "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: false
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:

{
    "edgeHostnames": {
        "items": [
            {
                "domainSuffix": "edgesuite.net",
                "secure": false,
                "edgeHostnameDomain": "example.com.edgesuite.net",
                "domainPrefix": "example.com",
                "edgeHostnameId": "ehn_887436",
                "mapDetails:serialNumber": 1951,
                "mapDetails:mapDomain": "a1951.g.akamai.net",
                "ipVersionBehavior": "IPV4",
                "productId": "prd_Alta"
            }
        ]
    },
    "accountId": "act_1-1TJZFB",
    "groupId": "grp_15225",
    "contractId": "ctr_1-1TJZH5"
}
  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: false
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": [
            {
                "productionVersion": null,
                "assetId": "aid_101",
                "propertyName": "example.com",
                "note": "Notes about example.com",
                "contractId": "ctr_1-1TJZH5",
                "latestVersion": 2,
                "accountId": "act_1-1TJZFB",
                "groupId": "grp_15225",
                "propertyId": "prp_175780",
                "stagingVersion": 1
            },
            {
                "productionVersion": null,
                "assetId": "aid_101",
                "propertyName": "m.example.com",
                "note": "Notes about m.example.com",
                "contractId": "ctr_1-1TJZH5",
                "latestVersion": 1,
                "accountId": "act_1-1TJZFB",
                "groupId": "grp_15225",
                "propertyId": "prp_175781",
                "stagingVersion": null
            }
        ]
    }
}
  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: false

Content-Type: application/json

Request Body:

{
    "propertyName": "my.new.property.com",
    "cloneFrom": {
        "copyHostnames": true,
        "version": 2,
        "propertyId": "prp_175780",
        "cloneFromVersionEtag": "a9dfe78cf93090516bde891d009eaf57"
    },
    "productId": "prd_Alta"
}
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, as in the example below.

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: 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, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group, optional for this operation. See Data Conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Response Body:

{
    "properties": {
        "items": [
            {
                "productionVersion": null,
                "assetId": "aid_101",
                "propertyName": "example.com",
                "note": "Notes about example.com",
                "contractId": "ctr_1-1TJZH5",
                "latestVersion": 2,
                "accountId": "act_1-1TJZFB",
                "groupId": "grp_15225",
                "propertyId": "prp_175780",
                "stagingVersion": 1
            }
        ]
    }
}
  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, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group, optional for this operation. 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: 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, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group, optional for this operation. See Data Conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Response Body:

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

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, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group, optional for this operation. 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: 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.
propertyVersion Integer 3 Property’s incremental version number.
Optional Query Parameters
contractId String ctr_1–1TJZFW Unique identifier for the contract, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group, optional for this operation. See Data Conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Headers:

Etag: "71573b922a87abc3"

Response Body:

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

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 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: 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.
propertyVersion Integer 3 Property’s incremental version number.
Optional Query Parameters
contractId String ctr_1–1TJZFW Unique identifier for the contract, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group, optional for this operation. See Data Conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Response Body:

{
    "contractId": "ctr_1-1TJZH5",
    "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"
            }
        ]
    },
    "ruleFormat": "v2015-08-08",
    "groupId": "grp_15225",
    "productId": "prd_Alta"
}
  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 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: 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.
propertyVersion Integer 3 Property’s incremental version number.
Optional Query Parameters
contractId String ctr_1–1TJZFW Unique identifier for the contract, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group, optional for this operation. See Data Conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Response Body:

{
    "contractId": "ctr_1-1TJZH5",
    "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"
            }
        ]
    },
    "ruleFormat": "v2015-08-08",
    "groupId": "grp_15225",
    "productId": "prd_Alta"
}
  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: 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
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, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group, optional for this operation. 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: 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.
propertyVersion Integer 3 Property’s incremental version number.
Optional Query Parameters
contractId String ctr_1–1TJZFW Unique identifier for the contract, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group, optional for this operation. 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 Validation and Activation Time 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:

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

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

Content-Type: application/json

Request Body:

[
    {
        "cnameTo": "example.com.edgesuite.net",
        "cnameFrom": "m.example.com",
        "cnameType": "EDGE_HOSTNAME"
    },
    {
        "cnameFrom": "example3.com",
        "edgeHostnameId": "ehn_895824",
        "cnameType": "EDGE_HOSTNAME"
    }
]
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, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group, optional for this operation. 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 Validation and Activation Time for details on the delays this might avoid.

Status 200 application/json

Headers:

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

Response Body:

{
    "propertyVersion": 1,
    "etag": "6aed418629b4e5c0",
    "contractId": "ctr_1-1TJZH5",
    "hostnames": {
        "items": [
            {
                "cnameTo": "example.com.edgesuite.net",
                "cnameFrom": "example.com",
                "edgeHostnameId": "ehn_895822",
                "cnameType": "EDGE_HOSTNAME"
            },
            {
                "cnameTo": "m.example.com.edgesuite.net",
                "cnameFrom": "m.example.com",
                "edgeHostnameId": "ehn_895833",
                "cnameType": "EDGE_HOSTNAME"
            }
        ]
    },
    "groupId": "grp_15225",
    "propertyId": "prp_175780",
    "accountId": "act_1-1TJZFB"
}
  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 Validation and Activation Time 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 Validation and Activation Time for guidance on when to defer validation. See JSON Problems for information on how validation data is embedded within the response object.

Get a Rule Tree

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

GET /papi/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: 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.
propertyVersion Integer 3 Property’s incremental version number.
Optional Query Parameters
contractId String ctr_1–1TJZFW Unique identifier for the contract, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
dryRun Boolean true Allow for a dry run. This means that we do not save if set to true. Defaults to false. Incompatible with validateRules = false and dryRun = true.
groupId String grp_15166 Unique identifier for the group, optional for this operation. See Data Conventions for details on omitting the value’s grp_ prefix.
validateMode Enumeration fast Validate modes enable either fast validation (json check) or full validation (json and xml check). values are either full or fast. Default is full validation.
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 Validation and Activation Time for details on the delays this might avoid.

Status 200 */*

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:

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

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

  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 Debug 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 Rules section for details on the rule tree’s structure. Use this operation also to freeze a set of rules to a rule format version to ensure no change in a deployed activation’s behavior. Set the validateRules query parameter to false to bypass a set of validation tests that may significantly slow this operation’s execution time. See Validation and Activation Time for guidance on when to defer validation. See JSON Problems for information on how validation data is embedded within the response object.

PUT /papi/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: */*

Request Body:

{
    "rules": {
        "name": "default",
        "children": [
            {
                "behaviors": [
                    {
                        "name": "caching",
                        "behavior": "max-age",
                        "ttl": "1m"
                    }
                ],
                "criteriaMustSatisfy": "all",
                "name": "Handle /my-path",
                "criteria": [
                    {
                        "name": "path",
                        "value": [
                            "/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, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
dryRun Boolean true Allow for a dry run. This means that we do not save if set to true. Defaults to false. Incompatible with validateRules = false and dryRun = true.
groupId String grp_15166 Unique identifier for the group, optional for this operation. See Data Conventions for details on omitting the value’s grp_ prefix.
validateMode Enumeration fast Validate modes enable either fast validation (json check) or full validation (json and xml check). values are either full or fast. Default is full validation.
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 Validation and Activation Time for details on the delays this might avoid.

Status 200 */*

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:

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

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

  1. 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 Validation and Activation Time 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 described above: to assign a specific rule format’s feature set to a rule tree. See also Freeze a Rule Tree’s Feature Set to increment the versioned set of rule format features that are assigned to a rule tree.

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

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

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

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

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, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
dryRun Boolean true Allow for a dry run. This means that we do not save if set to true. Defaults to false. Incompatible with validateRules = false and dryRun = true.
groupId String grp_15166 Unique identifier for the group, optional for this operation. See Data Conventions for details on omitting the value’s grp_ prefix.
validateMode Enumeration fast Validate modes enable either fast validation (json check) or full validation (json and xml check). values are either full or fast. Default is full validation.
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 Validation and Activation Time 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: 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, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group, optional for this operation. See Data Conventions for details on omitting the value’s grp_ prefix.

Status 200 application/json

Response Body:

{
    "activations": {
        "items": [
            {
                "status": "ACTIVE",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ],
                "network": "STAGING",
                "propertyName": "example.com",
                "propertyVersion": 1,
                "note": "Sample activation",
                "activationId": "atv_1696985",
                "submitDate": "2014-03-05T02:22:12Z",
                "activationType": "ACTIVATE",
                "propertyId": "prp_173136",
                "updateDate": "2014-03-04T21:12:57Z"
            },
            {
                "status": "ACTIVE",
                "propertyId": "prp_173136",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ],
                "network": "PRODUCTION",
                "fmaActivationState": "steady",
                "propertyName": "example.com",
                "propertyVersion": 1,
                "note": "Sample activation",
                "activationId": "atv_1696986",
                "submitDate": "2014-03-02T02:22:12Z",
                "activationType": "ACTIVATE",
                "fallbackInfo": {
                    "steadyStateTime": 1506448172,
                    "canFastFallback": true,
                    "fallbackVersion": 10,
                    "fastFallbackExpirationTime": 1506451772,
                    "fastFallbackAttempted": false,
                    "fastFallbackRecoveryState": null
                },
                "updateDate": "2014-03-01T21:12:57Z"
            }
        ]
    },
    "accountId": "act_1-1TJZFB",
    "groupId": "grp_15225",
    "contractId": "ctr_1-1TJZH5"
}
  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: false

Content-Type: application/json

Request Body:

{
    "notifyEmails": [
        "you@example.com",
        "them@example.com"
    ],
    "network": "STAGING",
    "acknowledgeWarnings": [
        "msg_baa4560881774a45b5fd25f5b1eab021d7c40b4f"
    ],
    "propertyVersion": 1,
    "note": "Sample activation",
    "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, optional for this operation. See Data Conventions for details on omitting the value’s ctr_ prefix.
groupId String grp_15166 Unique identifier for the group, optional for this operation. 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: 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.
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:

{
    "activations": {
        "items": [
            {
                "status": "PENDING",
                "propertyId": "prp_173136",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ],
                "network": "STAGING",
                "fmaActivationState": "steady",
                "propertyName": "example.com",
                "propertyVersion": 1,
                "note": "Sample activation",
                "activationId": "atv_1696985",
                "submitDate": "2014-03-02T02:22:12Z",
                "activationType": "ACTIVATE",
                "fallbackInfo": {
                    "steadyStateTime": 1506448172,
                    "canFastFallback": true,
                    "fallbackVersion": 10,
                    "fastFallbackExpirationTime": 1506451772,
                    "fastFallbackAttempted": false,
                    "fastFallbackRecoveryState": null
                },
                "updateDate": "2014-03-01T21:12:57Z"
            }
        ]
    },
    "accountId": "act_1-1TJZFB",
    "groupId": "grp_15225",
    "contractId": "ctr_1-CONTRACT"
}
  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: 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.
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": [
            {
                "status": "ABORTED",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ],
                "network": "STAGING",
                "propertyName": "example.com",
                "propertyVersion": 1,
                "note": "Sample activation cancellation",
                "activationId": "atv_1696985",
                "submitDate": "2014-03-02T02:22:12Z",
                "activationType": "ACTIVATE",
                "updateDate": "2014-03-01T21:12:57Z",
                "groupId": "grp_15225",
                "propertyId": "prp_173136",
                "accountId": "act_1-1TJZFB"
            }
        ]
    }
}

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.

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

Headers:

PAPI-Use-Prefixes: false

Content-Type: application/json

Request Body:

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

Status 200 application/json

Response Body:

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

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: false

Status 200 application/json

Response Body:

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

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: false
Parameter Type Sample Description
URL Parameters
behaviorId String cbe_12345 Unique identifier for the custom behavior.

Status 200 application/json

Response Body:

{
    "customBehaviors": {
        "items": [
            {
                "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>",
                "updatedByUser": "jsikkela",
                "displayName": "Custom Download Receipt",
                "description": "Setting custom download receipt. Uses PMUSER_LOG variable.",
                "updatedDate": "2017-04-24T12:34:56Z",
                "behaviorId": "cbe_12345",
                "name": "DLR"
            }
        ]
    }
}

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: false

Status 200 application/json

Response Body:

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

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: false
Parameter Type Sample Description
URL Parameters
overrideId String cbo_12345 Unique identifier for the custom override.

Status 200 application/json

Response Body:

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

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: false

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/EdgeHostnamesPostRequestV0.json

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

Status 200 application/json

Response Body:

{
    "type": "object"
}

Get a Rule Format’s Schema

Get the JSON schema for the given product and rule format, which you can use to validate a rule tree object. Note 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:

{
    "required": [
        "rules"
    ],
    "type": "object",
    "properties": {
        "rules": {
            "type": "object"
        }
    }
}
  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:

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

Last modified: 10/27/2017