Skip to content

Record sets

All operations require authentication.

5 operationsv2/dns/gslb
View as Markdown (opens in a new tab)
Agent setup

List GSLB record sets in a hosted zoneAlpha

GET
/v2/dns/gslb/zone/{zoneId}/recordSet

Path parameters

zoneId
required
stringuuid

Zone ID

Query parameters

name
string

Filter by exact record set name, ignoring case. The trailing dot is optional.

type
RecordTypeEnum

Filter by DNS record type

ValuesAAAAACNAMEMXTXT

Headers

X-Pagination-Cursor
string

Pagination cursor

X-Pagination-Size
integer

Pagination size

Response

200RecordSet[]successful operation
chainTarget
read-only
string

Target record name for chained routing. Null when the record set is not chained.

coordinates
read-only
Coordinates

Endpoint coordinates for GEOPROXIMITY

createdAt
read-only
stringdate-time

Creation timestamp

evaluateTargetHealth
read-only
boolean

Whether to fall through to the global scope when a GEOLOCATION chain target is unhealthy, always false for other record sets

failover
read-only
FailoverTypeEnum

Failover role of this entry, null for routing policies other than FAILOVER

ValuesPRIMARYSECONDARY
geoLocation
read-only
GeoLocation

Geographic routing scope, required for GEOLOCATION routing. Null when not set.

healthCheckId
read-only
stringuuid

Identifier of the associated health check. Null when no health check is linked.

id
read-only
stringuuid

Unique identifier of the record set

name
read-only
string

Fully qualified domain name with a trailing dot

resourceStatus
read-only
ResourceStatusEnum

Resource lifecycle status

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
routingPolicy
read-only
RoutingPolicyEnum

Traffic routing policy

ValuesFAILOVERGEOLOCATIONGEOPROXIMITYMULTIVALUESIMPLEWEIGHTED
setIdentifier
read-only
string

Identifier distinguishing entries with the same name and type, can be null only for SIMPLE routing

ttl
read-only
integer

Time to live in seconds. Record sets with the same name and type share one TTL. Updating the TTL updates all of them.

type
read-only
RecordTypeEnum

DNS record type

ValuesAAAAACNAMEMXTXT
updatedAt
read-only
stringdate-time

Last modification timestamp

values
read-only
string[]

DNS record values. Empty when chainTarget is set.

weight
read-only
integer

Weight from 0 to 255, required for WEIGHTED routing. Null when not set.

zoneId
read-only
stringuuid

Identifier of the parent hosted zone

400objectError 400 response
404objectError 404 response

Example uses zoneId = 00000000-0000-0000-0000-000000000000

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/zone/{zoneId}/recordSet \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
[ { "chainTarget": "string", "coordinates": { "latitude": 0, "longitude": 0 }, "createdAt": "2024-01-01T12:00:00Z", "evaluateTargetHealth": true, "failover": "PRIMARY", "geoLocation": { "continentCode": "AF", "countryCode": "AC", "subdivisionCode": "string" }, "healthCheckId": "00000000-0000-0000-0000-000000000000", "id": "00000000-0000-0000-0000-000000000000", "name": "string", "resourceStatus": "CREATING", "routingPolicy": "FAILOVER", "setIdentifier": "string", "ttl": 0, "type": "A", "updatedAt": "2024-01-01T12:00:00Z", "values": [ "string" ], "weight": 0, "zoneId": "00000000-0000-0000-0000-000000000000" }]

Get a GSLB record setAlpha

GET
/v2/dns/gslb/zone/{zoneId}/recordSet/{recordSetId}

Path parameters

recordSetId
required
stringuuid

Record set ID

zoneId
required
stringuuid

Zone ID

Response

200RecordSetsuccessful operation
chainTarget
read-only
string

Target record name for chained routing. Null when the record set is not chained.

coordinates
read-only
Coordinates

Endpoint coordinates for GEOPROXIMITY

createdAt
read-only
stringdate-time

Creation timestamp

evaluateTargetHealth
read-only
boolean

Whether to fall through to the global scope when a GEOLOCATION chain target is unhealthy, always false for other record sets

