---
title: "Change a site's slug"
method: POST
path: "/api/v1/sites/{slug}/rename"
tags: ["Sites"]
---

# Change a site's slug

`POST /api/v1/sites/{slug}/rename`

## Request

- Base URL: `https://api.dotsy.ai`
- URL: `https://api.dotsy.ai/api/v1/sites/{slug}/rename`
- Auth: HTTP bearer

Gives the site a new slug, and with it a new address. Only the site's owner can do it, and a guest token cannot.

Most sites finish inside the request: **200** with the new `slug`. A large site (more than 1,000 stored files) is copied in the background instead: **202** with `status: "copying"` and a `job`. Poll `GET /api/v1/sites/{slug}/jobs/{id}` with `job.id` until `status` is `succeeded` or `failed`. Once the copy finishes the old slug stops answering directly, so poll with the new slug if the old one redirects or returns 404.

If the site was ever published, the old slug stays reserved and redirects here (301 for reads, 308 for writes), so follow redirects; `aliasRedirect` says which case you are in. A site that was never published releases the old slug, which then 404s. Absolute URLs inside stored HTML are not rewritten. The rename is declined while an import, a structure or adapt job, an asset warm-up or a site transfer is running.

## Path parameters

- `slug` string, required

## Request body

- RenameSiteRequest
  - `newSlug` string, required: The new slug: lowercase letters, numbers and hyphens (1–63), not reserved, and not shaped like a site id (UUID).

## Response `200`

Renamed. The site lives at `slug` now.

- RenameSiteResponse
  - `slug` string, required: The slug the site now has.
  - `previousSlug` string, required
  - `publicUrl` string, required
  - `liveUrl` string, required
  - `liveReady` boolean, required: True when the site had been published (the new address serves right away).
  - `aliasRedirect` boolean, required: True when the old slug keeps redirecting (the site had been published). False when the old slug was released.
  - `hint` string, required: The warnings joined into one sentence.
  - `warnings` string[], required: What to know after the rename. Plain sentences.

## Other responses

- `202`: Accepted: a large site is being copied in the background. Poll the `job`.
- `400`: The body is not `{ newSlug }` (`invalid_body`), the slug is not valid (`invalid_slug`) or is reserved (`reserved_slug`), or it is the site's current slug (`same_slug`).
- `401`: Missing or invalid credentials.
- `403`: Only the site's owner can rename it (`forbidden_role`); a read-only key or a guest token cannot (`forbidden_read_only`, `guest_requires_account`).
- `404`: No such site, or it is not visible to this account (`site_not_found`).
- `409`: Nothing changed. `slug_taken`, or the site is busy: `structure_active`, `adapt_active`, `import_active`, `warm_active`, `transfer_pending` or `rename_active`.
- `429`: Over the account's write budget (`rate_limited`). Retry after the `Retry-After` seconds.

---

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