Cache, trash and destroy

Three different things used to share the word "purge" in this API: deleting a trashed page for good, deleting a trashed space for good, and dropping cached copies of published pages. They now have three names. This page says what each one does, what it loses, and what publishing does on its own.

Trash

DELETE /orgs/{orgId}/spaces/{spaceId} and DELETE …/pages/{pageId} move the thing to the trash. Readers stop seeing it at once (its addresses are purged from every cache), and it can be restored with POST …/restore.

Retention. By default the trash keeps everything until somebody destroys it. An organization can set a window — PATCH /orgs/{orgId} with {"trashRetentionDays": 30} — after which an hourly sweep destroys what has been in the trash longer. A space can override it for its own pages with settings.trashRetentionDays (0 keeps them until destroyed, whatever the organization says). Every trash listing shows when each item goes:

forumulate spaces list --deleted true     # deletedAt, purgeAfter
GET /orgs/{orgId}/spaces/{spaceId}/pages/trash   # purgeAfter per page

purgeAfter is null when nothing will destroy it automatically.

Destroy (irreversible)

DELETE …/spaces/{spaceId}/destroy?confirm=<space-slug> and DELETE …/pages/{pageId}/destroy?confirm=<page-slug> delete for good.

• Only from the trash. A live space or page is a 409 destroy.not_trashed.

• Typed out. confirm must be the slug of the thing you are destroying; a missing or different value is a 422 validation.failed (reason: confirm_required, param: confirm) and nothing is deleted — a script holding the wrong id fails instead of destroying it.

• What is lost. A space: every page, post, topic and reply in it, their revision history and drafts, members' content and reactions in it, uploaded files, domains, and the slug reservation (the slug becomes free). A page: its content, every revision, draft and checkpoint, comments and feedback, and its search and AI index entries. Its translations and other versions are separate pages and stay. The answer says what went (destroyed.pages, topics, revisions).

• Audited. The audit log records the destruction before it happens, with who did it and — for a token — the token's id and name.

DELETE …/purge is the old name of the same operation. It still works; from Forumulate-Version: 2027-03-01 it requires confirm too.

Cache purge (nothing is deleted)

Published pages are cached in our web tier and at the edge — our CDN for forumulate.com, and any CDN your organization has configured for its own domains: Cloudflare (/orgs/{orgId}/integrations/cloudflare), or Fastly, Bunny, KeyCDN or a signed purge webhook to your own function (CloudFront, Akamai, Varnish…) at /orgs/{orgId}/integrations/cdn/{provider}.

Each answers what it did:

{
  "purged": "page",
  "urls": ["https://docs.acme.com/intro", "https://forumulate.com/p/acme/docs/intro"],
  "urlCount": 2,
  "edge": "fastly",          // or "cloudflare", "multiple" — or "none" when no CDN fronts these addresses
  "edges": [{ "name": "fastly", "account": "org", "urls": 1, "ok": true }],
  "webTier": true
}

edge: "none" is a real answer, not a failure: our web tier was refreshed and no CDN in front of the address was told, because none is configured. Consent_purgeSpace and Consent_purgeOrg are deprecated aliases of the space and org purges.

What publishing purges by itself

Every publish refreshes the page in our web tier and purges its addresses at every configured CDN. POST …/pages/{pageId}/publish (and POST …/docs/import) take purge:

• page (the default for publish) — the page's own addresses, reported as purged in the answer;

• space — everything under the space, for a change every page shows (a title in the navigation);

• none — leave the CDN alone (our web tier is still refreshed).

forumulate publish --purge page|space|none does the same for a folder and prints the summary; publish.completed carries it to a webhook.