Skip to content

Zones

All operations require authentication.

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

List GSLB hosted zonesAlpha

GET
/v2/dns/gslb/zone

Query parameters

iamTags
object

Filter resources on IAM tags

name
string

Filter by zone name prefix, ignoring case. The filter applies to each page of authorized zones. A page can hold fewer zones than requested. The total counts every authorized zone.

Headers

X-Pagination-Cursor
string

Pagination cursor

X-Pagination-Size
integer

Pagination size

Response

200HostedZoneWithIAM[]successful operation
comment
read-only
string

Optional zone description

createdAt
read-only
stringdate-time

Creation timestamp

iam
read-only
ResourceMetadata

IAM resource metadata

id
read-only
stringuuid

Unique identifier of the hosted zone

name
read-only
string

Fully qualified domain name with a trailing dot

nameServers
read-only
string[]

Assigned authoritative nameservers

recordCount
read-only
integer

Number of record sets in the zone

resourceStatus
read-only
ResourceStatusEnum

Resource lifecycle status

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
soa
read-only
SoaRecord

Start of Authority configuration for the hosted zone. Null when the name servers cannot currently report the SOA.

updatedAt
read-only
stringdate-time

Last modification timestamp

400objectError 400 response

Reads your token from $OVH_TOKEN

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/zone \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
[ { "comment": "string", "createdAt": "2024-01-01T12:00:00Z", "iam": { "displayName": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "EXPIRED", "tags": { "key": "string" }, "urn": "string" }, "id": "00000000-0000-0000-0000-000000000000", "name": "string", "nameServers": [ "string" ], "recordCount": 0, "resourceStatus": "CREATING", "soa": { "expire": 0, "hostmaster": "string", "minimum": 0, "name": "string", "primary": "string", "refresh": 0, "retry": 0, "serial": 0, "ttl": 0 }, "updatedAt": "2024-01-01T12:00:00Z" }]

Get a GSLB hosted zoneAlpha

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

Path parameters

zoneId
required
stringuuid

Zone ID

Response

200HostedZoneWithIAMsuccessful operation
comment
read-only
string

Optional zone description

createdAt
read-only
stringdate-time

Creation timestamp

iam
read-only
ResourceMetadata

IAM resource metadata

id
read-only
stringuuid

Unique identifier of the hosted zone

name
read-only
string

Fully qualified domain name with a trailing dot

nameServers
read-only
string[]

Assigned authoritative nameservers

recordCount
read-only
integer

Number of record sets in the zone

resourceStatus
read-only
ResourceStatusEnum

Resource lifecycle status

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
soa
read-only
SoaRecord

Start of Authority configuration for the hosted zone. Null when the name servers cannot currently report the SOA.

updatedAt
read-only
stringdate-time

Last modification timestamp

404objectError 404 response

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

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/zone/{zoneId} \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "comment": "string", "createdAt": "2024-01-01T12:00:00Z", "iam": { "displayName": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "EXPIRED", "tags": { "key": "string" }, "urn": "string" }, "id": "00000000-0000-0000-0000-000000000000", "name": "string", "nameServers": [ "string" ], "recordCount": 0, "resourceStatus": "CREATING", "soa": { "expire": 0, "hostmaster": "string", "minimum": 0, "name": "string", "primary": "string", "refresh": 0, "retry": 0, "serial": 0, "ttl": 0 }, "updatedAt": "2024-01-01T12:00:00Z"}

Create a GSLB hosted zone with SOA and NS recordsAlpha

POST
/v2/dns/gslb/zone

Request body (required)

comment
string

Optional description. At most 256 characters.

name
required
string

Fully qualified domain name with a trailing dot. Immutable after creation. At most 254 characters.

Response

200HostedZonesuccessful operation
comment
read-only
string

Optional zone description

createdAt
read-only
stringdate-time

Creation timestamp

id
read-only
stringuuid

Unique identifier of the hosted zone

name
read-only
string

Fully qualified domain name with a trailing dot

nameServers
read-only
string[]

Assigned authoritative nameservers

recordCount
read-only
integer

Number of record sets in the zone

resourceStatus
read-only
ResourceStatusEnum

Resource lifecycle status

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
soa
read-only
SoaRecord

Start of Authority configuration for the hosted zone. Null when the name servers cannot currently report the SOA.

updatedAt
read-only
stringdate-time

Last modification timestamp

400objectError 400 response
409objectError 409 response

Reads your token from $OVH_TOKEN

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/zone \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "comment": "string", "createdAt": "2024-01-01T12:00:00Z", "id": "00000000-0000-0000-0000-000000000000", "name": "string", "nameServers": [ "string" ], "recordCount": 0, "resourceStatus": "CREATING", "soa": { "expire": 0, "hostmaster": "string", "minimum": 0, "name": "string", "primary": "string", "refresh": 0, "retry": 0, "serial": 0, "ttl": 0 }, "updatedAt": "2024-01-01T12:00:00Z"}

Update a GSLB hosted zone, including its SOA configurationAlpha

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

Path parameters

zoneId
required
stringuuid

Zone ID

Request body (required)

comment
string

New description. When omitted, the current comment is kept. When null, the comment is removed. At most 256 characters.

nameServers
string[]

New authoritative name servers, each with a trailing dot. The list replaces the one currently set. When omitted, the current name servers are kept. When null, the default name servers are restored.

soa
UpdateSoaRequest

Partial update of the zone SOA configuration. When omitted, the current SOA is kept. A null value is rejected. The SOA cannot be removed.

Response

200HostedZonesuccessful operation
comment
read-only
string

Optional zone description

createdAt
read-only
stringdate-time

Creation timestamp

id
read-only
stringuuid

Unique identifier of the hosted zone

name
read-only
string

Fully qualified domain name with a trailing dot

nameServers
read-only
string[]

Assigned authoritative nameservers

recordCount
read-only
integer

Number of record sets in the zone

resourceStatus
read-only
ResourceStatusEnum

Resource lifecycle status

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
soa
read-only
SoaRecord

Start of Authority configuration for the hosted zone. Null when the name servers cannot currently report the SOA.

updatedAt
read-only
stringdate-time

Last modification timestamp

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} \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "comment": "string", "createdAt": "2024-01-01T12:00:00Z", "id": "00000000-0000-0000-0000-000000000000", "name": "string", "nameServers": [ "string" ], "recordCount": 0, "resourceStatus": "CREATING", "soa": { "expire": 0, "hostmaster": "string", "minimum": 0, "name": "string", "primary": "string", "refresh": 0, "retry": 0, "serial": 0, "ttl": 0 }, "updatedAt": "2024-01-01T12:00:00Z"}

Delete an empty GSLB hosted zoneAlpha

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

Path parameters

zoneId
required
stringuuid

Zone ID

Response

200—successful operation

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

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

Push the hosted zone and its record sets again to all GSLB name serversAlpha

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

Path parameters

zoneId
required
stringuuid

Zone ID

Response

200ZoneRefreshResultsuccessful operation
message
read-only
string

Explanation of a PARTIAL or ERROR status. It names the faulty record when the name servers reject the zone content. Null when status is OK.

recordSetCount
read-only
integer

Number of DNS resource record sets sent to the name servers, counting each name and type once and including SOA and NS

status
read-only
SyncStatusEnum

Aggregate push status: OK when every name server was updated, PARTIAL when the push failed on some but not all name servers, ERROR when it failed on every name server

ValuesERROROKPARTIAL
zone
read-only
string

Hosted zone name

404objectError 404 response

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

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/zone/{zoneId}/refresh \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "message": "string", "recordSetCount": 0, "status": "ERROR", "zone": "string"}