CP Codes and Reporting Groups API v1

Manages the Content Provider codes (CP codes) and reporting groups to track and report on web traffic.

Learn more:


Overview

The CP Codes and Reporting Groups API offers a programmatic interface to manage CP codes and reporting groups. It also details contracts and products associated with each CP code, and contracts and CP codes associated with each reporting group. Knowing these associations lets you break down your invoices and reports by reporting groups rather than by contracts or products only. You can sort and retrieve CP code and reporting group details available in your contract using either a CP code or reporting group ID.

The CP Code and Reporting Group API lets you:

  • List and update CP codes. Note: If you want to create CP codes, use the Property Manager API which automatically assigns them to the correct product and contract. CP code deletion is unavailable at this time.

  • Create, delete, list, and update reporting groups.

Who should use this API

Developers, DevOps, and operations personnel use this API as an alternative to using Luna Control Center.

Getting started

To configure this API for the first time:

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

  • To enable this API, choose the API service named CPcode and Reporting group (CPRG), and set the access level to READ WRITE.

  • To use this API, you need to add one of the following roles:

    • CP Code - Edit CP Code Information

    • CP Code - View CP Code Information

    • CPCode Rep Group - All privileges

    • CPCode Rep Group - Edit/View

    Use the Identity and Access Management application. You can also add these roles programmatically with the Identity Management: User Administration API.

  • To use this API, you need to have a READ access level to the Property Manager API.

Concepts

You deal with various conceptual objects when interacting with the CP Codes and Reporting Group API.

  • Account. An account key that Akamai customers use to access all their services. While administrators may have access to more than one account, in general they provision all their web assets under a single account.

  • Contract. The level of access that depends on the contracts your Luna Control Center username is associated with. If your username is not associated with the contractId you select, then the request fails. Each account features one or more contracts, each of which has a fixed term of service during which specified Akamai products and modules are active.

  • Reporting group. A Logical grouping of content provider (CP) codes that consolidates billing for a contract. Without reporting groups, reports in the Billing Center are broken down by contracts and products only.

  • Content Provider (CP) code. A unique identifier assigned to each customer to track and report on a set of traffic served over the Akamai network. It is primarily used for billing, reporting, and access control. A customer and a single contract may each have multiple CP codes.

  • High watermark limit. By default, the maximum number of CP codes or reporting groups allowed for an account. Each contract associated with an account inherits the account’s limit, but the total objects created in all associated contracts can’t exceed the account’s limit. For example, each contract associated with an account having a 100 CP code limit also has a limit of 100 CP codes. Having said that, the total number of CP codes that can be added to all these contracts is still 100. Note that high watermark limit may also refer to the maximum number of CP codes or reporting groups allowed for a contract if the contract’s limit overrides its account limit. To increase the limit, contact your account representative.

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List CP codes GET /cprg/v1/cpcodes{?contractId,groupId,productId,name}
List details of a CP code GET /cprg/v1/cpcodes/{cpcodeId}
Update a CP code PUT /cprg/v1/cpcodes/{cpcodeId}
List watermark limits for CP codes GET /cprg/v1/cpcodes/contracts/{contractId}/watermark-limits
List reporting groups GET /cprg/v1/reporting-groups{?contractId,groupId,name,cpcodeId}
Create a reporting group POST /cprg/v1/reporting-groups
List details of a reporting group GET /cprg/v1/reporting-groups/{reportingGroupId}
Update a reporting group PUT /cprg/v1/reporting-groups/{reportingGroupId}
Delete a reporting group DELETE /cprg/v1/reporting-groups/{reportingGroupId}
List products within a reporting group GET /cprg/v1/reporting-groups/{reportingGroupId}/products
List watermark limits for reporting groups GET /cprg/v1/reporting-groups/contracts/{contractId}/watermark-limits

List CP codes

This operation lists detailed information about CP codes available within your account and contract paring.

GET /cprg/v1/cpcodes{?contractId,groupId,productId,name}

Sample: /cprg/v1/cpcodes?contractId=1-ABC382&groupId=12345&productId=AdaptiveMediaDelivery%3A%3AAdaptiveMediaDelivery&name=Adaptive%20Media%20Delivery

