ClearList Publishing API

openapi: 3.2.0
info:
  title: ClearList Publishing API
  version: 0.3.6
  description: 'API for ClearList, an AI resale manager. Agents authenticate via an API key acquired through the email verification flow, or as an OAuth 2.1 client (see /auth.md). Standard response envelope: `{ success: boolean, data?: object, error?: string }`. Errors return the Error schema with a machine-readable `code` and a resolution `hint`. Versioning: every response carries an X-API-Version header (currently 0.3); breaking changes ship as a new version and the old behavior is kept through a deprecation window announced via Deprecation and Sunset headers (RFC 8594) and the changelog at /developers. Retries: the operations that declare the Idempotency-Key header parameter accept it (1-255 chars; a UUID works well). The first successful (2xx) response is stored for 24h, and a retry with the same key replays it instead of duplicating the side effect, marked by an Idempotency-Replayed: true response header. An error returned by the operation itself is never stored and releases the key, so retrying that same request re-executes it. A key is scoped to the seller and the operation, and it identifies ONE request: while its record is live (the first request is still running, or it succeeded within the last 24h), the same key on the same operation with a different request body (compared byte for byte, so reformatted JSON counts as different) or from a different kind of credential (a signed-in session, an API key, and an OAuth token are three kinds) is refused with 422 `idempotency_key_reuse`. That refusal leaves the original record in place, so a corrected request needs a NEW key. A key outside the allowed characters is refused with 400 `invalid_idempotency_key`. Do not assume an operation is retry-safe because it looks like an update: check for the parameter on the operation itself.'
  contact:
    email: hello@clearlist.me
    url: https://clearlist.me
servers:
- url: https://clearlist.me
  description: Production
security:
- apiKey: []
- oauth2: []
tags:
- name: Publishing
  description: Publish the shareable sale page.
paths:
  /api/pages/publish:
    post:
      operationId: publishPage
      security:
      - apiKey: []
      - oauth2:
        - write
      x-tool-id: publish_page
      tags:
      - Publishing
      summary: Publish sale page
      description: '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.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                city:
                  type: string
                state:
                  type: string
                publish:
                  type: boolean
                  description: '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.'
      responses:
        '200':
          description: Published.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      url:
                        type: string
                        format: uri
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: '`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':
          description: '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`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/IdempotencyKeyReuse'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
  /api/pages/renewal-options:
    get:
      operationId: getPageRenewalOptions
      tags:
      - Publishing
      summary: Get sale-page renewal choices
      description: Returns the authenticated seller's current page expiry and the renewal choices that can be fulfilled in full. Checkout URLs are omitted when the page is unpublished or no option is currently eligible.
      responses:
        '200':
          description: Current renewal state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      can_renew:
                        type: boolean
                      is_free:
                        type: boolean
                      page_expires_at:
                        type: string
                        format: date-time
                        nullable: true
                      days_until_page_expiry:
                        type: integer
                        nullable: true
                      is_expired:
                        type: boolean
                      options:
                        type: array
                        items:
                          type: object
                          properties:
                            intent:
                              type: string
                              enum:
                              - free_renew
                              - time_only
                              - renew_pass
                              - upgrade
                            label:
                              type: string
                            detail:
                              type: string
                            priceUsd:
                              type: number
                            durationDays:
                              type: integer
                            addsCapacity:
                              type: boolean
                            sku:
                              type: string
                              enum:
                              - sale_pass
                              - big_move
                              - move_extension
                              - garage_extension
                            checkout_url:
                              type: string
                              format: uri
                              nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/pages/extend:
    post:
      operationId: extendSalePage
      security:
      - apiKey: []
      - oauth2:
        - write
      x-tool-id: extend_sale_page
      tags:
      - Publishing
      summary: Renew or begin renewing a sale page
      description: Renews an eligible free page immediately. Paid or lapsed-paid accounts receive purchasable choices instead; this endpoint never grants paid time for free. Pass an Idempotency-Key when retrying.
      responses:
        '200':
          description: Page extended, or payment choices returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      extended:
                        type: boolean
                      requires_payment:
                        type: boolean
                      page_expires_at:
                        type: string
                        format: date-time
                        nullable: true
                      days_until_page_expiry:
                        type: integer
                        nullable: true
                      url:
                        type: string
                        format: uri
                      options:
                        type: array
                        items:
                          type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: 'Page is unpublished, renewal is too early, or account state changed. 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':
          $ref: '#/components/responses/IdempotencyKeyReuse'
        '429':
          $ref: '#/components/responses/RateLimited'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