failover
read-only
FailoverTypeEnum

Failover role of this entry, null for routing policies other than FAILOVER

ValuesPRIMARYSECONDARY
geoLocation
read-only
GeoLocation

Geographic routing scope, required for GEOLOCATION routing. Null when not set.

healthCheckId
read-only
stringuuid

Identifier of the associated health check. Null when no health check is linked.

id
read-only
stringuuid

Unique identifier of the record set

name
read-only
string

Fully qualified domain name with a trailing dot

resourceStatus
read-only
ResourceStatusEnum

Resource lifecycle status

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
routingPolicy
read-only
RoutingPolicyEnum

Traffic routing policy

ValuesFAILOVERGEOLOCATIONGEOPROXIMITYMULTIVALUESIMPLEWEIGHTED
setIdentifier
read-only
string

Identifier distinguishing entries with the same name and type, can be null only for SIMPLE routing

ttl
read-only
integer

Time to live in seconds. Record sets with the same name and type share one TTL. Updating the TTL updates all of them.

type
read-only
RecordTypeEnum

DNS record type

ValuesAAAAACNAMEMXTXT
updatedAt
read-only
stringdate-time

Last modification timestamp

values
read-only
string[]

DNS record values. Empty when chainTarget is set.

weight
read-only
integer

Weight from 0 to 255, required for WEIGHTED routing. Null when not set.

zoneId
read-only
stringuuid

Identifier of the parent hosted zone

404objectError 404 response

Example uses recordSetId = 00000000-0000-0000-0000-000000000000, zoneId = 00000000-0000-0000-0000-000000000000

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/zone/{zoneId}/recordSet/{recordSetId} \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "chainTarget": "string", "coordinates": { "latitude": 0, "longitude": 0 }, "createdAt": "2024-01-01T12:00:00Z", "evaluateTargetHealth": true, "failover": "PRIMARY", "geoLocation": { "continentCode": "AF", "countryCode": "AC", "subdivisionCode": "string" }, "healthCheckId": "00000000-0000-0000-0000-000000000000", "id": "00000000-0000-0000-0000-000000000000", "name": "string", "resourceStatus": "CREATING", "routingPolicy": "FAILOVER", "setIdentifier": "string", "ttl": 0, "type": "A", "updatedAt": "2024-01-01T12:00:00Z", "values": [ "string" ], "weight": 0, "zoneId": "00000000-0000-0000-0000-000000000000"}

Create a GSLB record setAlpha

POST
/v2/dns/gslb/zone/{zoneId}/recordSet

Path parameters

zoneId
required
stringuuid

Zone ID

Request body (required)

chainTarget
string

Target record name for chaining, up to three hops. Unavailable for GEOPROXIMITY parents.

coordinates
Coordinates

Endpoint coordinates, required for GEOPROXIMITY routing

evaluateTargetHealth
boolean

Whether to fall through to the global scope when the chain target is unhealthy. Only supported for GEOLOCATION chains.

failover
FailoverTypeEnum

Failover role of this entry, required for FAILOVER routing. PRIMARY requires a health check. Immutable after creation.

ValuesPRIMARYSECONDARY
geoLocation
GeoLocation

Geographic scope of this entry, required for GEOLOCATION routing. An empty object is the global fallback.

healthCheckId
stringuuid

Associated health check. Unsupported for SIMPLE.

name
required
string

Fully qualified domain name in the hosted zone, ending with a dot. Immutable after creation.

routingPolicy
RoutingPolicyEnum

Traffic routing policy, defaults to SIMPLE. Immutable after creation.

ValuesFAILOVERGEOLOCATIONGEOPROXIMITYMULTIVALUESIMPLEWEIGHTED
setIdentifier
string

Identifier that distinguishes entries with the same name and type. Required for non-SIMPLE routing. At most 128 characters.

ttl
required
integer

Time to live in seconds. Record sets with the same name and type share one TTL. The value must equal the TTL of any existing one. From 0 to 2147483647.

type
required
RecordTypeEnum

DNS record type. FAILOVER, GEOLOCATION, MULTIVALUE and GEOPROXIMITY require A or AAAA. Immutable after creation.