Parameter Type Sample Description
Optional query parameters
contractId String 1-ABC382 The identifier for the contract to filter data by.
groupId String 12345 The identifier for the reporting group to filter data by.
name String Adaptive Media Delivery The name of the CP code to filter data by.
productId String AdaptiveMediaDelivery::AdaptiveMediaDelivery The identifier for the product or service to filter data by.

Status 200 application/json

Response Body:

{
    "cpcodes": [
        {
            "cpcodeId": 123456,
            "cpcodeName": "CPC XYZ",
            "purgeable": true,
            "accountId": "act_1-1TGTG",
            "defaultTimezone": "GMT 0 (Greenwich Mean Time)",
            "overrideTimezone": {
                "timezoneId": "0",
                "timezoneValue": "GMT 0 (Greenwich Mean Time)"
            },
            "type": "Regular",
            "contracts": [
                {
                    "contractId": "ctr_004W",
                    "status": "ongoing"
                }
            ],
            "products": [
                {
                    "productId": "AdvSite::Reporter",
                    "productName": "Monitor site advance"
                }
            ],
            "accessGroup": {
                "groupId": 9760,
                "contractId": "ctr_004W"
            }
        },
        {
            "cpcodeId": 67890,
            "cpcodeName": "CPC SME",
            "purgeable": true,
            "accountId": "act_1-1TGTG",
            "defaultTimezone": "GMT 0 (Greenwich Mean Time)",
            "overrideTimezone": {
                "timezoneId": "0",
                "timezoneValue": "GMT 0 (Greenwich Mean Time)"
            },
            "type": "Regular",
            "contracts": [
                {
                    "contractId": "ctr_004W",
                    "status": "ongoing"
                }
            ],
            "products": [
                {
                    "productId": "Dev::Cloud",
                    "productName": "Cloud development CD"
                }
            ],
            "accessGroup": {
                "groupId": 9760,
                "contractId": "ctr_004W"
            }
        }
    ]
}

List details of a CP code

This operation lists detailed information about a specific CP code, including its type, name, time zone, and the account it’s assigned to. It also lists the access control group that the CP code belongs to and the contracts and products assigned to this CP code.

GET /cprg/v1/cpcodes/{cpcodeId}

Sample: /cprg/v1/cpcodes/678263

Parameter Type Sample Description
URL parameters
cpcodeId Integer 678263 The identifier for the CP code.

Status 200 application/json

Response Body:

{
    "cpcodeId": 123456,
    "cpcodeName": "CPC XYZ",
    "purgeable": true,
    "accountId": "act_1-1TGTG",
    "defaultTimezone": "GMT 0 (Greenwich Mean Time)",
    "overrideTimezone": {
        "timezoneId": "0",
        "timezoneValue": "GMT 0 (Greenwich Mean Time)"
    },
    "type": "Regular",
    "contracts": [
        {
            "contractId": "ctr_004W",
            "status": "ongoing"
        }
    ],
    "products": [
        {
            "productId": "AdvSite::Reporter",
            "productName": "Monitor site advance"
        }
    ],
    "accessGroup": {
        "groupId": 9760,
        "contractId": "ctr_004W"
    }
}
  1. List CP codes and store the appropriate cpcodeId.

  2. Make a GET request to /cprg/v1/cpcodes/{cpcodeId}.

Update a CP code

This operation allows you to modify a specific CP code. You should only modify a CP code’s name, time zone, and purgeable member.

PUT /cprg/v1/cpcodes/{cpcodeId}

Sample: /cprg/v1/cpcodes/678263

Content-Type: application/json

Request Body:

{
    "cpcodeId": 123456,
    "cpcodeName": "CPC XYZ",
    "contracts": [
        {
            "contractId": "ctr_004W"
        }
    ],
    "products": [
        {
            "productId": "PPPL::ABC"
        },
        {
            "productId": "AdvSite::Reporter"
        }
    ]
}
Parameter Type Sample Description
URL parameters
cpcodeId Integer 678263 The identifier for the CP code.

