Documentation/Building Your App/Marketplace: Publish, Import & Personalize
Marketplace: Publish, Import & Personalize
How Marketplace listings work — browsing, importing, publishing from a project or an uploaded bundle, and versioning — and which of it the dashboard offers no entry point for today.
What the Marketplace is
⚠️ What you can and cannot do in the dashboard today
The Marketplace has no entry point in the dashboard at the moment. Its sidebar entry is not shown, App Studio's Publish to Marketplace action is hidden, and the Personalize surface an import normally lands on is hidden with it — so there is no browse, import, upload or publish button to find. This is the storefront being held back until it is ready, not a role gate and not a review queue you are waiting in: no permission change and no reviewer will surface it. Two things are unaffected. The pages stay reachable by direct URL for anyone who already has one, and the API described on this page is live and unchanged, so a programmatic caller can still list, import, publish and upgrade. Read the rest of this page as the contract, not as a click-through you can follow in the console today.
The Marketplace is a gallery of production-ready Supero apps. Instead of starting every app from a blank schema, you can browse listings by category and capability, try one in a sandboxed preview before committing to anything, and import it straight into a new project in your own domain. If you've built something worth reusing, you can publish it back to the same gallery — either as a snapshot of a project you already built, or as a bundle you upload directly.
- •Browse & import — filter by category, app type, and auto-detected capabilities; every listing runs a client-side preview with sample data so you can try it before importing.
- •Publish from your project — turn an app you already built into a listing without a separate export/upload step.
- •Upload a bundle — bring in an app packaged as a .tar.gz from outside your dashboard.
- •Personalize — after import, rebrand the app (name, emoji, accent color, headline) and redeploy, without touching the AI generator.
ℹ️ Who can do what
Two further gates sit on top of the missing entry points above, and these are the ones an API caller still meets. The Marketplace, Publish, Upload, My Apps, and Personalize pages require the domain_admin role in your workspace — see the Roles & Permissions Reference. Importing a listing additionally requires access to the destination domain and project. And publishing — from a project or by upload — goes through platform review before a listing becomes visible to anyone outside your domain. Review is a real gate, but it is not what is stopping you today: with no console entry point, a submission is not the step you are missing.
Browse the gallery
The gallery loads the full set of published listings once and filters client-side, so switching category tabs, the app-type toggle, or capability facets is instant. Each card shows the publisher, category, price, install/view counts, and up to three capability badges; search matches title, tagline, tags, and publisher name.
Categories
| Category |
|---|
| Ecommerce |
| IoT |
| Sales |
| Finance |
| Productivity |
| Fleet |
| HR |
| Healthcare |
This is a controlled vocabulary for the category tabs; any additional category value present in the published set still gets its own tab, so nothing is hidden.
Capability badges
Capabilities are not a claim the publisher types in — they're detected automatically from the bundle's own files at publish time, so a badge on a listing reflects something actually present in the code.
| Capability | Detected from |
|---|---|
| Multi-tenant | a tenants list in config.py, or content namespaced under the app’s namespace |
| RBAC | a non-empty POLICIES list in setup.py |
| User accounts | a schema parented on user_account |
| Workflows | a non-empty WORKFLOW_DEFINITIONS list in setup.py |
| Saga | a workflow step with an on_error compensate handler in setup.py |
| Transactional | a schema that extends a base_* transactional service, or registered transactional views in the UI bundle |
Integrations a listing declares
| Integration | Category | After you import |
|---|---|---|
| Stripe | Payments | connect with your own API keys |
| Slack | Notifications | connect with your own API keys |
| SendGrid / SMTP | connect with your own API keys | |
| SMS | Twilio | connect with your own API keys |
| Push | Mobile push (FCM) | connect with your own API keys |
| Webhooks | Outbound | ready to use |
Try before you import
Opening a listing builds a preview client-side from the published bundle, seeded with sample data, and renders it in a sandboxed iframe — no deployment happens and none of your real data is involved. The sandbox never grants the previewed app access to your dashboard session; it runs as an opaque, cookie-less origin. Import the app once you're ready to run it for real.
bash
curl "https://api.supero.dev/api/v1/marketplace/public/listings?category=productivity&app_type=web&capability=rbac&sort=popular&page=1&page_size=50"
# a single listing's detail (also increments its view count)
curl https://api.supero.dev/api/v1/marketplace/public/listings/crm-starterPublish from your project
Publishing the project you already built takes one call rather than an export and a re-upload. You supply the listing details — title, slug, category, app type, tagline, description, tags, and pricing — and submitting snapshot-copies the project's current build into an immutable, platform-owned backing project behind the listing. It's a copy, not a live link: further edits to your original project only reach the marketplace when you push a new version. The dashboard action that would start this is currently hidden, so the API below is the way to do it today.
A new listing starts in draft. Submitting sends it to platform review — nothing goes live until a reviewer approves it, so you can safely fill in details and come back later without accidentally publishing.
bash
curl -X POST https://api.supero.dev/api/v1/marketplace/my/listings/from-project \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"slug": "crm-starter",
"title": "CRM Starter Kit",
"category": "productivity",
"app_type": "web",
"source_project_uuid": "<project-uuid>",
"tagline": "Lightweight CRM with contacts, deals, and pipeline views",
"pricing": { "model": "free" }
}'
# submit the draft for platform review
curl -X POST https://api.supero.dev/api/v1/marketplace/my/listings/<listing-uuid>/submit \
-H "Authorization: Bearer $TOKEN"💡 Publish new versions the same way
Once a listing is linked to a project, shipping a new version is a single call — no re-upload. On a published listing, a new version queues for re-review while the currently approved version keeps serving importers unchanged.
⚠️ Only apps you built are eligible
An app whose source is itself an externally uploaded bundle — including one you imported from the Marketplace — can't be turned into a new listing through this path. Publish an app you generated and built yourself; the direct .tar.gz upload flow below is the route for bundles built outside your dashboard.
Upload an external bundle
If your app was packaged outside App Studio — or you just have a .tar.gz on hand — an upload is a create-draft call followed by a version upload. The Upload wizard that wraps those two calls in three steps (Upload, Details, Review) has no entry point in the dashboard at the moment; where it is reachable, dropping the file runs the same analysis the gallery uses, client-side, so you see detected capabilities, integrations, and schema names before you submit anything.
| Bundle requirement | Detail |
|---|---|
| Format | .tar.gz or .tgz |
| Required files | schemas.py, config.py, and setup.py present somewhere in the archive |
| Compressed size | up to 25 MB |
| Uncompressed size / file count | up to 250 MB and 5,000 members |
| Icon / screenshots | PNG, JPG, GIF, or WebP, up to 5 MB each — one icon, up to 6 screenshots |
The two calls in full — create the draft, then attach the tarball as a version:
bash
curl -X POST https://api.supero.dev/api/v1/marketplace/my/listings \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"slug":"crm-starter","title":"CRM Starter Kit","category":"productivity","app_type":"web"}'
curl -X POST https://api.supero.dev/api/v1/marketplace/my/listings/<listing-uuid>/versions \
-H "Authorization: Bearer $TOKEN" \
-F "[email protected]" \
-F "description=Initial release"Listings created by direct upload always start free — pricing is only settable when publishing from a project.
What happens to the bytes you upload
Before a tarball is stored, the platform checks its structure: it rejects an unreadable or empty archive, absolute or path-traversal member paths, symlinks or other non-regular members, and archives over the size caps above — the same checks that protect everyone who later imports and runs this bundle's files. Any secret-shaped file in the archive (a real .env, private keys, credentials files) is stripped before storage. Treat that strip as a safety net, not a reason to include real secrets — ship an .env.example, never a real .env.
Each new tarball you upload to a listing becomes a new version; nothing is overwritten. On a published listing, a new version queues for review while the previously approved version keeps serving current importers exactly as-is until the new one is approved.
Import and personalize
Importing copies a listing's latest approved version into a project in your domain. The target must be an empty project — one with no schemas yet — since an imported app ships its own full schema set and UI. Over the API you name the target project yourself; the dashboard's Import dialog, where it is reachable, defaults to creating a fresh project for you.
bash
curl -X POST https://api.supero.dev/api/v1/marketplace/listings/crm-starter/import \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"target_domain":"acme","target_project_uuid":"<empty-project-uuid>"}'Import normally lands you on Personalize. Imported apps ship a hand-written UI bundle, so the usual App Studio AI wizard doesn't apply to them — Personalize is the dedicated, branding-only surface instead: app name, an emoji picker, an accent-color swatch, and a landing headline/subcopy. There's no AI generation involved; the right-hand pane renders the real imported app client-side with sample data, live-reflecting each change as you make it.
⚠️ Personalize has no entry point in App Studio right now
Personalize is hidden along with the rest of the Marketplace surfaces. Because an imported app cannot be regenerated either, an imported project currently shows no actions at all in App Studio — that is expected, not a broken project. The page itself still answers on its own URL for anyone who already has one.
| Personalize field | Applies to |
|---|---|
| App name | shown in the app chrome and title |
| Emoji | the app icon |
| Accent color | the primary theme color |
| Landing headline / subcopy | the landing page hero text |
These overrides are saved on the project and merged into the app's config at deploy time — the app bundle itself is not regenerated. An advanced Edit code panel is also available for direct changes to the bundle's editable files (such as the UI entry point); edits are overlaid onto the bundle at deploy, still without a full re-package. Save persists your overrides only; Save & Deploy pushes them live through the same one-click launch used for any Supero Cloud deployment.
Staying up to date
My Apps > Imported apps lists every app imported into the selected project and flags an update when the source listing has shipped a newer approved version. Updating pulls the latest version into the same project, preserving your app slug and personalization.
bash
curl -X POST https://api.supero.dev/api/v1/marketplace/imports/upgrade \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"target_domain":"acme","target_project_uuid":"<project-uuid>","source_listing_slug":"crm-starter"}'Review, status, and My Apps
Every listing carries a status that governs where it's visible and whether it can be imported:
| Status | Meaning |
|---|---|
| draft | created but not yet submitted — visible only to you |
| pending_review | submitted, awaiting platform review; any previously approved version keeps serving importers untouched |
| published | live in the public gallery and importable |
| rejected | declined by review, with a note explaining why — fix the listing and resubmit |
| unlisted | taken down by you (Unlist); the already-approved bytes are untouched, so Re-list restores it instantly with no re-review |
| deprecated | delisted by platform review — still viewable by direct link, no longer importable; existing installs are unaffected |
My Apps is where you manage this from your side, once it has an entry point again. Its Published tab lists every listing you own at any status, with actions scoped to that status: submit a draft for review, unlist or re-list a published one, edit its details and price, or add a new version. Its Imported tab lists apps imported into the currently selected project, each with an update-available indicator. The same information is available now from GET /api/v1/marketplace/my/listings and GET /api/v1/marketplace/imports.
A served version is pinned to the sha256 hash of the exact bundle a reviewer approved, shown next to the version number — so an importer can see precisely which bytes they're getting, and the served copy can never silently drift after approval.
Pricing and access
A listing published from a project can carry a pricing model — Free, One-time, or Subscription (monthly or yearly), in USD, EUR, GBP, or INR. Listings created by direct bundle upload are always free. Changing a listing's price only affects future imports going forward; apps already imported keep the terms they were imported under.
| Action | Who |
|---|---|
| Browse the gallery, preview a listing | domain_admin — though the dashboard currently offers no way in; the open catalog reads need no credential at all |
| Import a listing into a project | domain_admin with access to the destination domain and project |
| Publish from a project, upload a bundle, edit a listing’s details or price, add a version | domain_admin, and only for listings you own |
| Personalize and deploy an imported app | domain_admin with access to the project |
| Approve, reject, or delist a submission | platform review — not self-serve, and applies regardless of the listing’s price |
ℹ️ Reference: Marketplace endpoints
GET /api/v1/marketplace/public/listings and /public/listings/{slug} are open catalog reads. POST /api/v1/marketplace/listings/{slug}/import and /api/v1/marketplace/imports/upgrade bring a listing into a project. GET /api/v1/marketplace/my/listings plus the POST/PUT variants under /my/listings/... manage listings you own. All of these sit under the standard https://api.supero.dev base and take the same Bearer/X-API-Key auth as the rest of the platform.
Next steps
- •Build Your First App (App Studio) — build the project you'll eventually publish to the Marketplace.
- •Anatomy of a Supero App — the schemas.py/config.py/setup.py/app.js shape every uploaded bundle must follow.
- •Publish Your App (Go Live / Supero Cloud) — what Save & Deploy on the Personalize page actually launches.
- •Access Control (RBAC) — how the domain_admin role and project access are managed for your workspace.
- •Plugin Registry — the registry an imported bundle's plugins are resolved against.
On this page