---
title: "Publish sale page"
method: POST
path: "/api/pages/publish"
tags: ["Publishing"]
---

# Publish sale page

`POST /api/pages/publish`

## Request

- Base URL: `https://clearlist.me`
- URL: `https://clearlist.me/api/pages/publish`
- Auth: one of:
  - API key in header `X-ClearList-API-Key`
  - OAuth 2 (authorization code, authorization URL `https://clearlist.me/oauth/authorize`, token URL `https://clearlist.me/api/oauth/token`, scopes: `write`)

Publishes the seller's sale page with location info and returns the shareable URL. Pass an Idempotency-Key. Re-publishing converges on the same page state, but a retry after a mid-flight failure short-circuits on the slug that already exists, so it will not repair a half-written page; replaying the stored first response is the reliable path. IMPORTANT: publishing requires `publish: true`. A page that has been unpublished stays offline unless you send it — the response still returns 200 and the URL either way.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `city` string
  - `state` string
  - `publish` boolean: Set true to bring the page ONLINE. Required to re-publish a page that was previously unpublished: without it this endpoint updates location and payment details only, returns 200 with the page URL, and leaves the page offline. Omit it (or send false) for a settings-style update that must not change published state.

## Response `200`

Published.

- object
  - `success` boolean
  - `data` object
    - `url` string, uri

## Other responses

- `400`: Invalid or missing parameters.
- `401`: Missing or invalid API key.
- `403`: `code: ADDRESS_IN_PUBLIC_LISTING` when an API key or OAuth token sends payment_instructions containing the seller's street address (stored, or sent as street_address in the same request). The instructions are shown on the public sale page. Nothing is written. Not retryable as sent: remove the address; to give it to a buyer, use the address share flow. A signed-in seller's own session is not checked.
- `409`: The requested custom URL is reserved or already taken. Not retryable: choose another URL. Also returned with `code: idempotency_conflict` while a request with the same Idempotency-Key is still being processed; that one is worth retrying with the same key after a few seconds. A 409 without that code is the operation's own refusal: read `error`.
- `422`: `code: idempotency_key_reuse`. While an earlier request with this Idempotency-Key is still running or succeeded within the last 24h, the key was sent to the same operation with a different body (compared byte for byte) or from a different kind of credential (signed-in session, API key, or OAuth token). Nothing was executed and the original record is untouched, so retrying with this key repeats the 422. Send the request with a new key.

---

[API](https://skmtc.dev/clearlist/apis/clearlist-api.md) · [All operations](https://skmtc.dev/clearlist/apis/clearlist-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clearlist/apis/clearlist-api/revisions/b1c1c4221cb8?raw)