Status 200 application/json

Response Body:

{
    "cpcodeId": 123456,
    "cpcodeName": "CPC XYZ",
    "purgeable": true,
    "accountId": "act_1-1TGTG",
    "defaultTimezone": "GMT 0 (Greenwich Mean Time)",
    "overrideTimezone": {
        "timezoneId": "0",
        "timezoneValue": "GMT 0 (Greenwich Mean Time)"
    },
    "type": "Regular",
    "contracts": [
        {
            "contractId": "ctr_004W",
            "status": "ongoing"
        }
    ],
    "products": [
        {
            "productId": "Core::Analyzer",
            "productName": "Core utility JL"
        }
    ],
    "accessGroup": {
        "groupId": 9760,
        "contractId": "ctr_004W"
    }
}
  1. List CP codes and store the appropriate cpcodeId.

  2. Get the details of the CP code by making a GET request to /cprg/v1/cpcodes/{cpcodeId}.

  3. Prepare a PUT request based on the CP code members table.

  4. Update the CP code’s members. You should only update the cpcodeName, purgeable, and overrideTimzone members.

  5. Make a PUT request to /cprg/v1/cpcodes/{cpcodeId}.

List watermark limits for CP codes

This operation lists a watermark limit for CP codes for the account associated within a specific contract.

GET /cprg/v1/cpcodes/contracts/{contractId}/watermark-limits

Sample: /cprg/v1/cpcodes/contracts/1-ABC123/watermark-limits

Parameter Type Sample Description
URL parameters
contractId String 1-ABC123 The identifier for the contract for which you want to check watermark limits.

Status 200 application/json

Response Body:

{
    "limit": 5000,
    "currentCapacity": 3500,
    "limitType": "account"
}
  1. List contracts and store the appropriate contractId.

  2. Make a GET request to /cprg/v1/cpcodes/contracts/{contractId}/watermark-limits.

List reporting groups

This operation lists detailed information about reporting groups available within your account and contract paring.

GET /cprg/v1/reporting-groups{?contractId,groupId,name,cpcodeId}

Sample: /cprg/v1/reporting-groups?contractId=1-ABC382&groupId=12345&name=JustAnExampleName&cpcodeId=34567

Parameter Type Sample Description
Optional query parameters
contractId String 1-ABC382 The identifier for the contract to filter data by.
cpcodeId String 34567 The identifier for the CP code to filter data by.
groupId String 12345 The identifier for the reporting group to filter data by.
name String JustAnExampleName The name of the reporting group to filter data by.

Status 200 application/json

Response Body:

{
    "reporting-groups": [
        {
            "reportingGroupId": 101010,
            "reportingGroupName": "Region XYZ",
            "contracts": [
                {
                    "contractId": "ctr_1Q004",
                    "cpcodes": [
                        {
                            "cpcodeId": 12345,
                            "cpcodeName": "CPC XYZ"
                        }
                    ]
                }
            ],
            "accessGroup": {
                "groupId": 9760,
                "contractId": "ctr_1Q004"
            }
        },
        {
            "reportingGroupId": 101011,
            "reportingGroupName": "Region gLobal XYZ",
            "contracts": [
                {
                    "contractId": "ctr_1Q004",
                    "cpcodes": [
                        {
                            "cpcodeId": 67890,
                            "cpcodeName": "CPC SME"
                        },
                        {
                            "cpcodeId": 98765,
                            "cpcodeName": "CPC Global"
                        }
                    ]
                }
            ],
            "accessGroup": {
                "groupId": 9760,
                "contractId": "ctr_1Q0042"
            }
        }
    ]
}

Create a reporting group

This operation allows you to create a reporting group. The reporting group’s name must be unique within an account. The location header in the response provides a relative path to the created reporting group.

POST /cprg/v1/reporting-groups

Content-Type: application/json

Request Body:

