Domains API endpoints

View as Markdown Open in Claude Open in ChatGPT

These endpoints manage the domains of a Cloider account: free subdomains under cloider.app that Cloider hosts for you, and custom domains you own and point at Cloider's nameservers. A domain does nothing by itself: DNS records say what its names resolve to, and targets route its paths to an app, a cluster service or a bucket's static website over HTTPS.

All paths are relative to https://cloider.com/api. Domains are identified by their name, not by an id: GET /domains/example.com. See Domains overview.

At a glance

Method	Path	Access
GET	`/domains`	Read
POST	`/domains`	Write
GET	`/domains/availability`	Read
GET	`/domains/:domain_name`	Read
DELETE	`/domains/:domain_name`	Write

The domain object

{
  "domain_name": "example.com",
  "domain_type": "CustomDomain",
  "status": "Active",
  "created_at": "2026-09-20T13:05:41.880214Z"
}

Field	Type	Description
`domain_name`	string	The domain, in lower case. It is the domain's identifier in every endpoint
`domain_type`	string	`Subdomain` for a free subdomain such as `blog.cloider.app`, `CustomDomain` for your own domain
`status`	string	`Pending` (just added, nothing routed yet), `Active` (at least one target routes to it), `Suspended` (its last target was removed) or `Failed`
`created_at`	string	When the domain was added

List domains

GET /domains

Returns every domain of the account, sorted by name in reverse alphabetical order.

Access: any token.

curl https://cloider.com/api/domains \
  -H "Authorization: Bearer $CLOIDER_TOKEN"

Response
[
  {"domain_name": "example.com", "domain_type": "CustomDomain", "status": "Active", "created_at": "2026-09-20T13:05:41.880214Z"},
  {"domain_name": "blog.cloider.app", "domain_type": "Subdomain", "status": "Active", "created_at": "2026-10-01T09:20:33.102994Z"}
]

Check whether a free subdomain is available

GET /domains/availability?domain_name=:name

Checks whether a free subdomain can be claimed, with the same rules POST /domains and app creation apply. It claims nothing.

Access: any token.

Query parameter	Required	Description
`domain_name`	Yes	The full subdomain, for example `shop.cloider.app`

curl "https://cloider.com/api/domains/availability?domain_name=shop.cloider.app" \
  -H "Authorization: Bearer $CLOIDER_TOKEN"

Response
{"domain_name": "shop.cloider.app", "available": true, "reason": ""}

When available is false, reason says why, for example This subdomain is already taken. Please try another one., You already own this subdomain. Connect it to the app from Domains instead. or a naming rule such as Subdomain name cannot start with numbers.

Add a domain

POST /domains

Claims a free subdomain or adds a custom domain to the account.

Access: Read & Write token.

Field	Type	Required	Description
`domain_name`	string	Yes	The full domain. Lower cased before it is checked
`domain_type`	string	Yes	`Subdomain` or `CustomDomain`

Free subdomains are one label under cloider.app (GET /options lists the root as subdomain_roots): 2 to 63 characters of lower case letters, digits and -, starting with a letter and not starting or ending with -, and no dots of their own.

Custom domains are 3 to 253 characters of lower case letters, digits, dots and hyphens, with at least two labels. Domains under cloider are not allowed.

Custom domain
Free subdomain

curl -X POST https://cloider.com/api/domains \
  -H "Authorization: Bearer $CLOIDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain_name": "example.com", "domain_type": "CustomDomain"}'

curl -X POST https://cloider.com/api/domains \
  -H "Authorization: Bearer $CLOIDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain_name": "shop.cloider.app", "domain_type": "Subdomain"}'

Response
{"domain_name": "example.com", "domain_type": "CustomDomain", "status": "Pending", "created_at": "2026-10-20T10:12:09.441027Z"}

Adding a domain the account already has returns the existing domain with 200, so this request is safe to repeat. A new custom domain also gets an ALIAS record for the domain itself that points at cloider.app (and, once a target routes the domain to an app with a free subdomain, at that subdomain), unless it's under another of the account's custom domains; it's listed with the domain's DNS records. After adding a custom domain, set its nameservers at your registrar to the ones in GET /options nameservers (ns1.cloider.com to ns4.cloider.com); see Nameservers.

Status	Field	Message
`400`	`domain_name`	`Invalid domain format`, `Disallowed domain name`, `Domain name cannot have upper case letters`, `Domain name must not have consecutive dots`, `Domain name must contain only letters, numbers, dots, and hyphens`, `Domain name must not exceed 253 characters`, `Domain name is a public suffix shared by many owners, add your own domain under it, such as example.co.uk`
`400`	`domain_name`	`Invalid root domain name`, `Subdomain name cannot contain dots (multi-level subdomains not allowed)`, `Subdomain name cannot start with numbers`, `Subdomain name must be at least 2 characters`
`400`	`_`	`Invalid domain type specified`
`400`	`_`	`This subdomain is already taken. Please try another one.`
`400`	`_`	`The domain already created by a different user, if you own this domain contact support`
`400`	`_`	`This domain is under example.com, which belongs to another Cloider account. If you own example.com, contact support`
`400`	`_`	`A domain under this one belongs to another Cloider account. If you own example.com, contact support`
`400`	`_`	`Your account is suspended. Upgrade to a paid plan to continue using our services.`
`400`	`_`	`You have read-only access to this account, you can not create domains!` (a Restricted member)
`403`	`_`	`This API token is read only!`

Get a domain

GET /domains/:domain_name

Returns one domain with its targets, newest first. For an app or bucket target, namespace and service are empty.

Access: any token.

curl https://cloider.com/api/domains/example.com \
  -H "Authorization: Bearer $CLOIDER_TOKEN"

Response (trimmed)
{
  "domain_name": "example.com",
  "domain_type": "CustomDomain",
  "status": "Active",
  "created_at": "2026-09-20T13:05:41.880214Z",
  "targets": [
    {"hashed_id": "t4k9pz", "domain_name": "example.com", "target_type": "App", "app_id": "a7c2mq", "app_name": "web", "app_label": "web", "namespace": "", "service": "", "port": 8080, "path": "/", "target_path": "/"}
  ]
}

A domain that doesn't exist, or belongs to another account, answers 404 Not Found (plain text). The domain's records have their own endpoint, GET /domains/example.com/dns-records, and GET /targets?domain_name=example.com lists the targets on their own.

Delete a domain

DELETE /domains/:domain_name

Deletes a domain together with all of its DNS records and targets. Apps, cluster services and bucket websites that were routed through it keep running, but are no longer reachable on it. This can't be undone, and a free subdomain becomes available to anyone.

Access: Read & Write token.

curl -X DELETE https://cloider.com/api/domains/example.com \
  -H "Authorization: Bearer $CLOIDER_TOKEN"

The response is the account's remaining domain list.

Status	Message
`400`	`Operation failed, could not delete DNS records` and other `Operation failed, ...` messages when the deletion couldn't complete; nothing was deleted
`403`	`This API token is read only!`, `You have read-only access to this account, you can not delete domains!`
`404`	`Not Found` (plain text)

See Delete a domain.

DNS records and targets
Free subdomains and add a custom domain
cloider domain and the cloider_domain Terraform resource

At a glance​

The domain object​

List domains​

Check whether a free subdomain is available​

Add a domain​

Get a domain​

Delete a domain​

Related​

At a glance

The domain object

List domains

Check whether a free subdomain is available

Add a domain

Get a domain

Delete a domain

Related