Redirects API

Redirects map an old source (a page reference or a literal path) to a target, so moved or retired URLs keep resolving. Methods live at cms.api.<collection>.<method> (use your collection name, e.g. cms.api.pages.createRedirect) and mirror on the client as client.<collection>.<method> with identical types.

Redirects are not versioned content, so unlike the entry and block mutation APIs these methods do not return a commit envelope. All of them require the collection to have slugs enabled.

Methods

Create a Redirect

Point an old source (a page reference or a literal path) at a target, so a moved or retired URL keeps resolving. Source paths are canonicalized and must be unique among active redirects; target paths are stored verbatim, so you can point at an external destination. You get back the stored redirect enriched with its resolved current paths. Fails with SLUG_NOT_ENABLED, REDIRECT_INVALID (a source page root does not exist or a required field is missing), or REDIRECT_SOURCE_EXISTS.

const data = await cms.api.pages.createRedirect({
  body: {
    sourceType: 'path', // required
    sourcePath: '/old-pricing', // required when sourceType is 'path'
    targetType: 'page', // required
    targetRootId: 'root_123', // required when targetType is 'page'
    statusCode: 301,
  },
});

const { data, error } = await client.pages.createRedirect({
  body: {
    sourceType: 'path', // required
    sourcePath: '/old-pricing', // required when sourceType is 'path'
    targetType: 'page', // required
    targetRootId: 'root_123', // required when targetType is 'page'
    statusCode: 301,
  },
});

The returned redirect carries the stored row plus resolved sourceCurrentPath and targetCurrentPath (page references resolve to their current published path), matching the rows from listRedirects.

List Redirects

List the active redirects in a collection, newest first, with pagination and resolved current paths for page references. You get an empty list back when slugs are not enabled.

const data = await cms.api.pages.listRedirects({
  query: { limit: 25, offset: 0 },
});

const { data, error } = await client.pages.listRedirects({
  query: { limit: 25, offset: 0 },
});

Update a Redirect

Change a redirect's source, target, or status code. Source uniqueness is re-checked (excluding the redirect itself), so you can safely re-point it. Fails with SLUG_NOT_ENABLED, REDIRECT_NOT_FOUND, REDIRECT_INVALID, or REDIRECT_SOURCE_EXISTS.

const data = await cms.api.pages.updateRedirect({
  body: {
    redirectId: 'redirect_123', // required
    sourceType: 'path', // required
    sourcePath: '/old-pricing', // required when sourceType is 'path'
    targetType: 'page', // required
    targetRootId: 'root_456', // required when targetType is 'page'
    statusCode: 301,
  },
});

const { data, error } = await client.pages.updateRedirect({
  body: {
    redirectId: 'redirect_123', // required
    sourceType: 'path', // required
    sourcePath: '/old-pricing', // required when sourceType is 'path'
    targetType: 'page', // required
    targetRootId: 'root_456', // required when targetType is 'page'
    statusCode: 301,
  },
});

Resolve a Redirect

Resolve an incoming request path to its redirect decision, if one matches. This is the consumer's public routing call: it runs the full auth chain (so plugin scope is enforced) but is conventionally anonymous-readable. You get back { redirect: null } when no redirect matches or slugs are not enabled.

const data = await cms.api.pages.resolveRedirect({
  query: { path: '/old-pricing' }, // required
});

const { data, error } = await client.pages.resolveRedirect({
  query: { path: '/old-pricing' }, // required
});

The resolved redirect carries the target URL and status code, or is null when nothing matches.

Archive a Redirect

Soft-delete an active redirect by stamping its archivedAt timestamp, so it stops resolving without losing the record. Fails with REDIRECT_NOT_FOUND if the redirect does not exist, is already archived, or is out of scope.

const data = await cms.api.pages.archiveRedirect({
  body: {
    redirectId: 'redirect_123', // required
  },
});

const { data, error } = await client.pages.archiveRedirect({
  body: {
    redirectId: 'redirect_123', // required
  },
});