{
    "reportingGroupName": "Region XYZ",
    "accessGroup": {
        "groupId": 9760,
        "contractId": "ctr_1Q004"
    },
    "contracts": [
        {
            "contractId": "ctr_1Q004",
            "cpcodes": [
                {
                    "cpcodeId": 12345,
                    "cpcodeName": "CPC XYZ"
                },
                {
                    "cpcodeId": 67890,
                    "cpcodeName": "CPC SME"
                }
            ]
        }
    ]
}

Status 201 application/json

Headers:

Location: /cprg/v2/reporting-groups/1234

Response Body:

{
    "reportingGroupId": 101010,
    "reportingGroupName": "Region XYZ",
    "description": "Region XYZ",
    "contracts": [
        {
            "contractId": "ctr_004W",
            "cpcodes": [
                {
                    "cpcodeId": 12345,
                    "cpcodeName": "CPC XYZ"
                },
                {
                    "cpcodeId": 67890,
                    "cpcodeName": "CPC SME"
                }
            ]
        }
    ],
    "accessGroup": {
        "groupId": 9760,
        "contractId": "ctr_004W"
    }
}
  1. List contracts and store the appropriate contractId.

  2. List CP codes and store the appropriate cpcodeId values.

  3. List groups and store the appropriate groupId.

  4. Prepare a POST request based on the reporting group members table.

  5. Make a POST request to /cprg/v1/reporting-groups.

List details of a reporting group

This operation lists detailed information about a specific reporting group, including its name and the access control group that it belongs to. It also lists the contracts and CP codes assigned to the reporting group.

GET /cprg/v1/reporting-groups/{reportingGroupId}

Sample: /cprg/v1/reporting-groups/23456

Parameter Type Sample Description
URL parameters
reportingGroupId Integer 23456 The identifier for the reporting group.

Status 200 application/json

Response Body:

{
    "reportingGroupId": 101010,
    "reportingGroupName": "Region XYZ",
    "description": "Region XYZ",
    "contracts": [
        {
            "contractId": "ctr_004W",
            "cpcodes": [
                {
                    "cpcodeId": 12345,
                    "cpcodeName": "CPC XYZ"
                },
                {
                    "cpcodeId": 67890,
                    "cpcodeName": "CPC SME"
                }
            ]
        }
    ],
    "accessGroup": {
        "groupId": 9760,
        "contractId": "ctr_004W"
    }
}
  1. List reporting groups and store the appropriate reportingGroupId.

  2. Make a GET request to /cprg/v1/reporting-groups/{reportingGroupId}.

Update a reporting group

This operation allows you to modify a specific reporting group. You should only modify a reporting group’s name and assigned CP codes.

PUT /cprg/v1/reporting-groups/{reportingGroupId}

Sample: /cprg/v1/reporting-groups/23456

Content-Type: application/json

Request Body:

{
    "reportingGroupId": 101010,
    "reportingGroupName": "Region XYZ",
    "description": "Region XYZ",
    "contracts": [
        {
            "contractId": "ctr_1Q004",
            "cpcodes": [
                {
                    "cpcodeId": 12345,
                    "cpcodeName": "CPC XYZ"
                },
                {
                    "cpcodeId": 67890,
                    "cpcodeName": "CPC SME"
                }
            ]
        }
    ]
}
Parameter Type Sample Description
URL parameters
reportingGroupId Integer 23456 The identifier for the reporting group.

Status 200 application/json

Response Body:

{
    "reporting-group": {
        "reportingGroupId": 101010,
        "reportingGroupName": "Region XYZ",
        "description": "Region XYZ",
        "contracts": [
            {
                "contractId": "ctr_1Q004",
                "cpcodes": [
                    {
                        "cpcodeId": 12345,
                        "cpcodeName": "CPC XYZ"
                    },
                    {
                        "cpcodeId": 67890,
                        "cpcodeName": "CPC SME"
                    }
                ]
            }
        ],
        "accessGroup": {
            "groupId": 9760,
            "contractId": "ctr_1Q004"
        }
    }
}
  1. List reporting groups and store the appropriate reportingGroupId.

  2. Get the details of the reporting group by making a GET request to /cprg/v1/reporting-groups/{reportingGroupId}.

  3. Prepare a PUT request based on the reporting group members table.

  4. Update the reporting group’s members. You should only update the reportingGroupName and cpcodes members.

  5. Make a PUT request to cprg/v1/reporting-groups/{reportingGroupId}.

