Property Manager API v0 Resources

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

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

API Summary

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

List Groups

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

GET /papi/v0/groups/

Status 200 application/json

Response:

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

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

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

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

List Contracts

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

GET /papi/v0/contracts/

Status 200 application/json

Response:

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

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

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

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

List Products

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

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

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

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

Status 200 application/json

Response:

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

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

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

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

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

List CP Codes

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

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

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

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

Status 200 application/json

Response:

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

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

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

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

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

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

Create a New CP Code

To create a new CP code, you need to associate it with a product. You can assign any CP code within a property’s rule tree as detailed in the 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/v0/cpcodes/{?contractId,groupId}

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

Content-Type: application/json

Request:

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

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

Status 201 application/json

Headers:

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

Response:

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

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

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

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

  4. Build a CpCode POST object.

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

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

Get a CP Code

This operations gets details about a CP code.

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

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

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

Status 200 application/json

Response:

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

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

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

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

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

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

List Edge Hostnames

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

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

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

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

Status 200 application/json

Headers:

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

Response:

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

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

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

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

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

Create a New Edge Hostname

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

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

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

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

Content-Type: application/json

Request:

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

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

Status 201 application/json

Headers:

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

Response:

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

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

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

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

  4. Build an EdgeHostname POST object.

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

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

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

    • Set the domainSuffix to edgesuite.net.

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

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

Enable Traffic for a New Edge Hostname

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

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

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

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

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

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

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

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

Get an Edge Hostname

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

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

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

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

Status 200 application/json

Response:

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

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

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

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

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

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

List Properties

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

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

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

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

Status 200 application/json

Headers:

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

Response:

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

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

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

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

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

Create or Clone a Property

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

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

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

Content-Type: application/json

Request:

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

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

Status 201 application/json

Headers:

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

Response:

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

Gather prerequisites:

  1. List Contracts from /papi/v0/contracts and store the relevant contractId.
  2. List Groups from /papi/v0/groups and store the relevant groupId.
  3. List Products from /papi/v0/products{?contractId} and store the relevant productId with which to enable the property.

To create a property from scratch:

  1. Optionally List Rule Formats from /papi/v0/rule-formats and store the desired feature catalog version.
  2. Build a Property POST object, optionally specifying the rule format, as in the example below.

To clone a property:

  1. List Properties from /papi/v0/properties/{?contractId,groupId} and store the relevant propertyId from the property you want to clone.
  2. List the property’s versions from /papi/v0/properties/{propertyId}/versions/{?contractId,groupId} and select the version you want to clone.
  3. Store the version’s propertyVersion and etag.
  4. Build a Property POST object.
  5. Add a Property.cloneFrom sub-object.

POST the request:

  1. POST the object to /papi/v0/properties/{?contractId,groupId}.
  2. Optionally GET the new property from the response’s propertyLink or Location header.

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

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

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

Get a Property

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

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

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

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

Status 200 application/json

Response:

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

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

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

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

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

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

Remove a Property

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

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

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

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

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

Status 200 application/json

Response:

{
    "message" : "Deletion Successful."
}

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

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

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

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

List Versions

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

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

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

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

Status 200 application/json

Response:

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

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

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

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

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

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

Create a New Version

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

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

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

Content-Type: application/json

Request:

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

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

Status 201 application/json

Headers:

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

Response:

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

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

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

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

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

  5. Build a Property POST object.

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

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

Get a Version

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

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

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

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

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

Status 200 application/json

Headers:

  • Etag: "71573b922a87abc3"

Response:

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

Status 200 text/xml

Response:

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

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

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

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

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

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

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

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

Get the Latest Version

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

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

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

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

Status 302 application/json

Headers:

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

Response:

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

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

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

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

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

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

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

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

List Available Behaviors

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

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

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

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

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

Status 200 application/json

Response:

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

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

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

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

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

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

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

List Available Criteria

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

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

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

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

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

Status 200 application/json

Response:

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

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

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

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

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

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

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

List a Property’s Hostnames

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

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

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

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

Status 200 application/json

Headers:

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

Response:

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

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

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

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

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

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

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

Update a Property’s Hostnames

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

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

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

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

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

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

Content-Type: application/json

Headers:

  • If-Match: "6aed418629b4e5c0"

Request:

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

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

Status 200 application/json

Headers:

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

Response:

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

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

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

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

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

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

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

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

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

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

Get a Rule Tree

This gets the entire rule tree for a property version. See the 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/v0/properties/{propertyId}/versions/{propertyVersion}/rules/{?contractId,groupId}

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

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

Status 200 application/json

Headers:

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

Response:

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

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

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

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

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

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

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

Update Rules to a Newer Set of Features

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

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

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

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

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

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

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

This respresents 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.

As discussed in Renaming Features and Options, 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.

Get a Rule Tree’s Digest

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

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

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

Headers:

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

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

Status 204

Headers:

  • Etag: "a9dfe78cf93090516bde891d009eaf57"

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

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

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

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

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

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

Update a Rule Tree

To write a rule tree to a property version, make a PUT request to the same resource as the GET request that reads it, passing in the rule object in the body of the request. See the 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/v0/properties/{propertyId}/versions/{propertyVersion}/rules/{?contractId,groupId,validateRules}

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

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

Headers:

  • If-Match: "a9dfe78cf93090516bde891d009eaf57"

Request:

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

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

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

Headers:

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

Response:

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

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

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

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

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

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

  5. Optionally get the existing rule tree object.

  6. Modify the rule tree.

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

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

Freeze a Rule Tree’s Feature Set

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

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

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

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

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

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

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

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

Search Properties

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

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

Content-Type: application/json

Request:

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

Status 200 application/json

Response:

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

List Activations

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

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

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

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

Status 200 application/json

Headers:

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

Response:

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

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

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

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

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

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

Activate a Property

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

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

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

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

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

Content-Type: application/json

Request:

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

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

Status 201 application/json

Headers:

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

Response:

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

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

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

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

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

  5. Build an Activation POST object.

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

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

Get an Activation

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

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

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

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

Status 200 application/json

Headers:

  • Retry-After: 600

Response:

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

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

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

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

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

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

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

Cancel a Pending Activation

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

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

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

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

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

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

Status 200 application/json

Response:

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

List Rule Formats

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

GET /papi/v0/rule-formats

Status 200 application/json

Response:

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

Get a Request’s Schema

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

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

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

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

Status 200 application/json

Response:

{
    "type": "object"
}

Get a Rule Format’s Schema

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

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

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

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

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

Status 200 application/json

Response:

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

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

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

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

Get Client Settings

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

GET /papi/v0/client-settings

Status 200 application/json

Response:

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

Update Client Settings

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

PUT /papi/v0/client-settings

Content-Type: application/json

Request:

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

Status 200 application/json

Response:

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

This sets a new default rule format:

  1. List Rule Formats and select the appropriate version.

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

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

Get Build Details

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

GET /papi/v0/build

Status 200 application/json

Response:

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


Last modified: 6/7/2017