ValuesAAAAACNAMEMXTXT
values
string[]

Record values. Required unless chainTarget is set. A CNAME accepts a single value. MULTIVALUE and GEOPROXIMITY accept one value per entry.

weight
integer

Relative weight of this entry for WEIGHTED routing. Required for WEIGHTED routing. From 0 to 255.

Response

200RecordSetsuccessful operation
chainTarget
read-only
string

Target record name for chained routing. Null when the record set is not chained.

coordinates
read-only
Coordinates

Endpoint coordinates for GEOPROXIMITY

createdAt
read-only
stringdate-time

Creation timestamp

evaluateTargetHealth
read-only
boolean

Whether to fall through to the global scope when a GEOLOCATION chain target is unhealthy, always false for other record sets

failover
read-only
FailoverTypeEnum

Failover role of this entry, null for routing policies other than FAILOVER

ValuesPRIMARYSECONDARY
geoLocation
read-only
GeoLocation

Geographic routing scope, required for GEOLOCATION routing. Null when not set.

healthCheckId
read-only
stringuuid

Identifier of the associated health check. Null when no health check is linked.

id
read-only
stringuuid

Unique identifier of the record set

name
read-only
string

Fully qualified domain name with a trailing dot

resourceStatus
read-only
ResourceStatusEnum

Resource lifecycle status

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
routingPolicy
read-only
RoutingPolicyEnum

Traffic routing policy

ValuesFAILOVERGEOLOCATIONGEOPROXIMITYMULTIVALUESIMPLEWEIGHTED
setIdentifier
read-only
string

Identifier distinguishing entries with the same name and type, can be null only for SIMPLE routing

ttl
read-only
integer

Time to live in seconds. Record sets with the same name and type share one TTL. Updating the TTL updates all of them.

type
read-only
RecordTypeEnum

DNS record type

ValuesAAAAACNAMEMXTXT
updatedAt
read-only
stringdate-time

Last modification timestamp

values
read-only
string[]

DNS record values. Empty when chainTarget is set.

weight
read-only
integer

Weight from 0 to 255, required for WEIGHTED routing. Null when not set.

zoneId
read-only
stringuuid

Identifier of the parent hosted zone

400objectError 400 response
403objectError 403 response
404objectError 404 response
409objectError 409 response

Example uses zoneId = 00000000-0000-0000-0000-000000000000

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/zone/{zoneId}/recordSet \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "chainTarget": "string", "coordinates": { "latitude": 0, "longitude": 0 }, "createdAt": "2024-01-01T12:00:00Z", "evaluateTargetHealth": true, "failover": "PRIMARY", "geoLocation": { "continentCode": "AF", "countryCode": "AC", "subdivisionCode": "string" }, "healthCheckId": "00000000-0000-0000-0000-000000000000", "id": "00000000-0000-0000-0000-000000000000", "name": "string", "resourceStatus": "CREATING", "routingPolicy": "FAILOVER", "setIdentifier": "string", "ttl": 0, "type": "A", "updatedAt": "2024-01-01T12:00:00Z", "values": [ "string" ], "weight": 0, "zoneId": "00000000-0000-0000-0000-000000000000"}

Update a GSLB record set. Name, type, routing policy and failover role are immutable.Alpha

PATCH
/v2/dns/gslb/zone/{zoneId}/recordSet/{recordSetId}

Omitted fields keep their current value. A null value removes a field, except ttl and values, which cannot be null.

Record sets with the same name and type share one TTL. Updating the TTL updates all of them.

Linking a health check also requires the gslbHealthCheck:apiovh:get action on that health check.

Path parameters

recordSetId
required
stringuuid

Record set ID

zoneId
required
stringuuid

Zone ID

Request body (required)

chainTarget
string

New target record name for chained routing. When null or empty, the chain target is removed.

coordinates
Coordinates

New endpoint coordinates for GEOPROXIMITY routing. When null, the coordinates are removed.

evaluateTargetHealth
boolean

Whether to fall through to the global scope when a GEOLOCATION chain target is unhealthy. When null, the value is reset to false.

geoLocation
GeoLocation

