---
title: "Rename the platform subdomain"
method: POST
path: "/websites/{websiteId}/domains/platform/rename"
tags: ["Domains"]
---

# Rename the platform subdomain

`POST /websites/{websiteId}/domains/platform/rename`

## Request

- Base URL: `https://api.cactal.ai/v1`
- URL: `https://api.cactal.ai/v1/websites/{websiteId}/domains/platform/rename`
- Auth: HTTP bearer

Moves the website to `<label>.<platform domain>`, the free address every website is allocated at creation. `label` is just the leading part: 1-40 characters, lowercase letters, digits, and inner hyphens, and it may not be one of the labels Cactal reserves. The change takes effect immediately, on published and draft hosts alike. The previous hostname is released at the same moment, with no redirect and no grace period, so any existing links to it break and another website may claim it. Take care on a published site. Fails with 409 when the label is already taken by another website; renaming to the label the website already has is a no-op. Custom domains are unaffected, and if one of them is primary it stays the canonical address.

## Path parameters

- `websiteId` string, required

## Request body

- object
  - `label` string, required

## Response `200`

The platform subdomain at its new hostname, plus `previousHostname`: the address that was just released.

- object
  - `id` string, required: Unique domain id.
  - `hostname` string, required: Fully-qualified lowercase hostname, e.g. `blog.example.com`.
  - `status` 'pending_dns' | 'pending_verification' | 'active' | 'failed' | 'removing' | 'suspended', required: `pending_dns`: waiting for the required DNS records; `pending_verification`: DNS found, waiting for the edge host to become ready; `active`: serving traffic; `failed`: verification failed (see `failureMessage`); `removing`: being deregistered from the edge; `suspended`: disabled by Cactal trust & safety. Platform subdomains are always `active`.
  - `kind` 'platform_subdomain' | 'custom', required: Every website automatically gets one `platform_subdomain`; `custom` domains are added through this API.
  - `isPrimary` boolean, required: Whether this is the canonical custom domain that published traffic redirects to. Always `false` for platform subdomains.
  - `dnsRecords` object[], required: DNS records the domain owner must create for verification to succeed. Empty for platform subdomains.
    - `type` 'TXT' | 'CNAME' | 'A', required: DNS record type to create.
    - `name` string, required: Fully-qualified name (host) to create the record on.
    - `value` string, required: Exact value the record must resolve to.
    - `purpose` 'ownership' | 'routing', required: `ownership` records prove control of the hostname (TXT); `routing` records point traffic at the Cactal edge (CNAME for subdomains, A for apex domains).
  - `failureMessage` string, nullable, required: What the most recent verification check found wrong, including whether ownership is missing, the hostname is unreachable, or traffic reaches a service other than Cactal. `null` when nothing is wrong.
  - `lastCheckedAt` string, date-time, nullable, required: When DNS and edge status were last checked. `null` before the first check.
  - `createdAt` string, date-time, required: When the domain record was created.
  - `previousHostname` string, required: The hostname the website was reachable at before the rename. It is released immediately, so links to it stop working and another website may claim it.

## Other responses

- `400`: Validation failed. The response `message` names the first invalid field.
- `401`: Missing, invalid, expired, or revoked API key.
- `403`: The authenticated principal lacks the required capability.
- `404`: The resource does not exist or is outside the principal’s access scope.
- `409`: The request conflicts with the current state of the resource.
- `429`: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.

---

[API](https://skmtc.dev/cactal/apis/cactal-api.md) · [All operations](https://skmtc.dev/cactal/apis/cactal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cactal/apis/cactal-api/revisions/9cd0fb5eacdd?raw)