Delete a reporting group

This operation deletes a specific reporting group.

DELETE /cprg/v1/reporting-groups/{reportingGroupId}

Sample: /cprg/v1/reporting-groups/23456

Parameter Type Sample Description
URL parameters
reportingGroupId Integer 23456 The identifier for the reporting group.

Status 201

List products within a reporting group

This operation lists products and services assigned to a specific reporting group.

GET /cprg/v1/reporting-groups/{reportingGroupId}/products

Sample: /cprg/v1/reporting-groups/23456/products

Parameter Type Sample Description
URL parameters
reportingGroupId Integer 23456 The identifier for the reporting group.

Status 200 application/json

Response Body:

{
    "products": [
        {
            "productId": "PPPL::ABC",
            "productName": "Performance PPL ABC "
        },
        {
            "productId": "Core::Analyzer",
            "productName": "Core utility JL"
        },
        {
            "productId": "Dev::Cloud",
            "productName": "Cloud development CD"
        },
        {
            "productId": "AdvSite::Reporter",
            "productName": "Monitor site advance"
        }
    ]
}
  1. List reporting groups and store the appropriate reportingGroupId.

  2. Make a GET request to /cprg/v1/reporting-groups/{reportingGroupId}/products.

List watermark limits for reporting groups

This operation lists a watermark limit for reporting groups available within a specific contract.

GET /cprg/v1/reporting-groups/contracts/{contractId}/watermark-limits

Sample: /cprg/v1/reporting-groups/contracts/1-ABC123/watermark-limits

Parameter Type Sample Description
URL parameters
contractId String 1-ABC123 The identifier for the contract for which you want to check watermark limits.

Status 200 application/json

Response Body:

{
    "limit": 100,
    "currentCapacity": 25,
    "limitType": "account"
}
  1. List contracts to and store the appropriate contractId.

  2. Make a GET request to /cprg/v1/reporting-groups/contracts/{contractId}/watermark-limits.

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

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

CpCode

Contains the request members that you can specify when updating a CP code. You should only modify a CP code’s name, time zone, and purgeable member. Modifying other members results in a 400 error response and causes the request to fail.

Download schema: cpcode.json, update-cpcode-request.json

Sample PUT request:

{
    "cpcodeId": 123456,
    "cpcodeName": "CPC XYZ",
    "contracts": [
        {
            "contractId": "ctr_004W"
        }
    ],
    "products": [
        {
            "productId": "PPPL::ABC"
        },
        {
            "productId": "AdvSite::Reporter"
        }
    ]
}

CpCode members

Member Type GET PUT Description
accountId String The identifier for an account assigned to the CP code.
contracts CpCode.contracts[] A collection of contracts assigned to the CP code.
cpcodeId Integer Read-only. The identifier for the CP code.
cpcodeName String The descriptive label for the CP code.
defaultTimezone String Read-only. The default GMT time zone assigned to the CP code.
overrideTimezone CpCode.overrideTimezone The GMT time zone that overrides the default GMT time zone assigned to the CP code.
products CpCode.products[] A collection of products and services assigned to a CP code.
purgeable Boolean Whether you can purge the content cached by the CP code.
type String The type of CP code.
CpCode.contracts[]: Provides detailed information about the contracts assigned to the CP code.
contractId String Read-only. The identifier for the contract.
status String Read-only. The current status of the contract.
CpCode.overrideTimezone: The GMT time zone that overrides the default time zone assigned to the CP code. Only a few legacy reports override the default time zone for the time axis. Most reports, and all new ones, use the user’s own time zone for the time axis.
timezoneId String The identifier for the GMT time zone.
timezoneValue String The offset value for the GMT time zone.
CpCode.products[]: The products and services assigned to the CP code.
productId String Read-only. The identifier for a product or service.
productName String Read-only. The descriptive label for a product or service.

ReportingGroup

Provides the request members that you can specify when updating a reporting group. You should only modify a reporting group’s name and assigned CP codes. Modifying other members results in an 400 error response and causes the request to fail.

