---
title: "Publish Preferences Page"
method: POST
path: "/preferences/publish"
tags: ["Preference Topics"]
---

# Publish Preferences Page

`POST /preferences/publish`

Publishes the workspace preference page, snapshotting every preference and topic, and returns the page id and a preview URL.

## Headers

- `Idempotency-Key` string
- `x-idempotency-expiration` string

## Request body

- PublishPreferencesRequest — Optional page metadata to apply when publishing the workspace's preferences page. All fields are optional; omitted fields fall back to the page defaults (and the workspace default brand).
  - `heading` string, nullable — Heading shown at the top of the hosted preferences page.
  - `description` string, nullable — Description shown under the heading on the hosted preferences page.
  - `brand_id` string, nullable — Brand for the hosted page - "default" (workspace default brand), "none" (no brand), or a specific brand id. Defaults to "default".

## Response `200`

- PublishPreferencesResponse — Result of publishing the workspace's preferences page.
  - `page_id` string, required — Id of the published page snapshot.
  - `published_at` string, required — ISO-8601 timestamp of the publish.
  - `published_by` string, nullable — Id of the publisher.
  - `published_version` number, required — Monotonic published version (epoch milliseconds).
  - `preview_url` string, nullable — Draft-mode hosted preferences page URL for previewing.

---

[API](https://skmtc.net/trycourier/apis/courier.md) · [All operations](https://skmtc.net/trycourier/apis/courier/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/trycourier/courier/versions/04f69fbf96a5/schema)