Marketplace API

Browse marketplace listings, install them, and check what the account is entitled to.

6 endpoints

Endpoints

POST

/api/v1/marketplace/browse

Browse published Store listings (sites, templates, add-ons the user can install). Optional param "category" to filter: "page", "component", "email", "function", "table", "base", "flow", "theme", "app", "automation", "accountFunction", "agent". Returns listings with id, title, description, category, tier ("free"|"freemium"|"premium"|"upgrade" — there is no "paid"), price (cents), currentVersionId, installCount. Use this when the user asks for ready-made pages, components, functions, emails, bases, or flows.

Parameters

category string

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/marketplace/browse \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "example"
}'

POST

/api/v1/marketplace/getListing

Get full Store listing detail. Param "listingId" from browse. Returns { listing, currentVersion, manifest }. The manifest lists every artifact in the package (category, name, slug, description, requires). Use currentVersion.id as versionId for getInstallPlan/install.

Parameters

listingId stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/marketplace/getListing \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "listingId": "example"
}'

POST

/api/v1/marketplace/getInstallPlan

Preview what installing a listing would do — read-only, no writes. Params: listingId, versionId (from getListing currentVersion.id), targetProjectId (the current project). Returns items[] with category, name, slug, and collision (true if a page path, or a table name already in the site's base, is already used). ALWAYS call this before install and warn the user about collisions.

Parameters

`listingId`	stringrequired
`versionId`	stringrequired
`targetProjectId`	stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/marketplace/getInstallPlan \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "listingId": "example",
  "versionId": "example",
  "targetProjectId": "example"
}'

POST

/api/v1/marketplace/myEntitlements

List paid Store listings the current user has purchased. Returns entitlements with listingId. Paid listings require an entitlement before install — if missing, tell the user to buy it on the Store page first (never attempt payment yourself).

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/marketplace/myEntitlements \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'

POST

/api/v1/marketplace/install

Install a Store listing into a project. Params: listingId, versionId (from getListing currentVersion.id), targetProjectId (required — the project to install into), selections (optional array of artifact slugs to install a subset), mode (optional: "add-to-existing" default). Copies pages/components/functions/emails verbatim and remaps table/base/flow IDs to fresh ones. Tables are added to the site's existing linked base (or a new base if it has none); a table name already used there is refused with a plain message. After install, you can configure the installed artifacts (e.g. bind them to the user's existing tables and data).

Parameters

`listingId`	stringrequired
`versionId`	stringrequired
`targetProjectId`	stringrequired
`selections`	array
`mode`	string

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/marketplace/install \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "listingId": "example",
  "versionId": "example",
  "targetProjectId": "example"
}'

POST

/api/v1/marketplace/installedIn

List Store artifacts already installed in a project. Param "projectId". Returns records with category, artifactSlug, installedVersion, installedAt. Use to avoid duplicate installs.

Parameters

projectId stringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/marketplace/installedIn \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "example"
}'