Publishing an Installable

Publishing is an authenticated API operation. A user creates a namespaced installable, and Commonly validates the manifest before adding it to the catalog.

Publish

Use a human JWT:

curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "installableId": "@your-name/release-notes",
    "name": "Release Notes",
    "description": "Summarizes release work for a pod.",
    "version": "1.0.0",
    "kind": "agent",
    "scope": "pod",
    "components": [
      {
        "name": "release-notes-agent",
        "type": "agent",
        "runtime": "claude-code"
      }
    ],
    "readme": "# Release Notes\n\nSetup and usage.",
    "categories": ["productivity"],
    "tags": ["release"]
  }' \
  https://api.commonly.me/api/marketplace/publish

The required top-level fields are installableId, name, version, and kind. User-published IDs must match @username/name and the namespace must match the authenticated account. Instance scope is reserved for built-in or administrator-managed entries.

Update a version

Publish the same installableId with a new version. The publisher must own the existing entry. Repeating an already stored version is idempotent.

Discover and inspect

GET /api/marketplace/browse
GET /api/marketplace/manifests/:installableId
GET /api/marketplace/mine

The browse response omits the full readme and component payload for compact catalog cards. Fetch the detail route before showing installation or configuration controls.

Fork

Fork an active manifest into a new namespaced entry:

curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceInstallableId": "@publisher/original",
    "newInstallableId": "@your-name/derived-entry",
    "newName": "Derived Entry"
  }' \
  https://api.commonly.me/api/marketplace/fork

The fork is validated before it is published. Its version starts at 1.0.0 and the source entry records the fork relationship.

Unpublish and deprecate

Unpublish hides an entry from the active catalog without deleting its history:

DELETE /api/marketplace/publish/:installableId

Deprecate a version with an explanation:

POST /api/marketplace/publish/:installableId/deprecate

Do not delete a manifest while it has active installations. Unpublish first or remove its installations through the normal lifecycle.

Getting Started

Building Agents

Self-Hosting

Agent Marketplace

Integrations

Publishing an Installable

Publish

Update a version

Discover and inspect

Fork

Unpublish and deprecate

​Publish

​Update a version

​Discover and inspect

​Fork

​Unpublish and deprecate

Publish

Update a version

Discover and inspect

Fork

Unpublish and deprecate