--- updatedAt: 2026-05-13T18:26:54.000Z agentTools: siteIndex: https://techdocs.akamai.com/llms.txt projectIndex: https://techdocs.akamai.com/gtm/llms.txt --- # Add or update properties Adds or updates properties on a domain without replacing the entire set. Properties not included in the request body are left unchanged. # OpenAPI definition ```json { "externalDocs": { "description": "See documentation for Akamai's Global Traffic Management API", "url": "https://techdocs.akamai.com/gtm/reference" }, "info": { "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "title": "Properties", "version": "v1" }, "openapi": "3.0.0", "paths": { "/domains/{domainName}/properties": { "patch": { "description": "Adds or updates properties on a domain without replacing the entire set. Properties not included in the request body are left unchanged.", "externalDocs": { "description": "See documentation for this operation in Akamai's Global Traffic Management API", "url": "https://techdocs.akamai.com/gtm/reference/patch-properties" }, "operationId": "patch-properties", "parameters": [ { "description": "Specifies change descriptions for audit trail and domain's change history. The maximum is 4000 characters.", "in": "query", "name": "domainModificationComments", "schema": { "example": "Load balancer policy change", "maxLength": 4000, "nullable": true, "type": "string" }, "x-akamai": { "file-path": "parameters/domain-modification-comments-query.yaml" } }, { "description": "For customers who manage more than one account, this [runs the operation from another account](https://techdocs.akamai.com/developer/docs/manage-many-accounts-with-one-api-client). The Identity and Access Management API provides a [list of available account switch keys](https://techdocs.akamai.com/iam-api/reference/get-client-account-switch-keys).", "in": "query", "name": "accountSwitchKey", "required": false, "schema": { "example": "1-5C0YLB:1-8BYUX", "type": "string" } } ], "requestBody": { "content": { "application/property-vnd-config-gtm.v1.8+json": { "example": { "items": [ { "backupCName": "string", "backupIp": "string", "balanceByDownloadScore": true, "cname": "string", "comments": null, "dynamicTTL": 30, "failbackDelay": 0, "failoverDelay": 0, "ghostDemandReporting": false, "handoutLimit": 8, "handoutMode": "normal", "healthMax": 0, "healthMultiplier": 0, "healthThreshold": 0, "ipv6": true, "lastModified": "2025-05-12T19:36:44Z", "links": [ { "href": "string", "rel": "string" } ], "livenessTests": [ { "alternateCACertificates": [ "myAlternateCACertificates", "myAlternateCACertificates2" ], "answersRequired": true, "disableNonstandardPortWarning": true, "disabled": true, "errorPenalty": 0, "hostHeader": "string", "httpError3xx": true, "httpError4xx": true, "httpError5xx": true, "httpHeaders": [ { "name": "string", "value": "string" } ], "httpMethod": "TRACE", "httpRequestBody": "string", "name": "string", "peerCertificateVerification": true, "pre2023SecurityPosture": false, "recursionRequested": true, "requestString": "string", "resourceType": "A", "responseString": "string", "sslClientCertificate": "string", "sslClientPrivateKey": "string", "testInterval": 10, "testObject": "string", "testObjectPassword": "string", "testObjectPort": 53, "testObjectProtocol": "DNS", "testObjectUsername": "string", "testTimeout": 10, "timeoutPenalty": 0 } ], "loadImbalancePercentage": 0, "mapName": "string", "maxUnreachablePenalty": 0, "minActiveDatacenterFraction": 0.75, "minLiveFraction": 0, "mxRecords": [], "name": "string", "scoreAggregationType": "mean", "stateChangeNotificationWebhook": { "format": "json-compact", "url": "https://example.com/webhooks/gtm-notifications" }, "staticRRSets": [ { "rdata": [ "string" ], "ttl": 3600, "type": "MX" } ], "staticTTL": null, "stickinessBonusConstant": 0, "stickinessBonusPercentage": 0, "trafficTargets": [ { "datacenterId": 0, "enabled": true, "handoutCName": null, "handoutRRSets": [ { "rdata": [ "192.0.2.1" ], "ttl": 60, "type": "A" }, { "rdata": [ "2001:db8::1" ], "ttl": 60, "type": "AAAA" } ], "name": "string", "precedence": 3, "servers": [ "string" ], "weight": 0 } ], "type": "ranked-failover", "unreachableThreshold": 0, "useComputedTargets": true } ] }, "schema": { "additionalProperties": true, "properties": { "items": { "description": "The list of a domain's properties.", "items": { "allOf": [ { "additionalProperties": true, "description": "The entire GTM property configuration.", "properties": { "backupCName": { "description": "Specifies a `backupCName`. If GTM declares that all of the servers configured for your property are down, and you configured a `backupCName`, then queries for the property return the `backupCName`. If a `backupCName` is set, don't set a `backupIp`.", "nullable": true, "type": "string" }, "backupIp": { "description": "Specifies a backup IP. When GTM declares that all of the targets are down, it hands out the `backupIP`. The IP type coincides with the property's `iPv6` setting. If a `backupIp` is set, don't set a `backupCName`.", "nullable": true, "type": "string" }, "balanceByDownloadScore": { "description": "Indicates whether download score based load balancing is enabled. GTM estimates the load on your data centers based on how long they take to respond to GTM liveness tests. The advantage: you don't need to implement a load object. The disadvantage: it's a very crude measure of load, and usually highly nonlinear. As load increases, download times don't increase significantly, until there's too much load. When that happens, the download times skyrocket. This can easily cause erratic load balancing or load oscillations.", "type": "boolean" }, "cname": { "description": "Indicates the fully qualified name aliased to a particular property. The public name of the property.", "nullable": true, "type": "string" }, "comments": { "description": "Provides information about the purpose of the property.", "nullable": true, "type": "string" }, "dynamicTTL": { "default": 60, "description": "Indicates the TTL in seconds for records that might change dynamically based on liveness and load balancing such as A and AAAA records, and CNAMEs. The value ranges from `30` to `3600` and can change on request. The default is `60`.", "maximum": 3600, "minimum": 30, "type": "integer" }, "failbackDelay": { "description": "Specifies the failback delay in seconds. The minimum value is `0`. If specified, when a server has been down and comes back up, (that is, its liveness test starts succeeding again), GTM only considers it up after the failback delay has elapsed and tests continue to succeed.", "minimum": 0, "nullable": true, "type": "integer" }, "failoverDelay": { "description": "Specifies the failover delay in seconds. The minimum value is `0`. If specified, when a server begins failing its liveness test, GTM only considers it down after the failover delay has elapsed and the errors persist.", "minimum": 0, "nullable": true, "type": "integer" }, "handoutMode": { "default": "normal", "description": "Specifies how IPs are returned when more than one IP is alive and available. Possible values are: `normal`, `persistent`, `one-ip`, `one-ip-hashed`, or `all-live-ips`. The default is `normal`. Handout mode is relevant only when you have more than one server IP in a data center.", "enum": [ "normal", "persistent", "one-ip", "one-ip-hashed", "all-live-ips" ], "type": "string" }, "healthMax": { "description": "Defines the absolute limit beyond which IPs are declared unhealthy. If backup CNAMEs are provided for a property, then it's reasonable for all IPs to be declared unhealthy. The `healthMax` value is multiplied by the smaller of the `timeoutPenalty` and the `errorPenalty`. This check declares as down any server with a score greater than this product. The default value is `null`.", "nullable": true, "type": "number" }, "healthMultiplier": { "description": "Configures a cutoff value that's computed from the median scores. Any server with a score over the cutoff value is considered down, and load isn't sent to it. The cutoff is computed from the minimum score across all data centers, for a given property and two object fields: `healthMultiplier` and `healthThreshold`. The cutoff is either `healthMultiplier` (default value: 1.5) times the minimum score, or the `healthThreshold` (default value: 4), whichever is greater. See also `healthThreshold` within this object. For more information on how to determine server liveness, see the [Global Traffic Management User Guide](https://techdocs.akamai.com/gtm/docs/welcome-to-global-traffic-management).", "nullable": true, "type": "number" }, "healthThreshold": { "description": "Configures a cutoff value that's computed from the median scores. Any server with a score over the cutoff value is considered down, and load isn't sent to it. See also `healthMultiplier` within this object. For more information on how to determine server liveness, see the [Global Traffic Management User Guide](https://techdocs.akamai.com/gtm/docs/welcome-to-global-traffic-management).", "nullable": true, "type": "number" }, "ipv6": { "description": "Indicates the type of IP address handed out by a property. A `true` value indicates that all IP addresses specified are IPv6, and all hostnames need to resolve to AAAA records. A `false` value indicates IPv4 addresses, and all hostnames need to resolve to A records.", "type": "boolean" }, "lastModified": { "description": "An ISO 8601 timestamp indicating when the property was last changed.", "nullable": true, "type": "string" }, "links": { "description": "A URL path that allows direct navigation to the property.", "items": { "additionalProperties": false, "description": "Lists navigable URLs to resources.", "properties": { "href": { "description": "Provides a hypermedia link to the complete URL that uniquely defines a resource.", "type": "string" }, "rel": { "description": "Indicates the link relationship of the object.", "type": "string" } }, "type": "object", "x-akamai": { "file-path": "schemas/link.yaml" } }, "type": "array" }, "loadImbalancePercentage": { "description": "Indicates the percent of load imbalance factor (LIF) for the domain. It lets GTM exceed the value configured for traffic distribution. For example, if the data center's traffic allocation is 25 percent and the LIF is 1.5, the demand can grow to 37.5 percent (25% × 1.5) before the load balancer starts shifting load away from it. If the LIF is `0`, no load imbalance is allowed. However, internally, GTM adds one to the LIF to allow its use as a multiplier. The default LIF is 1.1, which is displayed as `10.0` percent. The value ranges from `0` to `1000000` percent.", "maximum": 1000000, "minimum": 0, "nullable": true, "type": "number" }, "mapName": { "description": "A descriptive label for a geographic map or a CIDR map that's required if the property is either `geographic` or `cidrmapping`, in which case `mapName` needs to reference either an existing geographic map or CIDR map in the same domain.", "nullable": true, "type": "string" }, "maxUnreachablePenalty": { "description": "For `performance` domains, this specifies a penalty value that's added to liveness test scores when data centers show an aggregated loss fraction higher than the penalty value. The penalty value is either `maxUnreachablePenalty` (minimum value is `0` and the default is `null`) or `unreachableThreshold` (decimal between `0` and `1`. A value of 1.0 or `null` disables an unreachable penalty). See also `unreachableThreshold` within this object.", "minimum": 0, "nullable": true, "type": "number" }, "mxRecords": { "description": "Specifies the MX records handed out to `MX` record type queries. Note that mapping and liveness testing aren't done. The same MX records are handed out for every request.", "items": { "additionalProperties": false, "properties": { "exchange": { "description": "MX record exchange field.", "type": "string" }, "preference": { "description": "MX record preference field.", "type": "number" } }, "required": [ "exchange", "preference" ], "type": "object" }, "type": "array" }, "name": { "description": "The value, together with the full GTM `domainName`, forms the property's hostname. The value should not begin or end with a dot character and needs to be a valid [RFC 1123](https://tools.ietf.org/html/rfc1123) hostname. Set the name to `@` if the property is to be located at the apex of the domain.", "oneOf": [ { "format": "hostname", "title": "Hostname", "type": "string" }, { "enum": [ "@" ], "title": "apex", "type": "string" } ] }, "scoreAggregationType": { "default": "worst", "description": "Specifies how GTM aggregates liveness test scores across different tests, when multiple tests are configured. Possible values are: `mean`, `median`, `best`, or the default `worst`.", "enum": [ "mean", "median", "best", "worst" ], "type": "string" }, "staticTTL": { "description": "Specifies the TTL in seconds for static resource records that don't change based on the requesting name server IP. This includes MX, TXT, and SPF records.", "maximum": 3600, "minimum": 30, "nullable": true, "type": "integer" }, "stickinessBonusConstant": { "description": "Specifies a constant used to configure data center affinity. This only applies if the property `type` is `performance` and the domain `type` is `full`. The value ranges from `0` to `30000`. See also `stickinessBonusPercentage` within this object. To learn more about how these object fields relate to each other, see [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "maximum": 30000, "minimum": 0, "nullable": true, "type": "integer" }, "stickinessBonusPercentage": { "description": "Specifies a percentage used to configure data center affinity. This only applies if the property `type` is `performance` and the domain `type` is `full`. The value ranges from `0` to `100`. See also `stickinessBonusConstant` within this object. To learn more about how these object fields relate to each other, see [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "maximum": 100, "minimum": 0, "nullable": true, "type": "integer" }, "unreachableThreshold": { "description": "For `performance` domains, this specifies a penalty value that's added to liveness test scores when data centers have an aggregated loss fraction higher than this value. The value is a decimal between `0` and `1`. A value of `1.0` or `null` disables an unreachable penalty. See also `maxUnreachablePenalty` within this object.", "maximum": 1, "minimum": 0, "nullable": true, "type": "number" }, "useComputedTargets": { "description": "For `load-feedback` domains only, this specifies that you want GTM to automatically compute target load. Report only the current load objects, either by omission, or by using non-XML load objects.", "type": "boolean" } }, "required": [ "backupCName", "backupIp", "dynamicTTL", "failbackDelay", "failoverDelay", "handoutMode", "ipv6", "mapName", "mxRecords", "name", "scoreAggregationType", "staticTTL" ], "type": "object", "x-akamai": { "file-path": "schemas/property-vnd-config-gtm-nested-not-versioned.v1.0.yaml" } }, { "additionalProperties": true, "description": "The entire GTM property configuration.", "properties": { "ghostDemandReporting": { "description": "__v1.3__ Enables reporting of unmet content requests received by edge servers, analyzing demand for unserved content.", "type": "boolean", "x-akamai": { "labels": [ "v1.3" ] } }, "handoutLimit": { "description": "__v1.3__ Indicates the limit for the number of live IPs handed out to a DNS request. The `handoutLimit` applies only if `handoutMode` is set to either `normal` or `persistent` for the property. If applicable, the `handoutLimit` default value is `8` or `null` if not.", "minimum": 1, "nullable": true, "type": "integer", "x-akamai": { "labels": [ "v1.3" ] } }, "livenessTests": { "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "items": { "allOf": [ { "allOf": [ { "allOf": [ { "allOf": [ { "allOf": [ { "allOf": [ { "allOf": [ { "additionalProperties": true, "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "properties": { "disableNonstandardPortWarning": { "default": false, "description": "Disables warnings when non-standard ports are used. For example, GTM doesn't emit a warning to specify port 1234 when the `testObjectProtocol` is `http`, as HTTP typically uses port 80. The default is `false`.", "type": "boolean" }, "hostHeader": { "description": "Sent if the `testObjectProtocol` is `http` or `https`, up to 256 non-space, alphanumeric characters. Obsolete as of version 1.4. You should use `hostHeaders` instead.", "maxLength": 256, "minLength": 1, "nullable": true, "type": "string" }, "httpError3xx": { "description": "Treats a 3xx HTTP response as a failure if the `testObjectProtocol` is `http`, `https`, or `ftp`.", "type": "boolean" }, "httpError4xx": { "description": "Treats a 4xx HTTP response as a failure if the `testObjectProtocol` is `http`, `https`, or `ftp`.", "type": "boolean" }, "httpError5xx": { "description": "Treats a 5xx HTTP response as a failure if the `testObjectProtocol` is `http`, `https`, or `ftp`.", "type": "boolean" }, "name": { "description": "A descriptive name for the liveness test.", "maxLength": 128, "minLength": 1, "type": "string" }, "requestString": { "description": "Specifies a request string. Required if `testObjectProtocol` is `tcp` or `tcps`. The value is a maximum of 4000 non-space, alphanumeric characters.", "maxLength": 4000, "minLength": 1, "nullable": true, "type": "string" }, "responseString": { "description": "Specifies a response string. Required if `testObjectProtocol` is `tcp` or `tcps`. Maximum 4000 characters.", "maxLength": 4000, "nullable": true, "type": "string" }, "sslClientCertificate": { "description": "Indicates a Base64-encoded certificate. SSL client certificates are available for `livenessTests` that use secure protocols.", "nullable": true, "type": "string" }, "sslClientPrivateKey": { "description": "Indicates a Base64-encoded private key. The private key used to generate or request a certificate for `livenessTests` can't have a passphrase nor be used for any other purpose.", "nullable": true, "type": "string" }, "testInterval": { "description": "Indicates the interval at which the liveness test is run, in seconds. Requires a minimum of 10 seconds.", "minimum": 10, "type": "integer" }, "testObject": { "description": "Specifies the static text that acts as a stand-in for the data that you're sending on the network.", "maxLength": 256, "minLength": 1, "nullable": true, "type": "string" }, "testObjectPassword": { "description": "Specifies the test object's password. It's required if `testObjectProtocol` is `ftp`. Maximum is 128 characters.", "maxLength": 128, "minLength": 1, "nullable": true, "type": "string" }, "testObjectPort": { "description": "Specifies the port number for the `testObject`. Value from `1` to `65535`.", "maximum": 65535, "minimum": 1, "type": "integer" }, "testObjectProtocol": { "description": "Specifies the test protocol. Possible values are: `DNS`, `DOH`, `DOT`, `HTTP`, `HTTPS`, `HTTP2`, `HTTP2S`, `FTP`, `POP`, `POPS`, `SMTP`, `SMTPS`, `TCP`, or `TCPS`. To enable `testObjectProtocol` for `DNS`, `DOH`, or `DOT` requires `application/vnd.config-gtm.v1.3+json`.", "enum": [ "DNS", "DOH", "DOT", "HTTP", "HTTPS", "HTTP2", "HTTP2S", "FTP", "POP", "POPS", "SMTP", "SMTPS", "TCP", "TCPS" ], "type": "string" }, "testObjectUsername": { "description": "A descriptive name for the `testObject`. If `testObjectProtocol` is `ftp`, then you need to specify a `testObjectUsername`. The value is a maximum of 256 non-space, alphanumeric characters.", "maxLength": 512, "minLength": 1, "nullable": true, "type": "string" }, "testTimeout": { "description": "Specifies the duration of the liveness test before it fails. The range is from `0.001` to `60` seconds.", "maximum": 60, "minimum": 0.001, "type": "number" } }, "required": [ "disableNonstandardPortWarning", "hostHeader", "httpError3xx", "httpError4xx", "httpError5xx", "name", "requestString", "responseString", "sslClientCertificate", "sslClientPrivateKey", "testInterval", "testObject", "testObjectPassword", "testObjectPort", "testObjectProtocol", "testObjectUsername", "testTimeout" ], "type": "object", "x-akamai": { "file-path": "schemas/liveness-test-v1.0.yaml" } }, { "additionalProperties": true, "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "properties": { "errorPenalty": { "default": 75, "description": "__v1.2__ Specifies the score that's reported if the liveness test encounters an error other than timeout, such as connection refused, and 404. The default value is `75`.", "minimum": 0, "type": "number", "x-akamai": { "labels": [ "v1.2" ] } }, "timeoutPenalty": { "default": 25, "description": "__v1.2__ Specifies the score reported if the liveness test times out. This is independent of the liveness `testTimeout` value. The default value is `25` seconds.", "minimum": 0, "type": "number", "x-akamai": { "labels": [ "v1.2" ] } } }, "required": [ "errorPenalty", "timeoutPenalty" ], "type": "object" } ], "title": "livenessTest v1.2", "x-akamai": { "file-path": "schemas/liveness-test-v1.2.yaml" } }, { "additionalProperties": true, "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "properties": { "answersRequired": { "default": false, "description": "__v1.3__ If `testObjectProtocol` is `DNS`, `DOH` or `DOT`, requires an answer to the DNS query to be considered a success. The default is `false`.", "type": "boolean", "x-akamai": { "labels": [ "v1.3" ] } }, "peerCertificateVerification": { "default": false, "description": "__v1.3__ Validates the origin certificate. Applies only to tests with `testObjectProtocol` of `https`. The default is `false`.", "type": "boolean", "x-akamai": { "labels": [ "v1.3" ] } }, "recursionRequested": { "default": false, "description": "__v1.3__ Indicates that if `testObjectProtocol` is `DNS`, `DOH` or `DOT`, the `DNS` query is recursive. The default is `false`.", "type": "boolean", "x-akamai": { "labels": [ "v1.3" ] } }, "resourceType": { "description": "__v1.3__ Specifies the query type, if `testObjectProtocol` is `DNS`. Possible values are: `A`, `AAAA`, `AFSDB`, `CNAME`, `HINFO`, `LOC`, `MX`, `NAPTR`, `NS`, `PTR`, `RP`, `SOA`, `SPF`, `SRV`, `SSHFP`, `TXT`, `DNSKEY`, `DS`, `NSEC3`, `NSEC3PARAM`, or `RRSIG`. Unknown types `TYPENNNNN` are also supported, where `NNNNN` is an integer from `1` through `65535`.", "enum": [ "A", "AAAA", "AFSDB", "CNAME", "HINFO", "LOC", "MX", "NAPTR", "NS", "PTR", "RP", "SOA", "SPF", "SRV", "SSHFP", "TXT", "DNSKEY", "DS", "NSEC3", "NSEC3PARAM", "RRSIG" ], "nullable": true, "type": "string", "x-akamai": { "labels": [ "v1.3" ] } } }, "required": [ "answersRequired", "resourceType", "recursionRequested", "peerCertificateVerification" ], "type": "object" } ], "title": "livenessTest v1.3", "x-akamai": { "file-path": "schemas/liveness-test-v1.3.yaml" } }, { "additionalProperties": true, "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "properties": { "disabled": { "default": false, "description": "__v1.4__ Disables the liveness test. When disabled, GTM stops running the test, treating it as if it no longer exists. The default is `false`.", "type": "boolean", "x-akamai": { "labels": [ "v1.4" ] } }, "httpHeaders": { "description": "__v1.4__ HTTP headers to send if the `testObjectProtocol` is `http` or `https`. This `hostHeader` is deprecated as of version 1.4.", "items": { "additionalProperties": false, "properties": { "name": { "description": "Name of the HTTP header.", "minLength": 1, "type": "string" }, "value": { "description": "Value of the HTTP header.", "type": "string" } }, "required": [ "name", "value" ], "type": "object" }, "type": "array", "x-akamai": { "labels": [ "v1.4" ] } } }, "type": "object" } ], "title": "livenessTest v1.4", "x-akamai": { "file-path": "schemas/liveness-test-v1.4.yaml" } }, { "additionalProperties": true, "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "properties": { "alternateCACertificates": { "description": "__v1.5__ Alternate trust anchors, Base64-encoded CA certificates. Available for `livenessTests` that use secure protocols.", "items": { "type": "string" }, "type": "array", "x-akamai": { "labels": [ "v1.5" ] } }, "httpMethod": { "default": "GET", "description": "__v1.5__ The HTTP method to send if the `testObjectProtocol` is `http` or `https`. Possible values are: `TRACE`, `HEAD`, `OPTIONS`, `GET`, `PUT`, `POST`, `PATCH`, or `DELETE`. When omitted or `null`, this value defaults to `GET`.", "enum": [ "TRACE", "HEAD", "OPTIONS", "GET", "PUT", "POST", "PATCH", "DELETE" ], "nullable": true, "type": "string", "x-akamai": { "labels": [ "v1.5" ] } }, "httpRequestBody": { "description": "__v1.5__ The Base64-encoded HTTP request body to send if the `testObjectProtocol` is `http` or `https`. When omitted or `null`, omits the request body from the request.", "nullable": true, "type": "string", "x-akamai": { "labels": [ "v1.5" ] } } }, "type": "object" } ], "title": "livenessTest v1.5", "x-akamai": { "file-path": "schemas/liveness-test-v1.5.yaml" } }, { "additionalProperties": true, "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "properties": { "pre2023SecurityPosture": { "default": false, "description": "__v1.6__ Indicates whether the system uses a security posture configuration from before 2023. Defaults to false.", "type": "boolean", "x-akamai": { "labels": [ "v1.6" ] } } }, "type": "object" } ], "title": "livenessTest v1.6", "x-akamai": { "file-path": "schemas/liveness-test-v1.6.yaml" } }, { "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "type": "object" } ], "title": "livenessTest v1.7", "x-akamai": { "file-path": "schemas/liveness-test-v1.7.yaml" } }, { "description": "Liveness tests, which run periodically to determine whether your servers respond to requests.", "type": "object" } ], "title": "livenessTest v1.8", "x-akamai": { "file-path": "schemas/liveness-test-v1.8.yaml" } }, "type": "array" }, "minActiveDatacenterFraction": { "default": null, "description": "__v1.7__ The fraction of data centers that must be passing their liveness tests in order for the selection of live data centers to occur. For example, if this is set to `0.75` and only half the data centers are passing their liveness tests, then all data centers are handed out regardless of liveness test results. A `null` or `0` value means the feature is disabled and behavior is unchanged. The default value is `null`.", "maximum": 1, "minimum": 0, "nullable": true, "type": "number", "x-akamai": { "labels": [ "v1.7" ] } }, "minLiveFraction": { "description": "__v1.3__ Specifies what fraction of the servers need to respond to requests so GTM considers the data center up and able to receive traffic. For example, if your data center contains eight servers, and the `minLiveFraction` value is `0.5`, then at least four servers need to respond to requests. Conversely, if five servers are down, and three servers are up, then GTM considers the entire data center down. Optional when a `minLiveFraction` value exists or not `null`.", "maximum": 1, "minimum": 0, "nullable": true, "type": "number", "x-akamai": { "labels": [ "v1.3" ] } }, "stateChangeNotificationWebhook": { "additionalProperties": false, "description": "__v1.7__ Configures a webhook to receive notifications when the property's state changes. Set to `null` to disable notifications.", "nullable": true, "properties": { "format": { "default": "json-compact", "description": "The format of the notification payload. Possible values are: `json-compact`, `json-pretty`, or `slack-mrkdwn`. The default value is `json-compact`.", "enum": [ "json-compact", "json-pretty", "slack-mrkdwn" ], "type": "string" }, "url": { "description": "The URL to send the notification to. Only `http`, `https`, and `mailto` schemes are allowed. If the host is a name, it must resolve to a routable address. If the host is an IP address, it must be routable.", "maxLength": 1024, "type": "string" } }, "required": [ "url" ], "type": "object", "x-akamai": { "labels": [ "v1.7" ] } }, "staticRRSets": { "description": "__v1.4__ Static recordsets. Use this instead of `mxRecords` and `staticTTL`, which were deprecated in version 1.4.", "items": { "additionalProperties": false, "properties": { "rdata": { "description": "An array of data strings, representing multiple records within a set. The format of the `rdata` strings are dependent on the `type` of this record.", "items": { "type": "string" }, "type": "array" }, "ttl": { "description": "The number of seconds that this record should live in a resolver's cache before being refetched.", "type": "integer" }, "type": { "description": "The record type.", "type": "string" } }, "required": [ "type", "ttl", "rdata" ], "type": "object" }, "type": "array", "x-akamai": { "labels": [ "v1.4" ] } }, "trafficTargets": { "description": "This specifies where to direct data center traffic. For geographic mapped properties, it's always a `cname`. For mirror failover properties, it can be any set of servers. For load balanced properties, this is a set of servers that are all within the same data center. You can assign multiple traffic targets to the same data center.", "items": { "allOf": [ { "allOf": [ { "allOf": [ { "additionalProperties": true, "description": "This specifies where to direct data center traffic. For geographic mapped properties, it's always a `cname`. For mirror failover properties, it can be any set of servers. For load balanced properties, this is a set of servers that are all within the same data center. You can assign multiple traffic targets to the same data center.", "properties": { "datacenterId": { "description": "A unique identifier for an existing data center in the domain.", "type": "integer" }, "enabled": { "description": "Indicates whether the traffic target is used. You can also omit the traffic target, which has the same result as the `false` value. However, when the value is `false`, GTM continues to store the other traffic target fields in the database. There's no need to store them locally should you want to use the traffic target at a later time.", "type": "boolean" }, "handoutCName": { "description": "Specifies an optional data center for the property. Uses the `handoutCName` when there are no servers configured for the property. Maximum 63 characters for the labels, 255 characters overall. May contain alphanumeric, hyphens, and underscores, but not literal IP addresses. Leading or trailing hyphens aren't allowed.", "maxLength": 255, "nullable": true, "type": "string" }, "name": { "description": "An alternative label for the traffic target.", "nullable": true, "type": "string" }, "servers": { "description": "Identifies the IP address or the hostnames of the servers. For hostnames that return IP addresses, tests all IP addresses for liveness.", "items": { "type": "string" }, "type": "array" }, "weight": { "description": "Specifies the traffic weight for the target. This is required when the enclosing property is `failover`, `weighted`, `weighted-with-load-feedback`, or `performance`. The sum of this value, for all enabled targets, can be any number, percentage, or ratio. For example, you can express a traffic split as 60/40, 120/80, or 3/2, all equivalent values. For `failover` properties, set this value to `1` for the traffic target you want to mark as _primary_.", "minimum": 0, "type": "number" } }, "type": "object", "x-akamai": { "file-path": "schemas/traffic-target-v1.0.yaml" } }, { "additionalProperties": true, "description": "This specifies where to direct data center traffic. For geographic mapped properties, it's always a `cname`. For mirror failover properties, it can be any set of servers. For load balanced properties, this is a set of servers that are all within the same data center. You can assign multiple traffic targets to the same data center.", "properties": { "precedence": { "description": "For use by `ranked-failover` type properties, the lower the number, the higher the precedence.", "maximum": 255, "minimum": 0, "type": "number" } }, "type": "object" } ], "title": "traffic target v1.6", "x-akamai": { "file-path": "schemas/traffic-target-v1.6.yaml" } }, { "description": "This specifies where to direct data center traffic. For geographic mapped properties, it's always a `cname`. For mirror failover properties, it can be any set of servers. For load balanced properties, this is a set of servers that are all within the same data center. You can assign multiple traffic targets to the same data center.", "type": "object" } ], "title": "traffic target v1.7", "x-akamai": { "file-path": "schemas/traffic-target-v1.7.yaml" } }, { "additionalProperties": true, "description": "This specifies where to direct data center traffic. For geographic mapped properties, it's always a `cname`. For mirror failover properties, it can be any set of servers. For load balanced properties, this is a set of servers that are all within the same data center. You can assign multiple traffic targets to the same data center.", "properties": { "handoutCName": { "deprecated": true, "description": "__Deprecated__ Use `handoutRRSets` instead. Specifies an optional data center for the property. Uses the `handoutCName` when there are no servers configured for the property. If both `handoutCName` and `handoutRRSets` are set, `handoutRRSets` must contain a single CNAME record matching the `handoutCName` value.", "maxLength": 255, "nullable": true, "type": "string", "x-akamai": { "status": "DEPRECATED" } }, "handoutRRSets": { "description": "__v1.8__ An array of DNS recordsets to hand out for this traffic target. Each recordset contains a DNS record `type`, an array of `rdata` strings, and a `ttl`. Replaces the recated `handoutCName` field, enabling richer DNS responses such as A, AAAA, TXT, and other record types in addition to CNAME. If `handoutCName` is also set, `handoutRRSets` must contain a single CNAME record matching the `handoutCName` value. For non-CNAME handouts, `handoutCName` must be `null`.", "items": { "additionalProperties": false, "properties": { "rdata": { "description": "An array of data strings for this recordset. The format depends on the record `type`.", "items": { "type": "string" }, "type": "array" }, "ttl": { "description": "The time to live in seconds for this recordset.", "minimum": 0, "type": "integer" }, "type": { "description": "The DNS record type. Valid values are: `A`, `AAAA`, `AFSDB`, `CAA`, `CNAME`, `HINFO`, `HTTPS`, `LOC`, `MX`, `NAPTR`, `NS`, `PTR`, `RP`, `SOA`, `SVCB`, or `TXT`.", "enum": [ "A", "AAAA", "AFSDB", "CAA", "CNAME", "HINFO", "HTTPS", "LOC", "MX", "NAPTR", "NS", "PTR", "RP", "SOA", "SVCB", "TXT" ], "type": "string" } }, "required": [ "type", "rdata", "ttl" ], "type": "object" }, "nullable": true, "type": "array", "x-akamai": { "labels": [ "v1.8" ] } } }, "type": "object" } ], "title": "traffic target v1.8", "x-akamai": { "file-path": "schemas/traffic-target-v1.8.yaml" } }, "type": "array" }, "type": { "description": "Specifies the load balancing behavior for the property. Possible values are: `failover`, `geographic`, `cidrmapping`, `weighted-round-robin`, `weighted-hashed`, `weighted-round-robin-load-feedback`, `qtr`, `performance`, `performance-with-load-feedback`, `asmapping`, `static`, or `ranked-failover`. See [API versioning](https://techdocs.akamai.com/gtm/reference/api-versioning) for more information.", "enum": [ "failover", "geographic", "cidrmapping", "weighted-round-robin", "weighted-hashed", "weighted-round-robin-load-feedback", "qtr", "performance", "performance-with-load-feedback", "asmapping", "static", "ranked-failover" ], "type": "string" } }, "required": [ "type", "trafficTargets", "livenessTests", "handoutLimit" ], "type": "object" } ], "title": "Property v1.8", "type": "object", "x-akamai": { "file-path": "schemas/property-vnd-config-gtm.v1.8.yaml" } }, "type": "array" } }, "type": "object", "x-akamai": { "file-path": "schemas/get-all-properties-v1.8.yaml" } } } }, "required": true }, "responses": { "200": { "content": { "application/property-vnd-config-gtm.v1.8+json": { "example": { "resource": { "items": [ { "backupCName": null, "backupIp": null, "balanceByDownloadScore": false, "dynamicTTL": 300, "failbackDelay": 0, "failoverDelay": 0, "handoutMode": "normal", "ipv6": false, "lastModified": "2014-04-07T16:21:27.000Z", "links": [ { "href": "/config-gtm/v1/domains/example.akadns.net/properties/www", "rel": "self" } ], "livenessTests": [ { "disableNonstandardPortWarning": false, "hostHeader": "foo.example.com", "httpError3xx": true, "httpError4xx": true, "httpError5xx": true, "name": "health-check", "requestString": null, "responseString": null, "sslClientCertificate": null, "sslClientPrivateKey": null, "testInterval": 60, "testObject": "/status", "testObjectPassword": null, "testObjectPort": 80, "testObjectProtocol": "HTTP", "testObjectUsername": null, "testTimeout": 10 } ], "mapName": null, "mxRecords": [], "name": "www", "scoreAggregationType": "mean", "staticTTL": 600, "stickinessBonusConstant": 0, "stickinessBonusPercentage": 0, "trafficTargets": [ { "datacenterId": 3134, "enabled": true, "servers": [ "192.0.2.98" ], "weight": 0 }, { "datacenterId": 3133, "enabled": true, "servers": [ "192.0.2.146" ], "weight": 1 } ], "type": "failover", "useComputedTargets": false } ] }, "status": { "changeId": "66c7ff0b-4b9e-41cc-9fd0-34d4f75c2484", "links": [ { "href": "/config-gtm/v1/domains/example.akadns.net/status/current", "rel": "self" } ], "message": "Change Pending", "passingValidation": true, "propagationStatus": "PENDING", "propagationStatusDate": "2014-04-03T21:18:01.000+0000" } }, "schema": { "additionalProperties": true, "properties": { "resource": { "additionalProperties": true, "description": "The updated list of properties for the domain.", "properties": { "items": { "description": "The list of a domain's properties.", "items": { "allOf": [ { "additionalProperties": true, "description": "The entire GTM property configuration.", "properties": { "backupCName": { "description": "Specifies a `backupCName`. If GTM declares that all of the servers configured for your property are down, and you configured a `backupCName`, then queries for the property return the `backupCName`. If a `backupCName` is set, don't set a `backupIp`.", "nullable": true, "type": "string" }, "backupIp": { "description": "Specifies a backup IP. When GTM declares that all of the targets are down, it hands out the `backupIP`. The IP type coincides with the property's `iPv6` setting. If a `backupIp` is set, don't set a `backupCName`.", "nullable": true, "type": "string" }, "balanceByDownloadScore": { "description": "Indicates whether download score based load balancing is enabled. GTM estimates the load on your data centers based on how long they take to respond to GTM liveness tests. The advantage: you don't need to implement a load object. The disadvantage: it's a very crude measure of load, and usually highly nonlinear. As load increases, download times don't increase significantly, until there's too much load. When that happens, the download times skyrocket. This can easily cause erratic load balancing or load oscillations.", "type": "boolean" }, "cname": { "description": "Indicates the fully qualified name aliased to a particular property. The public name of the property.", "nullable": true, "type": "string" }, "comments": { "description": "Provides information about the purpose of the property.", "nullable": true, "type": "string" }, "dynamicTTL": { "default": 60, "description": "Indicates the TTL in seconds for records that might change dynamically based on liveness and load balancing such as A and AAAA records, and CNAMEs. The value ranges from `30` to `3600` and can change on request. The default is `60`.", "maximum": 3600, "minimum": 30, "type": "integer" }, "failbackDelay": { "description": "Specifies the failback delay in seconds. The minimum value is `0`. If specified, when a server has been down and comes back up, (that is, its liveness test starts succeeding again), GTM only considers it up after the failback delay has elapsed and tests continue to succeed.", "minimum": 0, "nullable": true, "type": "integer" }, "failoverDelay": { "description": "Specifies the failover delay in seconds. The minimum value is `0`. If specified, when a server begins failing its liveness test, GTM only considers it down after the failover delay has elapsed and the errors persist.", "minimum": 0, "nullable": true, "type": "integer" }, "handoutMode": { "default": "normal", "description": "Specifies how IPs are returned when more than one IP is alive and available. Possible values are: `normal`, `persistent`, `one-ip`, `one-ip-hashed`, or `all-live-ips`. The default is `normal`. Handout mode is relevant only when you have more than one server IP in a data center.", "enum": [ "normal", "persistent", "one-ip", "one-ip-hashed", "all-live-ips" ], "type": "string" }, "healthMax": { "description": "Defines the absolute limit beyond which IPs are declared unhealthy. If backup CNAMEs are provided for a property, then it's reasonable for all IPs to be declared unhealthy. The `healthMax` value is multiplied by the smaller of the `timeoutPenalty` and the `errorPenalty`. This check declares as down any server with a score greater than this product. The default value is `null`.", "nullable": true, "type": "number" }, "healthMultiplier": { "description": "Configures a cutoff value that's computed from the median scores. Any server with a score over the cutoff value is considered down, and load isn't sent to it. The cutoff is computed from the minimum score across all data centers, for a given property and two object fields: `healthMultiplier` and `healthThreshold`. The cutoff is either `healthMultiplier` (default value: 1.5) times the minimum score, or the `healthThreshold` (default value: 4), whichever is greater. See also `healthThreshold` within this object. For more information on how to determine server liveness, see the [Global Traffic Management User Guide](https://techdocs.akamai.com/gtm/docs/welcome-to-global-traffic-management).", "nullable": true, "type": "number" }, "healthThreshold": { "description": "Configures a cutoff value that's computed from the median scores. Any server with a score over the cutoff value is considered down, and load isn't sent to it. See also `healthMultiplier` within this object. For more information on how to determine server liveness, see the [Global Traffic Management User Guide](https://techdocs.akamai.com/gtm/docs/welcome-to-global-traffic-management).", "nullable": true, "type": "number" }, "ipv6": { "description": "Indicates the type of IP address handed out by a property. A `true` value indicates that all IP addresses specified are IPv6, and all hostnames need to resolve to AAAA records. A `false` value indicates IPv4 addresses, and all hostnames need to resolve to A records.", "type": "boolean" }, "lastModified": { "description": "An ISO 8601 timestamp indicating when the property was last changed.", "nullable": true, "type": "string" }, "links": { "description": "A URL path that allows direct navigation to the property.", "items": { "additionalProperties": false, "description": "Lists navigable URLs to resources.", "properties": { "href": { "description": "Provides a hypermedia link to the complete URL that uniquely defines a resource.", "type": "string" }, "rel": { "description": "Indicates the link relationship of the object.", "type": "string" } }, "type": "object", "x-akamai": { "file-path": "schemas/link.yaml" } }, "type": "array" }, "loadImbalancePercentage": { "description": "Indicates the percent of load imbalance factor (LIF) for the domain. It lets GTM exceed the value configured for traffic distribution. For example, if the data center's traffic allocation is 25 percent and the LIF is 1.5, the demand can grow to 37.5 percent (25% × 1.5) before the load balancer starts shifting load away from it. If the LIF is `0`, no load imbalance is allowed. However, internally, GTM adds one to the LIF to allow its use as a multiplier. The default LIF is 1.1, which is displayed as `10.0` percent. The value ranges from `0` to `1000000` percent.", "maximum": 1000000, "minimum": 0, "nullable": true, "type": "number" }, "mapName": { "description": "A descriptive label for a geographic map or a CIDR map that's required if the property is either `geographic` or `cidrmapping`, in which case `mapName` needs to reference either an existing geographic map or CIDR map in the same domain.", "nullable": true, "type": "string" }, "maxUnreachablePenalty": { "description": "For `performance` domains, this specifies a penalty value that's added to liveness test scores when data centers show an aggregated loss fraction higher than the penalty value. The penalty value is either `maxUnreachablePenalty` (minimum value is `0` and the default is `null`) or `unreachableThreshold` (decimal between `0` and `1`. A value of 1.0 or `null` disables an unreachable penalty). See also `unreachableThreshold` within this object.", "minimum": 0, "nullable": true, "type": "number" }, "mxRecords": { "description": "Specifies the MX records handed out to `MX` record type queries. Note that mapping and liveness testing aren't done. The same MX records are handed out for every request.", "items": { "additionalProperties": false, "properties": { "exchange": { "description": "MX record exchange field.", "type": "string" }, "preference": { "description": "MX record preference field.", "type": "number" } }, "required": [ "exchange", "preference" ], "type": "object" }, "type": "array" }, "name": { "description": "The value, together with the full GTM `domainName`, forms the property's hostname. The value should not begin or end with a dot character and needs to be a valid [RFC 1123](https://tools.ietf.org/html/rfc1123) hostname. Set the name to `@` if the property is to be located at the apex of the domain.", "oneOf": [ { "format": "hostname", "title": "Hostname", "type": "string" }, { "enum": [ "@" ], "title": "apex", "type": "string" } ] }, "scoreAggregationType": { "default": "worst", "description": "Specifies how GTM aggregates liveness test scores across different tests, when multiple tests are configured. Possible values are: `mean`, `median`, `best`, or the default `worst`.", "enum": [ "mean", "median", "best", "worst" ], "type": "string" }, "staticTTL": { "description": "Specifies the TTL in seconds for static resource records that don't change based on the requesting name server IP. This includes MX, TXT, and SPF records.", "maximum": 3600, "minimum": 30, "nullable": true, "type": "integer" }, "stickinessBonusConstant": { "description": "Specifies a constant used to configure data center affinity. This only applies if the property `type` is `performance` and the domain `type` is `full`. The value ranges from `0` to `30000`. See also `stickinessBonusPercentage` within this object. To learn more about how these object fields relate to each other, see [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "maximum": 30000, "minimum": 0, "nullable": true, "type": "integer" }, "stickinessBonusPercentage": { "description": "Specifies a percentage used to configure data center affinity. This only applies if the property `type` is `performance` and the domain `type` is `full`. The value ranges from `0` to `100`. See also `stickinessBonusConstant` within this object. To learn more about how these object fields relate to each other, see [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "maximum": 100, "minimum": 0, "nullable": true, "type": "integer" }, "unreachableThreshold": { "description": "For `performance` domains, this specifies a penalty value that's added to liveness test scores when data centers have an aggregated loss fraction higher than this value. The value is a decimal between `0` and `1`. A value of `1.0` or `null` disables an unreachable penalty. See also `maxUnreachablePenalty` within this object.", "maximum": 1, "minimum": 0, "nullable": true, "type": "number" }, "useComputedTargets": { "description": "For `load-feedback` domains only, this specifies that you want GTM to automatically compute target load. Report only the current load objects, either by omission, or by using non-XML load objects.", "type": "boolean" } }, "required": [ "backupCName", "backupIp", "dynamicTTL", "failbackDelay", "failoverDelay", "handoutMode", "ipv6", "mapName", "mxRecords", "name", "scoreAggregationType", "staticTTL" ], "type": "object", "x-akamai": { "file-path": "schemas/property-vnd-config-gtm-nested-not-versioned.v1.0.yaml" } }, { "additionalProperties": true, "description": "The entire GTM property configuration.", "properties": { "ghostDemandReporting": { "description": "__v1.3__ Enables reporting of unmet content requests received by edge servers, analyzing demand for unserved content.", "type": "boolean", "x-akamai": { "labels": [ "v1.3" ] } }, "handoutLimit": { "description": "__v1.3__ Indicates the limit for the number of live IPs handed out to a DNS request. The `handoutLimit` applies only if `handoutMode` is set to either `normal` or `persistent` for the property. If applicable, the `handoutLimit` default value is `8` or `null` if not.", "minimum": 1, "nullable": true, "type": "integer", "x-akamai": { "labels": [ "v1.3" ] } }, "livenessTests": { "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "items": { "allOf": [ { "allOf": [ { "allOf": [ { "allOf": [ { "allOf": [ { "allOf": [ { "allOf": [ { "additionalProperties": true, "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "properties": { "disableNonstandardPortWarning": { "default": false, "description": "Disables warnings when non-standard ports are used. For example, GTM doesn't emit a warning to specify port 1234 when the `testObjectProtocol` is `http`, as HTTP typically uses port 80. The default is `false`.", "type": "boolean" }, "hostHeader": { "description": "Sent if the `testObjectProtocol` is `http` or `https`, up to 256 non-space, alphanumeric characters. Obsolete as of version 1.4. You should use `hostHeaders` instead.", "maxLength": 256, "minLength": 1, "nullable": true, "type": "string" }, "httpError3xx": { "description": "Treats a 3xx HTTP response as a failure if the `testObjectProtocol` is `http`, `https`, or `ftp`.", "type": "boolean" }, "httpError4xx": { "description": "Treats a 4xx HTTP response as a failure if the `testObjectProtocol` is `http`, `https`, or `ftp`.", "type": "boolean" }, "httpError5xx": { "description": "Treats a 5xx HTTP response as a failure if the `testObjectProtocol` is `http`, `https`, or `ftp`.", "type": "boolean" }, "name": { "description": "A descriptive name for the liveness test.", "maxLength": 128, "minLength": 1, "type": "string" }, "requestString": { "description": "Specifies a request string. Required if `testObjectProtocol` is `tcp` or `tcps`. The value is a maximum of 4000 non-space, alphanumeric characters.", "maxLength": 4000, "minLength": 1, "nullable": true, "type": "string" }, "responseString": { "description": "Specifies a response string. Required if `testObjectProtocol` is `tcp` or `tcps`. Maximum 4000 characters.", "maxLength": 4000, "nullable": true, "type": "string" }, "sslClientCertificate": { "description": "Indicates a Base64-encoded certificate. SSL client certificates are available for `livenessTests` that use secure protocols.", "nullable": true, "type": "string" }, "sslClientPrivateKey": { "description": "Indicates a Base64-encoded private key. The private key used to generate or request a certificate for `livenessTests` can't have a passphrase nor be used for any other purpose.", "nullable": true, "type": "string" }, "testInterval": { "description": "Indicates the interval at which the liveness test is run, in seconds. Requires a minimum of 10 seconds.", "minimum": 10, "type": "integer" }, "testObject": { "description": "Specifies the static text that acts as a stand-in for the data that you're sending on the network.", "maxLength": 256, "minLength": 1, "nullable": true, "type": "string" }, "testObjectPassword": { "description": "Specifies the test object's password. It's required if `testObjectProtocol` is `ftp`. Maximum is 128 characters.", "maxLength": 128, "minLength": 1, "nullable": true, "type": "string" }, "testObjectPort": { "description": "Specifies the port number for the `testObject`. Value from `1` to `65535`.", "maximum": 65535, "minimum": 1, "type": "integer" }, "testObjectProtocol": { "description": "Specifies the test protocol. Possible values are: `DNS`, `DOH`, `DOT`, `HTTP`, `HTTPS`, `HTTP2`, `HTTP2S`, `FTP`, `POP`, `POPS`, `SMTP`, `SMTPS`, `TCP`, or `TCPS`. To enable `testObjectProtocol` for `DNS`, `DOH`, or `DOT` requires `application/vnd.config-gtm.v1.3+json`.", "enum": [ "DNS", "DOH", "DOT", "HTTP", "HTTPS", "HTTP2", "HTTP2S", "FTP", "POP", "POPS", "SMTP", "SMTPS", "TCP", "TCPS" ], "type": "string" }, "testObjectUsername": { "description": "A descriptive name for the `testObject`. If `testObjectProtocol` is `ftp`, then you need to specify a `testObjectUsername`. The value is a maximum of 256 non-space, alphanumeric characters.", "maxLength": 512, "minLength": 1, "nullable": true, "type": "string" }, "testTimeout": { "description": "Specifies the duration of the liveness test before it fails. The range is from `0.001` to `60` seconds.", "maximum": 60, "minimum": 0.001, "type": "number" } }, "required": [ "disableNonstandardPortWarning", "hostHeader", "httpError3xx", "httpError4xx", "httpError5xx", "name", "requestString", "responseString", "sslClientCertificate", "sslClientPrivateKey", "testInterval", "testObject", "testObjectPassword", "testObjectPort", "testObjectProtocol", "testObjectUsername", "testTimeout" ], "type": "object", "x-akamai": { "file-path": "schemas/liveness-test-v1.0.yaml" } }, { "additionalProperties": true, "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "properties": { "errorPenalty": { "default": 75, "description": "__v1.2__ Specifies the score that's reported if the liveness test encounters an error other than timeout, such as connection refused, and 404. The default value is `75`.", "minimum": 0, "type": "number", "x-akamai": { "labels": [ "v1.2" ] } }, "timeoutPenalty": { "default": 25, "description": "__v1.2__ Specifies the score reported if the liveness test times out. This is independent of the liveness `testTimeout` value. The default value is `25` seconds.", "minimum": 0, "type": "number", "x-akamai": { "labels": [ "v1.2" ] } } }, "required": [ "errorPenalty", "timeoutPenalty" ], "type": "object" } ], "title": "livenessTest v1.2", "x-akamai": { "file-path": "schemas/liveness-test-v1.2.yaml" } }, { "additionalProperties": true, "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "properties": { "answersRequired": { "default": false, "description": "__v1.3__ If `testObjectProtocol` is `DNS`, `DOH` or `DOT`, requires an answer to the DNS query to be considered a success. The default is `false`.", "type": "boolean", "x-akamai": { "labels": [ "v1.3" ] } }, "peerCertificateVerification": { "default": false, "description": "__v1.3__ Validates the origin certificate. Applies only to tests with `testObjectProtocol` of `https`. The default is `false`.", "type": "boolean", "x-akamai": { "labels": [ "v1.3" ] } }, "recursionRequested": { "default": false, "description": "__v1.3__ Indicates that if `testObjectProtocol` is `DNS`, `DOH` or `DOT`, the `DNS` query is recursive. The default is `false`.", "type": "boolean", "x-akamai": { "labels": [ "v1.3" ] } }, "resourceType": { "description": "__v1.3__ Specifies the query type, if `testObjectProtocol` is `DNS`. Possible values are: `A`, `AAAA`, `AFSDB`, `CNAME`, `HINFO`, `LOC`, `MX`, `NAPTR`, `NS`, `PTR`, `RP`, `SOA`, `SPF`, `SRV`, `SSHFP`, `TXT`, `DNSKEY`, `DS`, `NSEC3`, `NSEC3PARAM`, or `RRSIG`. Unknown types `TYPENNNNN` are also supported, where `NNNNN` is an integer from `1` through `65535`.", "enum": [ "A", "AAAA", "AFSDB", "CNAME", "HINFO", "LOC", "MX", "NAPTR", "NS", "PTR", "RP", "SOA", "SPF", "SRV", "SSHFP", "TXT", "DNSKEY", "DS", "NSEC3", "NSEC3PARAM", "RRSIG" ], "nullable": true, "type": "string", "x-akamai": { "labels": [ "v1.3" ] } } }, "required": [ "answersRequired", "resourceType", "recursionRequested", "peerCertificateVerification" ], "type": "object" } ], "title": "livenessTest v1.3", "x-akamai": { "file-path": "schemas/liveness-test-v1.3.yaml" } }, { "additionalProperties": true, "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "properties": { "disabled": { "default": false, "description": "__v1.4__ Disables the liveness test. When disabled, GTM stops running the test, treating it as if it no longer exists. The default is `false`.", "type": "boolean", "x-akamai": { "labels": [ "v1.4" ] } }, "httpHeaders": { "description": "__v1.4__ HTTP headers to send if the `testObjectProtocol` is `http` or `https`. This `hostHeader` is deprecated as of version 1.4.", "items": { "additionalProperties": false, "properties": { "name": { "description": "Name of the HTTP header.", "minLength": 1, "type": "string" }, "value": { "description": "Value of the HTTP header.", "type": "string" } }, "required": [ "name", "value" ], "type": "object" }, "type": "array", "x-akamai": { "labels": [ "v1.4" ] } } }, "type": "object" } ], "title": "livenessTest v1.4", "x-akamai": { "file-path": "schemas/liveness-test-v1.4.yaml" } }, { "additionalProperties": true, "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "properties": { "alternateCACertificates": { "description": "__v1.5__ Alternate trust anchors, Base64-encoded CA certificates. Available for `livenessTests` that use secure protocols.", "items": { "type": "string" }, "type": "array", "x-akamai": { "labels": [ "v1.5" ] } }, "httpMethod": { "default": "GET", "description": "__v1.5__ The HTTP method to send if the `testObjectProtocol` is `http` or `https`. Possible values are: `TRACE`, `HEAD`, `OPTIONS`, `GET`, `PUT`, `POST`, `PATCH`, or `DELETE`. When omitted or `null`, this value defaults to `GET`.", "enum": [ "TRACE", "HEAD", "OPTIONS", "GET", "PUT", "POST", "PATCH", "DELETE" ], "nullable": true, "type": "string", "x-akamai": { "labels": [ "v1.5" ] } }, "httpRequestBody": { "description": "__v1.5__ The Base64-encoded HTTP request body to send if the `testObjectProtocol` is `http` or `https`. When omitted or `null`, omits the request body from the request.", "nullable": true, "type": "string", "x-akamai": { "labels": [ "v1.5" ] } } }, "type": "object" } ], "title": "livenessTest v1.5", "x-akamai": { "file-path": "schemas/liveness-test-v1.5.yaml" } }, { "additionalProperties": true, "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "properties": { "pre2023SecurityPosture": { "default": false, "description": "__v1.6__ Indicates whether the system uses a security posture configuration from before 2023. Defaults to false.", "type": "boolean", "x-akamai": { "labels": [ "v1.6" ] } } }, "type": "object" } ], "title": "livenessTest v1.6", "x-akamai": { "file-path": "schemas/liveness-test-v1.6.yaml" } }, { "description": "Liveness tests, which run periodically to determine whether your servers respond to requests, as discussed in [API concepts](https://techdocs.akamai.com/gtm/reference/api-concepts).", "type": "object" } ], "title": "livenessTest v1.7", "x-akamai": { "file-path": "schemas/liveness-test-v1.7.yaml" } }, { "description": "Liveness tests, which run periodically to determine whether your servers respond to requests.", "type": "object" } ], "title": "livenessTest v1.8", "x-akamai": { "file-path": "schemas/liveness-test-v1.8.yaml" } }, "type": "array" }, "minActiveDatacenterFraction": { "default": null, "description": "__v1.7__ The fraction of data centers that must be passing their liveness tests in order for the selection of live data centers to occur. For example, if this is set to `0.75` and only half the data centers are passing their liveness tests, then all data centers are handed out regardless of liveness test results. A `null` or `0` value means the feature is disabled and behavior is unchanged. The default value is `null`.", "maximum": 1, "minimum": 0, "nullable": true, "type": "number", "x-akamai": { "labels": [ "v1.7" ] } }, "minLiveFraction": { "description": "__v1.3__ Specifies what fraction of the servers need to respond to requests so GTM considers the data center up and able to receive traffic. For example, if your data center contains eight servers, and the `minLiveFraction` value is `0.5`, then at least four servers need to respond to requests. Conversely, if five servers are down, and three servers are up, then GTM considers the entire data center down. Optional when a `minLiveFraction` value exists or not `null`.", "maximum": 1, "minimum": 0, "nullable": true, "type": "number", "x-akamai": { "labels": [ "v1.3" ] } }, "stateChangeNotificationWebhook": { "additionalProperties": false, "description": "__v1.7__ Configures a webhook to receive notifications when the property's state changes. Set to `null` to disable notifications.", "nullable": true, "properties": { "format": { "default": "json-compact", "description": "The format of the notification payload. Possible values are: `json-compact`, `json-pretty`, or `slack-mrkdwn`. The default value is `json-compact`.", "enum": [ "json-compact", "json-pretty", "slack-mrkdwn" ], "type": "string" }, "url": { "description": "The URL to send the notification to. Only `http`, `https`, and `mailto` schemes are allowed. If the host is a name, it must resolve to a routable address. If the host is an IP address, it must be routable.", "maxLength": 1024, "type": "string" } }, "required": [ "url" ], "type": "object", "x-akamai": { "labels": [ "v1.7" ] } }, "staticRRSets": { "description": "__v1.4__ Static recordsets. Use this instead of `mxRecords` and `staticTTL`, which were deprecated in version 1.4.", "items": { "additionalProperties": false, "properties": { "rdata": { "description": "An array of data strings, representing multiple records within a set. The format of the `rdata` strings are dependent on the `type` of this record.", "items": { "type": "string" }, "type": "array" }, "ttl": { "description": "The number of seconds that this record should live in a resolver's cache before being refetched.", "type": "integer" }, "type": { "description": "The record type.", "type": "string" } }, "required": [ "type", "ttl", "rdata" ], "type": "object" }, "type": "array", "x-akamai": { "labels": [ "v1.4" ] } }, "trafficTargets": { "description": "This specifies where to direct data center traffic. For geographic mapped properties, it's always a `cname`. For mirror failover properties, it can be any set of servers. For load balanced properties, this is a set of servers that are all within the same data center. You can assign multiple traffic targets to the same data center.", "items": { "allOf": [ { "allOf": [ { "allOf": [ { "additionalProperties": true, "description": "This specifies where to direct data center traffic. For geographic mapped properties, it's always a `cname`. For mirror failover properties, it can be any set of servers. For load balanced properties, this is a set of servers that are all within the same data center. You can assign multiple traffic targets to the same data center.", "properties": { "datacenterId": { "description": "A unique identifier for an existing data center in the domain.", "type": "integer" }, "enabled": { "description": "Indicates whether the traffic target is used. You can also omit the traffic target, which has the same result as the `false` value. However, when the value is `false`, GTM continues to store the other traffic target fields in the database. There's no need to store them locally should you want to use the traffic target at a later time.", "type": "boolean" }, "handoutCName": { "description": "Specifies an optional data center for the property. Uses the `handoutCName` when there are no servers configured for the property. Maximum 63 characters for the labels, 255 characters overall. May contain alphanumeric, hyphens, and underscores, but not literal IP addresses. Leading or trailing hyphens aren't allowed.", "maxLength": 255, "nullable": true, "type": "string" }, "name": { "description": "An alternative label for the traffic target.", "nullable": true, "type": "string" }, "servers": { "description": "Identifies the IP address or the hostnames of the servers. For hostnames that return IP addresses, tests all IP addresses for liveness.", "items": { "type": "string" }, "type": "array" }, "weight": { "description": "Specifies the traffic weight for the target. This is required when the enclosing property is `failover`, `weighted`, `weighted-with-load-feedback`, or `performance`. The sum of this value, for all enabled targets, can be any number, percentage, or ratio. For example, you can express a traffic split as 60/40, 120/80, or 3/2, all equivalent values. For `failover` properties, set this value to `1` for the traffic target you want to mark as _primary_.", "minimum": 0, "type": "number" } }, "type": "object", "x-akamai": { "file-path": "schemas/traffic-target-v1.0.yaml" } }, { "additionalProperties": true, "description": "This specifies where to direct data center traffic. For geographic mapped properties, it's always a `cname`. For mirror failover properties, it can be any set of servers. For load balanced properties, this is a set of servers that are all within the same data center. You can assign multiple traffic targets to the same data center.", "properties": { "precedence": { "description": "For use by `ranked-failover` type properties, the lower the number, the higher the precedence.", "maximum": 255, "minimum": 0, "type": "number" } }, "type": "object" } ], "title": "traffic target v1.6", "x-akamai": { "file-path": "schemas/traffic-target-v1.6.yaml" } }, { "description": "This specifies where to direct data center traffic. For geographic mapped properties, it's always a `cname`. For mirror failover properties, it can be any set of servers. For load balanced properties, this is a set of servers that are all within the same data center. You can assign multiple traffic targets to the same data center.", "type": "object" } ], "title": "traffic target v1.7", "x-akamai": { "file-path": "schemas/traffic-target-v1.7.yaml" } }, { "additionalProperties": true, "description": "This specifies where to direct data center traffic. For geographic mapped properties, it's always a `cname`. For mirror failover properties, it can be any set of servers. For load balanced properties, this is a set of servers that are all within the same data center. You can assign multiple traffic targets to the same data center.", "properties": { "handoutCName": { "deprecated": true, "description": "__Deprecated__ Use `handoutRRSets` instead. Specifies an optional data center for the property. Uses the `handoutCName` when there are no servers configured for the property. If both `handoutCName` and `handoutRRSets` are set, `handoutRRSets` must contain a single CNAME record matching the `handoutCName` value.", "maxLength": 255, "nullable": true, "type": "string", "x-akamai": { "status": "DEPRECATED" } }, "handoutRRSets": { "description": "__v1.8__ An array of DNS recordsets to hand out for this traffic target. Each recordset contains a DNS record `type`, an array of `rdata` strings, and a `ttl`. Replaces the recated `handoutCName` field, enabling richer DNS responses such as A, AAAA, TXT, and other record types in addition to CNAME. If `handoutCName` is also set, `handoutRRSets` must contain a single CNAME record matching the `handoutCName` value. For non-CNAME handouts, `handoutCName` must be `null`.", "items": { "additionalProperties": false, "properties": { "rdata": { "description": "An array of data strings for this recordset. The format depends on the record `type`.", "items": { "type": "string" }, "type": "array" }, "ttl": { "description": "The time to live in seconds for this recordset.", "minimum": 0, "type": "integer" }, "type": { "description": "The DNS record type. Valid values are: `A`, `AAAA`, `AFSDB`, `CAA`, `CNAME`, `HINFO`, `HTTPS`, `LOC`, `MX`, `NAPTR`, `NS`, `PTR`, `RP`, `SOA`, `SVCB`, or `TXT`.", "enum": [ "A", "AAAA", "AFSDB", "CAA", "CNAME", "HINFO", "HTTPS", "LOC", "MX", "NAPTR", "NS", "PTR", "RP", "SOA", "SVCB", "TXT" ], "type": "string" } }, "required": [ "type", "rdata", "ttl" ], "type": "object" }, "nullable": true, "type": "array", "x-akamai": { "labels": [ "v1.8" ] } } }, "type": "object" } ], "title": "traffic target v1.8", "x-akamai": { "file-path": "schemas/traffic-target-v1.8.yaml" } }, "type": "array" }, "type": { "description": "Specifies the load balancing behavior for the property. Possible values are: `failover`, `geographic`, `cidrmapping`, `weighted-round-robin`, `weighted-hashed`, `weighted-round-robin-load-feedback`, `qtr`, `performance`, `performance-with-load-feedback`, `asmapping`, `static`, or `ranked-failover`. See [API versioning](https://techdocs.akamai.com/gtm/reference/api-versioning) for more information.", "enum": [ "failover", "geographic", "cidrmapping", "weighted-round-robin", "weighted-hashed", "weighted-round-robin-load-feedback", "qtr", "performance", "performance-with-load-feedback", "asmapping", "static", "ranked-failover" ], "type": "string" } }, "required": [ "type", "trafficTargets", "livenessTests", "handoutLimit" ], "type": "object" } ], "title": "Property v1.8", "type": "object", "x-akamai": { "file-path": "schemas/property-vnd-config-gtm.v1.8.yaml" } }, "type": "array" } }, "type": "object", "x-akamai": { "file-path": "schemas/get-all-properties-v1.8.yaml" } }, "status": { "additionalProperties": false, "description": "The status of the domain change request.", "properties": { "changeId": { "description": "__Read-only__ A unique identifier generated when a change occurs to the domain.", "maxLength": 36, "minLength": 36, "readOnly": true, "type": "string" }, "links": { "description": "Specifies the URL path that allows direct navigation to the domain.", "items": { "additionalProperties": false, "description": "Lists navigable URLs to resources.", "properties": { "href": { "description": "Provides a hypermedia link to the complete URL that uniquely defines a resource.", "type": "string" }, "rel": { "description": "Indicates the link relationship of the object.", "type": "string" } }, "type": "object", "x-akamai": { "file-path": "schemas/link.yaml" } }, "type": "array" }, "message": { "description": "__Read-only__ A notification generated when a change occurs to the domain. The maximum length is 4000 characters.", "maxLength": 4000, "readOnly": true, "type": "string" }, "passingValidation": { "description": "__Read-only__ Indicates if the domain validates.", "readOnly": true, "type": "boolean" }, "propagationStatus": { "description": "Tracks the status of the domain's propagation state. Possible values are: `PENDING`, `COMPLETE`, or `DENIED`. A `DENIED` value indicates that the domain configuration is invalid, and doesn't propagate until the validation errors are resolved.", "enum": [ "PENDING", "COMPLETE", "DENIED" ], "maxLength": 20, "type": "string" }, "propagationStatusDate": { "description": "__Read-only__ An ISO 8601 timestamp indicating when a change occurs to the domain.", "format": "date-time", "readOnly": true, "type": "string" } }, "type": "object", "x-akamai": { "file-path": "schemas/status.yaml" } } }, "type": "object", "x-akamai": { "file-path": "schemas/update-properties-response-v1.8.yaml" } } } }, "description": "Properties added or updated successfully." } }, "summary": "Add or update properties", "tags": [ "Properties" ] }, "parameters": [ { "description": "The full GTM domain name.", "in": "path", "name": "domainName", "required": true, "schema": { "example": "example.akadns.net", "type": "string" }, "x-akamai": { "file-path": "parameters/domain-name-path.yaml" } } ], "x-akamai": { "file-path": "paths/properties.yaml", "path-info": "/domains/{domainName}/properties" } } }, "servers": [ { "url": "https://{hostname}/config-gtm/v1" } ], "x-akamai": { "auth-type": "EDGE_GRID", "file-path": "04-properties.yaml" }, "x-readme": { "explorer-enabled": false, "samples-languages": [ "curl", "python", "node" ] } } ``` # Sibling pages * [List properties](https://techdocs.akamai.com/gtm/reference/get-properties.md) * [Get a property](https://techdocs.akamai.com/gtm/reference/get-property.md) * [Create or update a property](https://techdocs.akamai.com/gtm/reference/put-property.md) * [Remove a property](https://techdocs.akamai.com/gtm/reference/delete-property.md) * [Replace all properties](https://techdocs.akamai.com/gtm/reference/put-properties.md)