Renaming an organization

An organization's slug is the first segment of its public addresses (/p/acme/…, acme.forumulate.com) and an accepted value for {orgId} on every API route. Renaming it does not break either.

Rename

PATCH /orgs/{orgId}/slug with {"slug": "new-name"}. The answer carries previous. The id never changes; anything that stores the id is unaffected.

What keeps working

While links.keep_renamed is on (the default):

• Reader addresses under the old slug answer 308 to the same page under the new one, so shared links, bookmarks and search results keep landing.

• API calls that name the old slug keep working on every /orgs/{orgId}/… route, for members of the organization. Each answer says the name is borrowed:

Deprecation: @1792886400
Sunset: Thu, 24 Oct 2027 12:00:00 GMT
Link: </orgs/new-name/spaces>; rel="successor-version"
X-Forumulate-Org-Renamed: old-name -> new-name

Sunset is a year after the rename: move scripts, CI jobs and manifests to the new slug before then. Renaming the organization back to its old name ends the alias; renaming with links.keep_renamed off keeps no old name at all.

Renaming a space

A space's slug is the segment after the organization in its reader address (/p/acme/docs/…) and an accepted value for {spaceId} on the management API.

forumulate spaces rename docs handbook --org acme
# or
PATCH /orgs/{orgId}/spaces/{spaceId}/slug   {"slug": "handbook"}

The answer is {"slug": "handbook", "previous": "docs"}; previous is null when links.keep_renamed is off, or when the space already had that slug (nothing is written then). The rule is the one a new space's slug follows: 2–48 lower-case letters, numbers and single dashes. A slug another live space holds is a 409 space.slug_taken; one held by a space in the trash says to restore or destroy that space first. The rename needs space.update, and sends the space.updated webhook with changed: ["slug"] and oldSlug.

What happens to the old address:

• Our reader addresses (/p/acme/docs/… and the other reader prefixes) answer 308 to the same page under the new slug, query string included, for as long as the old slug is in the space's history (below).

• A custom domain or path attached to the space (docs.acme.com, acme.com/docs) belongs to the space, not to its slug, and does not change.

• A site (several spaces on one domain, or acme.forumulate.com) addresses each space by its slug: acme.com/docs/… becomes acme.com/handbook/…, and the old segment is not redirected there yet — it answers 404. Rename a space that is part of a site before you publish the site, or plan for the old section links to break.

• The management API takes the new slug, or the uuid, which never changes. Unlike an organization's former slug, a space's former slug is not accepted on /orgs/{orgId}/spaces/{spaceId}/…: scripts that name a space by slug need the new one. Use the uuid in anything long-lived.

Slug history

A former slug is kept only while links.keep_renamed is on (the default) when you rename. Organization and space renames share one history table; there is no expiry date.

• GET /orgs/{orgId}/spaces/{spaceId}/slug/history (forumulate spaces slugs list <space>) answers {"slugs": [...]}: every former slug that still redirects to this space, oldest first.

• DELETE /orgs/{orgId}/spaces/{spaceId}/slug/history/{slug} (forumulate spaces slugs forget <space> <slug>) stops one redirecting and frees the name. It is scoped to the space in the path: it cannot release another space's former slug.

• A former slug is also released when something live takes the name: a space renamed to it, or a new space created with it. A live space always wins over a redirect, so one address never has two answers.

• An organization's former slug stays until the organization takes the name back; while it is kept, no other organization can rename to it. The Sunset header is the date a client should have moved by, not the date the alias stops working.

• Renaming with links.keep_renamed off keeps no history: the old name is free at once and its links break.

The API reference's landing page

A reference generated from an OpenAPI spec has a landing page whose address came from the spec's title, so a product renamed after its first import kept ref-old-name. Re-sync the spec with the new landing address:

forumulate openapi relabel <spec> --space reference \
  --landing-slug ref-acme-api --landing-title "Acme API" \
  --landing-description "Every Acme endpoint, with examples."
# or
POST /orgs/{orgId}/spaces/{spaceId}/docs/openapi/specs/{id}/resync
{"landingSlug": "ref-acme-api", "landingTitle": "Acme API"}

The same page moves (its id, history and comments come with it) and the old address answers 308 to the new one. The slug and title are recorded on the spec, so the next re-sync, including a deploy hook's empty-body one, keeps them. The description is not: a later re-sync without landingDescription writes the one derived from the spec again, so send it each time if you set one. A landingSlug another page already holds is a 409 naming the field, before anything is written. landingSlug, landingTitle and landingDescription are also accepted when you register or import a spec.

Display names

An organization's name (PATCH /orgs/{orgId} with {"name": …}, forumulate orgs update) and a space's name (PATCH /orgs/{orgId}/spaces/{spaceId} with {"name": …}, forumulate spaces update) are labels: they appear in the console, the reader's header and titles, and emails, but in no address. Changing one moves no page, keeps no history and needs no redirect. Change the slug when the address should follow the name.

Renamed presets

Preset ids follow the same rule. The referral product that shipped as referally is referalli; every place that takes a preset id — referral programs, integration-token audiences, partner-link labels — accepts the old spelling, stores the new one and answers with the new one. Billing reads metadata.referally_customer_ref as well as metadata.referalli_customer_ref.

Checklist

1. Rename with PATCH /orgs/{orgId}/slug.

2. Search your code and CI for /orgs/<old-slug> and the old reader prefix.

3. Watch for the Deprecation header in API responses — it names any call you missed.

4. Update referally to referalli where you wrote it.

5. Renaming a space too? Use forumulate spaces rename, update anything that names it by slug (scripts, forumulate.yaml), and check the site sections it appears in (see "Renaming a space").

6. Check the contract changelog (GET /changelog.json) for anything else that moved.

In the API

Every operation below is also reachable from the other surfaces without a dedicated command. forumulate api <Operation> calls it from the CLI, the JavaScript SDK has a typed method for each one (the last column names it; the Python and Go SDKs are generated from the same spec), and an agent reaches the organization-scoped ones through the MCP agent server — its api_* family tools, or call_api. Where a CLI command or a hand-made MCP tool exists too, the last column names it. Operation names link to the API reference.

Space slug