> For the complete documentation index, see [llms.txt](https://docs.taptap3d.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.taptap3d.com/proposed-reference/listing-contract.md).

# Listing contract

Proposed public listing endpoints, response fields, revision rules and errors for Taptap3D integrations.

Status: proposed contract, not implemented in the product. These paths are the intended shape for client planning. `api.example.com` and `embed.example.com` are placeholders, not production services. Hostnames, limits and compatibility guarantees require confirmation before release.

## Routes

| Request                                                                | Intended result                                  |
| ---------------------------------------------------------------------- | ------------------------------------------------ |
| `GET {API_ORIGIN}/v1/publications/{publicationId}`                     | Latest approved public listing as JSON.          |
| `GET {API_ORIGIN}/v1/publications/{publicationId}?revision={revision}` | A particular approved revision.                  |
| `GET {EMBED_ORIGIN}/embed/{publicationId}?locale=en&theme=light`       | Hosted HTML presentation.                        |
| `GET {EMBED_ORIGIN}/p/{publicationId}`                                 | Canonical listing page and fallback link target. |

`publicationId` is an opaque public identifier issued after publication approval, not a private lot ID or tenant ID. Encode path segments with `encodeURIComponent`. Clients must not construct IDs from catalogue position or page number.

## Parameters

| Parameter  | Values                      | Default                        | Applies to |
| ---------- | --------------------------- | ------------------------------ | ---------- |
| `revision` | Opaque approved revision ID | Latest approved revision       | All routes |
| `locale`   | `en`, `zh-Hant`             | Publication's default language | All routes |
| `theme`    | `light`, `dark`             | `light`                        | Embed only |

Unsupported parameters or values return `400`. If a requested translation is unavailable, return the default language and its actual tag. Theme and locale must never alter field visibility.

## Successful response

```json
{
  "schemaVersion": "1",
  "publicationId": "pub_demo_vessel",
  "revision": "rev_demo_001",
  "updatedAt": "2026-10-08T08:00:00Z",
  "canonicalUrl": "https://embed.example.com/p/pub_demo_vessel",
  "title": "Ceramic vessel",
  "description": "A short description approved for publication.",
  "language": "en",
  "images": [
    {
      "url": "https://images.example.com/vessel.jpg",
      "alt": "Front view of the ceramic vessel",
      "width": 1600,
      "height": 1200
    }
  ]
}
```

All fields shown are required. `images` can be empty; otherwise its order is the approved display order, dimensions are positive integers and URLs use HTTPS. `description` is plain text: render it as text, not trusted HTML. `updatedAt` describes the approved revision, not the last private edit. Integrators must explicitly trust the origin of `canonicalUrl`.

The initial contract omits price and availability. Auction estimates are not purchase offers. Those fields need distinct types and currency rules before addition; clients must not infer them from text. Private organisation, consignor, valuation and workflow fields are excluded. Publication approval must review field visibility and image rights.

## Access and tenancy

The proposed public read routes require no bearer token. They return only approved public publications. An identifier is not a credential; these routes are unsuitable for private previews.

The service resolves publication ownership from the public identifier. A host cannot choose a tenant by header, query parameter or browser-supplied organisation ID. Private creation and approval APIs are outside this contract. Never place an administrative token in iframe markup, client JavaScript or a URL.

For browser JSON rendering, the intended service permits registered storefront origins through CORS. Direct iframe rendering does not require CORS. CORS is a browser policy, not authorisation. Approved parent origins must also be enforced by the embed's framing policy.

## Revisions and withdrawal

Omitting `revision` follows the latest approved revision. Supplying it pins that approved snapshot. Private edits never change either response until approved. A withdrawn publication returns `410` for every revision; retained historical data must not bypass withdrawal.

The proposed first release uses `Cache-Control: no-store` on JSON and embed responses. Public image expiry, CDN invalidation and withdrawal propagation still need validation before launch. Do not persist a listing indefinitely in a storefront cache.

## Error response

```json
{
  "error": {
    "code": "publication_withdrawn",
    "message": "This publication is no longer available."
  }
}
```

| HTTP status | Code                    | Client action                                                            |
| ----------- | ----------------------- | ------------------------------------------------------------------------ |
| `400`       | `invalid_request`       | Correct ID encoding or unsupported parameters; do not retry unchanged.   |
| `404`       | `publication_not_found` | Show unavailable; private/unapproved records also produce this response. |
| `404`       | `revision_not_found`    | Remove or correct the pinned revision after review.                      |
| `410`       | `publication_withdrawn` | Remove displayed content and purchase affordances.                       |
| `429`       | `rate_limited`          | Honour `Retry-After` seconds; do not retry in a tight loop.              |
| `503`       | `service_unavailable`   | Keep a fallback link and retry with bounded backoff.                     |

Messages are not stable identifiers. Branch on status and `error.code`. Exact quotas and service-level commitments are not yet defined.

## Compatibility

`/v1` identifies the proposed major contract. Ignore unknown JSON fields and message types. Existing field meanings and types must not change within a major version. A release still needs a deprecation policy; these docs do not promise a support duration.

See the [connection playbook](/get-started/connection-playbook.md) and [release acceptance checks](/testing-and-support/acceptance.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.taptap3d.com/proposed-reference/listing-contract.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.