Publish a bundle once, install it into any project

What a listing is

A listing is owned by one organization and identified by a globally unique slug. A listing has no content of its own; content lives in its versions, which are immutable once published.

A version bundles three kinds of thing, in any combination, and must contain at least one:

• Event contracts — the JSON Schema contracts the bundle's workflows trigger on.
• Custom actions — WebAssembly binaries, copied into the version at publish time.
• Workflows — trigger event, filters, steps and settings.

Visibility is private by default, meaning only the publishing organization can install it — which makes the same surface usable as an internal catalog. A public listing is installable by anyone. A private listing you do not own returns 404, not 403, so the catalog cannot be enumerated by probing identifiers.

Installing is project-scoped: a version installs into one project, the one your session or API key is scoped to. One live installation of a listing per project — installing again replaces the version on the same installation record rather than creating a second one.

Why installs arrive inert

Installing someone else's code is the moment where a platform either earns trust or loses it, so two rules are enforced in the database layer rather than left to the caller:

1. Installed custom actions arrive pending. The worker only executes approved actions, so third-party WebAssembly cannot run until an admin in your organization has reviewed it. Re-installing resets an action to pending.
2. Installed workflows arrive disabled. Nothing fires until a human turns it on.

Publishing draws from the publisher's own already-approved actions and copies the bytes into the version row. A publisher therefore cannot swap a binary after it has been reviewed, and the bytes you install are the bytes the publisher reviewed and ran.

The install response states both follow-up steps explicitly in next_steps, because they are the whole security model.

Publishing

Use Dashboard → Marketplace, or the REST API directly.

1. Create the listing

Requires developer access.

POST /organizations/:org_id/marketplace/listings

{
  "slug": "acme-deploy-guardrails",
  "name": "Acme deploy guardrails",
  "summary": "Scores each deployment and alerts on regressions.",
  "description": "Longer markdown-free description…",
  "visibility": "public"
}

Slugs are lowercase, at most 64 characters, and unique across the whole marketplace. A collision returns 409.

2. Publish a version

Requires admin access, because publishing distributes executable code under your organization's name.

POST /organizations/:org_id/marketplace/listings/:listing_id/versions

{
  "version": "1.0.0",
  "action_names": ["deploy-scorer"],
  "event_contracts": [
    {
      "event_type": "acme.deployment_completed",
      "version": 1,
      "description": "A service deployment finished",
      "required_fields": ["service", "status"],
      "json_schema": { "type": "object", "required": ["service", "status"] }
    }
  ],
  "workflows": [
    {
      "name": "Score deployments",
      "trigger_event": "acme.deployment_completed",
      "environment": "production",
      "steps": [{ "type": "custom_action", "action": "deploy-scorer" }]
    }
  ]
}

Three things are checked before the version is written:

• Each name in action_names must resolve to an approved action in your project. An unapproved action has not been reviewed by anyone, so publishing it would export unreviewed code — the request is refused with 400.
• Every custom_action step must name an action in the same bundle. A step pointing at an action the installer will not receive would install a workflow that can only fail closed.
• Workflows and event types are validated exactly as the workflow and contract routes validate them, since installing registers them verbatim in someone else's project.

Versions are immutable. Re-publishing the same version string returns 409 version_already_published; publish a new version instead. A version can later be yanked, which keeps existing installations working while preventing new ones.

Installing

Browse what your organization may install, then install a version into the active project. Browsing requires viewer access; installing requires developer access.

GET  /organizations/:org_id/marketplace/listings
GET  /organizations/:org_id/marketplace/listings/:listing_id
POST /organizations/:org_id/marketplace/listings/:listing_id/versions/:version_id/install
GET  /organizations/:org_id/marketplace/installations

The install response returns the installation summary plus the two things you still have to do:

{
  "installation": { "id": "…", "listing_id": "…", "version_id": "…", "status": "installed" },
  "next_steps": [
    "Review and approve the installed custom actions before they can execute.",
    "Enable the installed workflows once you are satisfied with their steps."
  ]
}

Approve the actions under Custom actions and enable the workflows under Workflows. Publishing, installing and uninstalling all write audit and security log entries.

Uninstalling

Requires admin access, because it deletes workflows and actions.

DELETE /organizations/:org_id/marketplace/installations/:installation_id

Uninstall removes only the rows that carry that installation's identifier, and it retains the event contracts, unlinking them instead. Deleting a contract would immediately start rejecting live events of that type, which is data loss dressed up as cleanup.

For the same reason the installation reference on installed artifacts is ON DELETE SET NULL rather than CASCADE: if an installation record disappears, its artifacts stay and simply become locally owned. Cascading would silently delete a workflow your team may have edited and come to depend on.

Limits

A bundle is capped at a size that is still reviewable by a person, since a person is what stands between an install and execution.

Not yet available

The Marketplace publishes and installs, but it is not a governed partner ecosystem yet. These do not exist today:

• Platform-side certification or moderation of public listings.
• Automated tenant-safety scanning of submitted WebAssembly.
• Permission-diff review when upgrading an installed version.
• Paid or metered listings.
• Any install path outside the dashboard and REST API — there is no public registry, and no SDK or CLI marketplace surface.

Treat a public listing the way you would treat any third-party dependency: read the action before you approve it.