components:
  headers:
    WWWAuthenticate:
      schema:
        type: string
      description: 'RFC 9728 challenge: `Bearer resource_metadata="https://clearlist.me/.well-known/oauth-protected-resource", error="invalid_token"`.'
    RateLimitRemaining:
      schema:
        type: integer
      description: Requests remaining in the current window.
    RateLimitLimit:
      schema:
        type: integer
      description: Request quota for the current window.
    RateLimitReset:
      schema:
        type: integer
      description: Unix epoch seconds when the window resets.
  responses:
    RateLimited:
      description: Too many requests.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    IdempotencyKeyReuse:
      description: '`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.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      headers:
        WWW-Authenticate:
          $ref: '#/components/headers/WWWAuthenticate'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid or missing parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: 'Unique client-generated key (1-255 chars from A-Za-z0-9_-:.; a UUID works well), scoped to the seller and the operation. The first successful (2xx) response is stored for 24h; retrying the identical request with the same key replays it instead of re-executing, so network-failure retries never create duplicates. A duplicate that arrives while the first is still running gets 409 idempotency_conflict. The same key with a different body (byte for byte) or a different kind of credential gets 422 idempotency_key_reuse and leaves the original record in place: send a new key. An error the operation itself returns is never stored and releases the key.'
      schema:
        type: string
        minLength: 1
        maxLength: 255
        pattern: ^[A-Za-z0-9_:.-]+$
  schemas:
    Error:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: Machine-readable error code, e.g. route_not_found, invalid_token, rate_limited.
        message:
          type: string
          description: Detailed message.
        hint:
          type: string
          description: Resolution guidance for agents.
        retryable:
          type: boolean
          description: Present on refusals that are worth retrying unchanged. Currently only a wrong-conversation address confirmation, where the token is untouched and only the id was wrong. Absent means terminal.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-ClearList-API-Key
      description: 'API key in `cl_<64-hex>` format. Obtained via POST /api/auth/verify-code with `{ email, code, agent: true }`. Always full access (read and write). The same credential is also accepted as `Authorization: Bearer cl_<64-hex>`.'
    oauth2:
      type: oauth2
      description: 'OAuth 2.1 authorization code flow. PKCE with code_challenge_method=S256 is required; public clients only (token_endpoint_auth_method none). Access tokens are `cl_<64-hex>` and are sent as `Authorization: Bearer <token>` (X-ClearList-API-Key also works). Operations that change state require the `write` scope; a grant without it gets 403. Reading needs no specific scope, so a `write`-only grant can also read.'
      flows:
        authorizationCode:
          authorizationUrl: https://clearlist.me/oauth/authorize
          tokenUrl: https://clearlist.me/api/oauth/token
          refreshUrl: https://clearlist.me/api/oauth/token
          scopes:
            read: Read listings, reservations, conversations, page stats and plan status.
            write: Create, edit, delete and publish listings; reply to buyers; share an address through the confirmed flow; set availability; create payment links.
    bearerToken:
      type: http
      scheme: bearer
      description: 'Firebase ID token for web UI authentication. A `Bearer cl_…` value is not a Firebase token: it is an API key or OAuth access token, covered by the apiKey and oauth2 schemes.'