Check Subdomain Availability

Overview

Checks whether a subdomain is valid, not reserved and not already taken by another status page. Use it before Create Status Page. GET /api/projects/{projectId}/status-pages/check-subdomain/{subdomain}

Authentication

Header	Required	Description
`X-API-Key`	Yes	Your API key (`Authorization: Bearer {jwt}` also works). Read-only keys are fine.
`X-Project-ID`	Yes	Must be the same project UUID as in the URL.

Required access: project viewer or higher.

Path parameters

Parameter	Type	Description
`projectId`	UUID	The project
`subdomain`	string	Subdomain to check. Matching is case-insensitive.

Response

200 OK

{
  "success": true,
  "data": {
    "available": false,
    "reason": "taken",
    "message": "This subdomain is already in use"
  }
}

Field	Type	Description
`available`	boolean	`true` if the subdomain can be used
`reason`	string	Present when unavailable: `taken`, `reserved` or `invalid_format`
`message`	string	Present when unavailable: a human-readable explanation

An available subdomain returns only { "available": true }. Valid subdomains are 3-63 characters of lowercase letters, numbers and single hyphens, with no leading or trailing hyphen.

Errors

Status	Code	Cause
400	`PROJECT_ID_REQUIRED` / `INVALID_PROJECT_ID`	`X-Project-ID` header missing or not a UUID
401	`AUTHENTICATION_REQUIRED`	Missing or invalid credentials
403	`ACCESS_DENIED`	No access to this project
404	`RESOURCE_NOT_FOUND`	The project does not exist

Example

cURL

curl https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/check-subdomain/acme-production \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID"

Introduction

Monitors

Groups

Incidents

Status Pages

Status Page Incidents

Check Subdomain Availability

Overview

Authentication

Path parameters

Response

200 OK

Errors

Example

​Overview

​Authentication

​Path parameters

​Response

​200 OK

​Errors

​Example

Overview

Authentication

Path parameters

Response

200 OK

Errors

Example