New geographic scope for GEOLOCATION routing. When null, the scope is removed.

healthCheckId
stringuuid

Health check to link. Omit it to keep the current link, or set it to null to unlink the current health check.

setIdentifier
string

New identifier distinguishing entries with the same name and type. When null, the identifier is removed, which is only valid for SIMPLE routing.

ttl
integer

New time to live in seconds. Record sets with the same name and type share one TTL. Updating the TTL updates all of them. When omitted, the current TTL is kept. A null value is rejected. From 0 to 2147483647.

values
string[]

New record values. The list replaces the one currently set. When omitted, the current values are kept. A null value is rejected.

weight
integer

New relative weight for WEIGHTED routing. When null, the weight is removed. From 0 to 255.

Response

200RecordSetsuccessful operation
chainTarget
read-only
string

Target record name for chained routing. Null when the record set is not chained.

coordinates
read-only
Coordinates

Endpoint coordinates for GEOPROXIMITY

createdAt
read-only
stringdate-time

Creation timestamp

evaluateTargetHealth
read-only
boolean

Whether to fall through to the global scope when a GEOLOCATION chain target is unhealthy, always false for other record sets

failover
read-only
FailoverTypeEnum

Failover role of this entry, null for routing policies other than FAILOVER

ValuesPRIMARYSECONDARY
geoLocation
read-only
GeoLocation

Geographic routing scope, required for GEOLOCATION routing. Null when not set.

healthCheckId
read-only
stringuuid

Identifier of the associated health check. Null when no health check is linked.

id
read-only
stringuuid

Unique identifier of the record set

name
read-only
string

Fully qualified domain name with a trailing dot

resourceStatus
read-only
ResourceStatusEnum

Resource lifecycle status

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
routingPolicy
read-only
RoutingPolicyEnum

Traffic routing policy

ValuesFAILOVERGEOLOCATIONGEOPROXIMITYMULTIVALUESIMPLEWEIGHTED
setIdentifier
read-only
string

Identifier distinguishing entries with the same name and type, can be null only for SIMPLE routing

ttl
read-only
integer

Time to live in seconds. Record sets with the same name and type share one TTL. Updating the TTL updates all of them.

type
read-only
RecordTypeEnum

DNS record type

ValuesAAAAACNAMEMXTXT
updatedAt
read-only
stringdate-time

Last modification timestamp

values
read-only
string[]

DNS record values. Empty when chainTarget is set.

weight
read-only
integer

Weight from 0 to 255, required for WEIGHTED routing. Null when not set.

zoneId
read-only
stringuuid

Identifier of the parent hosted zone

400objectError 400 response
403objectError 403 response
404objectError 404 response

Example uses recordSetId = 00000000-0000-0000-0000-000000000000, zoneId = 00000000-0000-0000-0000-000000000000

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/zone/{zoneId}/recordSet/{recordSetId} \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "chainTarget": "string", "coordinates": { "latitude": 0, "longitude": 0 }, "createdAt": "2024-01-01T12:00:00Z", "evaluateTargetHealth": true, "failover": "PRIMARY", "geoLocation": { "continentCode": "AF", "countryCode": "AC", "subdivisionCode": "string" }, "healthCheckId": "00000000-0000-0000-0000-000000000000", "id": "00000000-0000-0000-0000-000000000000", "name": "string", "resourceStatus": "CREATING", "routingPolicy": "FAILOVER", "setIdentifier": "string", "ttl": 0, "type": "A", "updatedAt": "2024-01-01T12:00:00Z", "values": [ "string" ], "weight": 0, "zoneId": "00000000-0000-0000-0000-000000000000"}

Delete a GSLB record setAlpha

DELETE
/v2/dns/gslb/zone/{zoneId}/recordSet/{recordSetId}

Path parameters

recordSetId
required
stringuuid

Record set ID

zoneId
required
stringuuid

Zone ID

Response

200—successful operation

Example uses recordSetId = 00000000-0000-0000-0000-000000000000, zoneId = 00000000-0000-0000-0000-000000000000

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/zone/{zoneId}/recordSet/{recordSetId} \
  -H "authorization: Bearer $OVH_TOKEN"