API
Smart Products
Create, read and publish smart products, and read their contributions, editions and payments.
A smart product is the central entity. It is created as a DRAFT, deployed as a Clarity
contract by your client, and becomes PUBLISHED when that deploy confirms.
Create the draft first. The server materializes contribution rows from your picker payload,
and those frozen rows are what
contract generation writes into the contract. Passing a
creators[] array of your own bypasses that and produces a contract whose payouts do not match
any record the protocol holds.
Status is not something you set. It follows the chain - see How State Syncs.
Products
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET | /api/smart-products | app key | List products across every domain (PAGE, EVENT, PREDICTION, GAME). Filter by domain, productTypeId, productTypeSlug, status (DRAFT, PUBLISHED, LOCKED, SETTLED, FAILED, ARCHIVED), ownerAddress, sourceAppId, collectionId and search; sort by createdAt, updatedAt, publishedAt, title or currentInstances; ?include= takes productType, styleSet and tags. |
POST | /api/smart-products | app key + user, entitlement, app access | Create a PAGE draft. Needs CREATE_PAGES; author must be the caller. The server materializes contribution rows from your picker payload, and accepts a named recipe in place of explicit capabilities. Another domain is a 400 pointing at its own route: /api/events, /api/brackets or /api/games. |
DELETE | /api/smart-products/{id} | app key + user | Delete a PAGE draft, or one that never reached the chain. Author only, or MANAGE_LISTINGS. A deployed product is refused with 400. |
GET | /api/smart-products/{id} | app key | One product. ?include= takes productType, styleSet, tags, contributions, instances, stickers, appListings, pageDetails and bracketDetails; anything else is a 400. |
PATCH | /api/smart-products/{id} | app key + user | Partial update of a draft. |
PUT | /api/smart-products/{id} | app key + user | Same handler as PATCH. |
POST | /api/smart-products/{id}/publish | app key + user | Manual publish trigger, for when the deploy event was missed. Publication normally follows the confirmed deploy on its own. The product's owner, or MANAGE_TOURNAMENTS. |
Composition and revenue
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET | /api/smart-products/{id}/contributions | app key | The revenue split: every contributor, role, percentage and frozen position. |
GET | /api/smart-products/{id}/payments | app key | Payment legs recorded against this product. |
POST | /api/smart-products/{id}/stickers | app key + user | Attach a sticker placement to a draft: { stickerId, x, y, scale?, rotation? }, in the template's canvas coordinates. The product's owner, or MANAGE_LISTINGS. |
DELETE | /api/smart-products/{id}/stickers/{stickerRowId} | app key + user | Remove a placement. Draft only; the product's owner, or MANAGE_LISTINGS. |
PATCH | /api/smart-products/{id}/stickers/{stickerRowId} | app key + user | Update a placement (x, y, scale, rotation). Draft only; the product's owner, or MANAGE_LISTINGS. |
Editions of a product
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET | /api/smart-products/{id}/instances | app key | Every minted edition of this product. |
GET | /api/smart-products/{id}/instances/{instanceId} | app key | One edition under this product. |
GET | /api/smart-products/{id}/instances/{instanceId}/note | app key + user | The private note a collector left with their mint. Readable by the parties to it, never public. |
GET | /api/smart-products/{id}/editions | app key | Pending-aware edition read: confirmed editions plus mints still in flight. |
Discovery and counters
| Method | Path | Auth | Purpose |
|---|---|---|---|
DELETE | /api/smart-products/{id}/apps | app key + user | Remove a listing. |
GET | /api/smart-products/{id}/apps | app key | Apps this product is listed in. |
POST | /api/smart-products/{id}/apps | app key + user | List this product in an app. |
GET | /api/smart-products/{id}/collections | app key | Collections this product appears in. |
GET | /api/smart-products/{id}/stats | user, entitlement | Aggregate counters for one product. Operator read: needs VIEW_ADMIN_PANEL. |
GET | /api/smart-products/{id}/sentiment-snapshot | app key | Current tallies for a product composing the sentiment capability. |