Add or remove hostnames for a property's hostname bucket

patch https://{hostname}/papi/v1/properties/{propertyId}/hostnames

For a property with useHostnameBucket set to true when created, this operation adds or removes up to 1000 property hostnames without incrementing the property version. Changes automatically activate on the selected network. If a property doesn't have hostname buckets enabled, this operation returns a 403 error. If another activation is in progress, whether it's a hostname activation or a property version activation, the operation fails with a 409 error. Once you perform this operation, it blocks subsequent requests until all the property hostnames are active. Note that to build the request body, you need to first obtain the edgeHostnameId either from an existing edge hostname or a new one you create by running the Create a new edge hostname operation.

Note: If you're using a new account, first register it on the Akamai network by activating any property version on either staging or production. Otherwise, your attempts to create or specify certificates will fail with a 403 error.

Recipes

Open Recipe

Path Params

propertyId

string

required

Unique identifier for the property. See ID prefixes for details on omitting the value's prp_ prefix.

Query Params

contractId

string

Unique identifier for the contract. The parameter is optional if a property belongs to only one contract. Otherwise you need to specify it along with the groupId. In other operations that don't specify a propertyId URL parameter, this parameter is always required. See ID prefixes for details on omitting the value's ctr_ prefix.

groupId

string

Unique identifier for the group. The parameter is optional if a property belongs to only one group. Otherwise you need to specify it along with the contractId. In other operations that don't specify a propertyId URL parameter, this parameter is always required. See ID prefixes for details on omitting the value's grp_ prefix.

accountSwitchKey

string

For customers who manage more than one account, this runs the operation from another account. The Identity and Access Management API provides a list of available account switch keys.

Body Params

add

array of objects

The property hostnames you want to add to a hostname bucket. You can specify up to 1000 new property hostnames in a single request.

add

network

required

The network to activate on, either STAGING or PRODUCTION.

note

string

Assigns a log message to the request.

notifyEmails

array of strings

length ≥ 1

Email addresses to notify when the activation status changes.

notifyEmails

remove

array of strings

The property hostnames you want to delete from the current set in the hostname bucket.

remove

Headers

PAPI-Use-Prefixes

string

required

Enum Sets whether to represent ID prefixes in response data. Set to false when exchanging PAPI data with other APIs.

Responses

Response body

object

activationId

string

required

Unique identifier for the hostname bucket activation. This is common for all property hostnames in a hostname bucket.

activationLink

string

required

Links the newly created hostname bucket activation. This is common for all property hostnames in a hostname bucket.

hostnames

array of objects

Specifies property hostnames activated in a hostname bucket.

hostnames

object

certProvisioningType

string

required

Indicates the type of the certificate used in the property hostname. Either CPS_MANAGED for the certificates you create with the Certificate Provisioning System API (CPS), or DEFAULT for Default Domain Validation (DV) certificates deployed automatically. Note that you can't specify the DEFAULT value if your account hostname uses the akamaized.net domain suffix.

CPS_MANAGED DEFAULT

certStatus

object

Limited availability With the includeCertStatus parameter set to true, determines whether a hostname is capable of serving secure content over the staging or production network.

cnameFrom

string

required

The hostname that your end users see, indicated by the Host header in end user requests.

cnameTo

string

The edge hostname you point the property hostname to so that you can start serving traffic through Akamai servers. This member corresponds to the edge hostname object's edgeHostnameDomain member.

cnameType

string

required

Only one supported EDGE_HOSTNAME value.

EDGE_HOSTNAME

edgeHostnameId

string

required

Identifies the edge hostname you mapped your traffic to on the staging network. See ID prefixes for details on how to omit the ID's ehn_ prefix.

Headers

object

X-Limit-Default-Certs-Per-Contract-Limit

string

The total number of Default Domain Validation (DV) certificates per contract. This header only appears if you have any hostnames with Default DV certificates assigned to the property version.

X-Limit-Default-Certs-Per-Contract-Remaining

string

The number of remaining Default Domain Validation (DV) certificates per contract. This header only appears if you have any hostnames with Default DV certificates assigned to the property version.

X-Limit-Hosts-Per-Account-Limit

string

Maximum number of hostnames you can assign to all properties under an account.

X-Limit-Hosts-Per-Account-Remaining

string

Remaining number of hostnames you can assign to all properties under an account. See Rate and resource limiting for details.

X-Limit-Hosts-Per-Property-Limit

string

Maximum number of hostnames you can assign to a property configuration.

X-Limit-Hosts-Per-Property-Remaining

string

Remaining number of hostnames you can assign to a property configuration. See Rate and resource limiting for details.

X-RateLimit-Limit

integer

Maximum sustainable number of request allowed each minute per account. This rate limit protects PAPI resources from being exhausted by single users. Once you exceed the limit, you receive the 429 error. If you call PAPI using multiple API clients within the same account, the rate limit applies globally to all API clients.

This API also provides a burst limit that specifies how many requests you can make in excess of the imposed rate limit. The one-time burst limit is 1000 requests. Once you consume all available resources, the burst capacity increases steadily by 100 requests every minute, until it reaches its initial maximum limit of 1000.

X-RateLimit-Remaining

integer

Remaining number of requests allowed each minute per account. See Rate and resource limiting for details.

Language

Authentication

Remember to add your authentication credentials to run this code.

URL


xxxxxxxxxx
10
1
curl --request PATCH \
2
     --url https://hostname/papi/v1/properties/propertyId/hostnames \
3
     --header 'PAPI-Use-Prefixes: true' \
4
     --header 'accept: application/json' \
5
     --header 'content-type: application/json' \
6
     --data '
7
{
8
  "network": "STAGING"
9
}
10
'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

201The response lists hostnames added or removed from the property.

400Bad request.

401Unauthorized.

403Forbidden.

404Not found.

405Method not allowed.

406Not acceptable.

409Conflict.

413Request entity too large.

415Unsupported media type.

422Unprocessable content.

429Too many requests.

500Internal server error.