Download schema: reportinggroup.json, create-reporting-group-request.json, update-reporting-group-request.json

Sample POST request:

{
    "reportingGroupName": "Region XYZ",
    "accessGroup": {
        "groupId": 9760,
        "contractId": "ctr_1Q004"
    },
    "contracts": [
        {
            "contractId": "ctr_1Q004",
            "cpcodes": [
                {
                    "cpcodeId": 12345,
                    "cpcodeName": "CPC XYZ"
                },
                {
                    "cpcodeId": 67890,
                    "cpcodeName": "CPC SME"
                }
            ]
        }
    ]
}

ReportingGroup members

Member Type GET POST PUT Description
accessGroup ReportingGroup.accessGroup A group that controls access to specific CP codes.
contracts ReportingGroup.contracts[] A collection of contracts assigned to the reporting group.
reportingGroupId Integer Read-only. The identifier for the reporting group.
reportingGroupName String The descriptive label for the reporting group.
ReportingGroup.accessGroup: A group that controls access to specific CP codes.
contractId String The identifier for the contract assigned to the access control group.
groupId Integer The identifier for the access control group.
ReportingGroup.contracts[]: A collection of contracts assigned to the reporting group.
contractId String Read-only. The identifier for the contract.
cpcodes ReportingGroup.contracts[].cpcodes[] A collection of CP codes assigned to the reporting group.
ReportingGroup.contracts[].cpcodes[]: A collection of CP codes assigned to the reporting group.
cpcodeId Integer The identifier for a CP code.
cpcodeName String The descriptive label for a CP code.

ReportingGroupProducts

Provides information about products and services assigned to a specific reporting group.

Download schema: get-reporting-group-product-response.json

Sample GET response:

{
    "products": [
        {
            "productId": "PPPL::ABC",
            "productName": "Performance PPL ABC "
        },
        {
            "productId": "Core::Analyzer",
            "productName": "Core utility JL"
        },
        {
            "productId": "Dev::Cloud",
            "productName": "Cloud development CD"
        },
        {
            "productId": "AdvSite::Reporter",
            "productName": "Monitor site advance"
        }
    ]
}

ReportingGroupProducts members

Member Type Required Description
products ReportingGroupProducts.products[] A collection of products and services assigned to the reporting group.
ReportingGroupProducts.products[]: A collection of products and services assigned to the reporting group.
productId String The identifier for a product or service.
productName String The descriptive label for a product or service.

WatermarkLimits

Provides information about watermark limits for CP codes or reporting groups available within a specific contract.

Download schema: watermark-limits.json

Sample GET response:

{
    "limit": 5000,
    "currentCapacity": 3500,
    "limitType": "account"
}

WatermarkLimits members

Member Type Required Description
currentCapacity Integer The current number of CP codes or reporting groups.
limit Integer The number of allowed CP codes or reporting groups.
limitType String Identifies whether the limit applies to an account or a contract. See High watermark limit.

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

When you encounter an error, the CP Code and Reporting Groups API responds with HTTP Problem objects that provide details useful for debugging, as in the example below.

{
  "details": [
    {
      "code": "invalid.data",
      "message": "Group name is mandatory"
    }
  ],
  "code": "bad.request",
  "title": "Bad Request",
  "incidentId": "dc2f405e-29d3-4845-a4ac-2f6b4a732aca"
}

HTTP status codes

This section lists the full range of response codes the API may generate.

Code Description
200 The operation was successful.
201 Resource successfully created.
202 Resource successfully accepted.
301 The requested item has permanently moved to the link provided.
302 The requested item is temporarily available at the link provided.
400 Bad request.
401 Authentication failure.
403 Access is forbidden.
404 Resource not found.
405 Method not supported.
408 Request timeout.
410 Requested resource is no longer available.
411 Content-length header not specified.
413 Request body exceeds maximum allowable size.
415 Unsupported media type.
500 Internal server error.
502 Platform timeout error.
503 Too many requests. Service is temporarily unavailable.

Last modified: 10/25/2018