Project names and addresses
A project's name is its display label. Its slug is the URL segment at
/<namespace>/projects/<slug>. Its stable ID identifies the same project across
name, slug, and ownership changes.
Open Edit Project to change its name. Under Project address, choose Follow project name or Custom slug. The dialog shows the current and proposed addresses before saving. Custom slugs persist when the name changes; selecting Follow project name immediately derives the address from the current name and enables future automatic changes.
New projects created without an explicit slug follow the name. Existing projects without recorded slug preferences retain their address. A historical name/slug mismatch cannot distinguish a stale address from an intentional custom URL; there is no automatic migration of those projects.
Name, slug, mode, and descendant paths change in one transaction. Editing
requires Project ADMIN. A collision or stale revision refuses the whole edit;
no numbered fallback is selected. ASCII and Unicode names use the same
established slug derivation as project creation. Names containing non-ASCII
characters receive a deterministic short hash so distinct names remain
addressable. Custom slugs use the project's existing single-segment rules and
100-code-point limit. New custom slugs cannot be 24 hexadecimal characters,
which the API reserves for project IDs; automatic slugs prefix such names with
project-.
Existing links
Previous browser addresses resolve to the current project, including their nested path, query, and fragment. The browser replaces the old history entry; Back does not loop through the old address. Unsaved editors remain protected by the existing navigation guard. Historical slugs remain reserved for the stable project identity and cannot be reused by another project.
An old address never grants access: location lookup checks current permissions. Deleting the project makes its historical links unavailable. Integrations should store the stable ID; an old slug is not an instruction to replay a write.
REST and clients
Read the project to obtain id, slugMode, and slugRevision. Address the
mutation by explicit namespace and project ID:
| Input | Result |
|---|---|
name alone | Changes the display name; auto mode derives its slug, custom mode preserves it |
slug | Sets that exact slug and custom mode |
slugMode: "auto" | Derives the slug now and on future renames |
slugMode: "custom" | Keeps the current slug on future renames |
slug with slugMode: "auto" | Invalid; choose one |
expectedProjectId binds the edit to the loaded project.
expectedSlugRevision rejects stale name/address edits with HTTP 409. A
successful response includes the canonical slug and new revision. Metadata
displayName edits follow the same policy; the generic Node API retains its
existing name-means-slug contract and treats it as an explicit custom slug.
Slug preferences use dedicated server fields; a metadata patch cannot override them.
GET /namespaces/:namespace/projects/:oldSlug/canonical-location returns the
current readable namespace, project ID and slug. Use it for link resolution;
mutations must use the verified current identity. CLI dl project rename,
TypeScript client.projects(namespace).update, Python client.projects.update,
and MCP project_get / project_update expose the same settings and guards.
After an uncertain write, inspect by ID before retrying.