---
title: "Rename a content key (and optionally its URL)"
method: POST
path: "/api/v1/sites/{slug}/content/rename"
tags: ["Content"]
---

# Rename a content key (and optionally its URL)

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

## Request

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

Re-keys a page: the last path segment becomes `newSlug`, the directory and extension stay. Works on a draft page and on a published static page. `key` is sent in the body, so a nested key such as `blog/post.html` needs no percent-encoding. The change is staged — publish to make it live.

## Path parameters

- `slug` string, required

## Request body

- object
  - `key` string, required: The content key to rename. Send it raw: it may contain `/` (for example `blog/post.html`).
  - `newSlug` string, required: The new last path segment. It is slugified (lowercased, hyphenated) and replaces the file name; the directory and extension are kept.
  - `movePath` boolean: Published pages only: move the page's route to the new URL (menu links follow) instead of dropping the route and serving the page at its key-derived URL. A draft rename ignores it.
  - `leaveRedirect` boolean: With `movePath: true` on a published page, leave a 301 redirect at the old URL. Default true. A draft rename ignores it.

## Response `200`

Renamed (staged).

- ContentRenameResponse
  - `key` string, required: The content key after the rename.
  - `path` string: The route path the page now serves at, when it has one.
  - `oldKey` string: The key before the rename.
  - `oldPath` string: The route path before the rename.
  - `written` string[], required: Every content key the rename staged: the new key and the old key's removal — for a shared section (`fragments/<name>.html`) also each page, layout and section that places it. Publish exactly these to make it live.
  - `published` false, required: Always false: a rename is staged until you publish.
  - `hint` string, required: Reminder that the change is staged.

## Other responses

- `400`: The body is not valid (`invalid_body`), the key is blank (`invalid_key`), or `newSlug` has no letter or number (`invalid_slug`).
- `401`: Missing or invalid credentials.
- `403`: The key or token cannot edit this site (viewer role, guest token, or a key scoped to other sites).
- `404`: No such site (`site_not_found`), or no content at `key` (`content_not_found`).
- `409`: The target key or route path is already in use, or the routes could not be updated (`rename_failed`). Nothing changed.
- `422`: The page cannot be renamed yet: a capture route or `meta.url` permalink (`unsupported_route_shape`), or a running experiment (`experiment_active`).

---

[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)