Marketplace API — bRRAIn Docs

Programmatic API for the Marketplace — list, install, manage extensions.

Marketplace API

The Marketplace API lets you browse the catalog and manage installs programmatically. Useful for IT automation, multi-organization deployment scripts, and integration with your provisioning pipelines.

Base path

https://marketplace.brrain.io/api
https://<your-org-slug>.brrain.io/api/console/marketplace   (per-org install management)

Public browsing

These endpoints don't require authentication.

List extensions

GET /listings?category=&pricing=&sort=popular&limit=50&cursor=

Returns the catalog. Sortable by popular, newest, updated, price, name.

Get a listing

GET /listings/{slug}

Full listing detail — name, tagline, description, screenshots, scopes, pricing, publisher, version history.

Get categories

GET /categories

The category tree.

GET /search?q=...

Full-text search across listings.

Per-organization install management

Authenticated. Requires Architect or Sovereign role.

List installed extensions

GET /api/console/marketplace/installs

Returns extensions installed in the organization.

Install

POST /api/console/marketplace/installs
Content-Type: application/json

{
  "slug": "brrain-agent-orchestrator",
  "version": "1.2.0",
  "approve_scopes": ["vault.engineering.read", "vault.agent-orchestrator-runs.write", ...]
}

Initiates the install lifecycle. Returns immediately with a job ID; poll GET /installs/{slug} for status.

For paid extensions, this creates a subscription. The dialog version of this in the Console shows the price; the API caller is expected to have surfaced the price to the human approver before calling.

Update version

POST /api/console/marketplace/installs/{slug}/update
Content-Type: application/json

{
  "version": "1.3.0"
}

Triggers the update lifecycle. Approvals required if the new version requires new scopes.

Uninstall

DELETE /api/console/marketplace/installs/{slug}?wipe_data=false

Stops the extension and removes it. wipe_data=true requires Sovereign role and additional confirmation.

Pin a version

POST /api/console/marketplace/installs/{slug}/pin
Content-Type: application/json

{
  "version": "1.2.0"
}

Skips update notifications until you unpin.

Get install status

GET /api/console/marketplace/installs/{slug}

Returns:

  • Current version.
  • Health (healthy / degraded / failed).
  • Last health-check timestamp and result.
  • Subscription status if paid.

Subscriptions

List

GET /api/console/marketplace/subscriptions

Active subscriptions on the organization.

Cancel

DELETE /api/console/marketplace/subscriptions/{id}?at=end_of_period

at=immediately cancels with proration; at=end_of_period (default) lets the subscription run out.

Pause / resume

POST /api/console/marketplace/subscriptions/{id}/pause
POST /api/console/marketplace/subscriptions/{id}/resume

For extensions whose publisher allows pausing.

Publishing (publisher-only)

Authenticated as a publisher.

Submit a new extension

POST /api/publish/listings
Content-Type: multipart/form-data

(name, tagline, description, banner, screenshots, manifest, tarball, ...)

Begins the review workflow.

Submit a new version

POST /api/publish/listings/{slug}/versions

Same shape minus the listing fields you don't want to change.

Get review status

GET /api/publish/listings/{slug}/versions/{version}/review

States: pending, under_review, changes_requested, approved, rejected.

Webhooks

Subscribe to install lifecycle events via the standard Webhooks API:

  • extension.installed
  • extension.updated
  • extension.uninstalled
  • extension.health_changed
  • subscription.created
  • subscription.canceled

Errors

  • extension_not_found
  • version_not_found
  • scope_not_approved
  • subscription_required — the call requires a paid subscription that isn't active.
  • incompatible_pod_version — the extension's manifest min-version exceeds your pod version.

Where to next