Marketplace

• Sells as: the marketplace product (a product-scoped API key). This capability has no separate product-face contract — its public product route reuses the capability contract below; see the Edge route table's Product face row.

Shared product-tier addon-marketplace / venture-storefront engine (Track L convergence). Catalog CRUD + install/uninstall + reviews/ratings + payment-verification + submit/approve/reject workflow, so no product re-rolls the marketplace plumbing. I5 capability-face only (Stripe checkout for a paid addon stays product-side; core records/verifies the resulting payment). I4 own Postgres store. I6 org-scoped: every row carries organization_id; every route resolves the tenant via the shared tenancy primitive. Business outcomes (including a {error} payload) return HTTP 200 so a converging product's thin client is a 1:1 passthrough; non-200 is reserved for tenancy (401/403/422) + store-unavailable (503).

• Group: Commerce & revenue
• Contract: contracts/marketplace/v1/openapi.yaml
• Console: Manage the marketplace product in the console →
• Runbook: operational checklist for marketplace — internal (Vagary Labs ops; not part of this public site): docs/runbooks/capability-operations.md#marketplace
• Public base: https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
• Auth: a product API key (vgk_…) issued from the console — Authorization: Bearer vgk_…
• Product face (customer-keyed):
  • https://api.vagarylabs.com/product/v1/marketplace/items
• Capability face (internal first-party — NOT customer-keyed):
  • https://api.vagarylabs.com/v1/connectors
  • https://api.vagarylabs.com/v1/developers
  • https://api.vagarylabs.com/v1/items
  • https://api.vagarylabs.com/v1/stats
  • https://api.vagarylabs.com/v1/users

Edge route table

The routes this capability actually serves on the public edge — live-synced from GET https://api.vagarylabs.com/product/v1/_meta/catalog (snapshot v1). The metric is the request-granularity billing counter; the scope is the key permission required.

Product face (customer-keyed)

Method	Path	Metric	Scope
POST	/product/v1/marketplace/items	marketplace_operations	write

Capability face (internal first-party — NOT customer-keyed)

• /v1/connectors
• /v1/developers
• /v1/items
• /v1/stats
• /v1/users

Endpoints

Method	Path	Summary
GET	/v1/items	List catalog items (filtered by status/category/addon_type)
POST	/v1/items	Submit an addon (→ pending_review)
GET	/v1/items/search	Search published items by name/description
GET	/v1/items/{item_id}	Get one item
PUT	/v1/items/{item_id}	Developer updates own item (allow-listed fields)
DELETE	/v1/items/{item_id}	Developer soft-deletes (unpublish) own item
POST	/v1/items/{item_id}/approve	Admin publishes a pending item
POST	/v1/items/{item_id}/reject	Admin rejects a pending item
POST	/v1/items/{item_id}/install	Install an item (payment-gated for paid items → 200 {error: Payment required} when unpaid)
DELETE	/v1/items/{item_id}/install	Uninstall an item
GET	/v1/items/{item_id}/reviews	List reviews for an item
POST	/v1/items/{item_id}/reviews	Add a review (must have installed; one per user/item)
POST	/v1/items/{item_id}/payments	Record a completed payment (product ran Stripe checkout — I5)
GET	/v1/items/{item_id}/payments/verify	Is there a completed payment for (user,item)?
GET	/v1/items/{item_id}/stats	One item's install/rating stats
GET	/v1/users/{user_id}/installed	A user's installed items
GET	/v1/developers/{developer_id}/items	A developer's items (any status)
GET	/v1/stats	Aggregate marketplace stats (admin)
GET	/v1/connectors	List the org's registered connectors (Row10d — connector-adapter registry)
POST	/v1/connectors	Register a connector (auth-config + typed actions) → published 'integration' item; body is the ConnectorSpec (optionally under spec)
POST	/v1/connectors/tools	Build the dialog-core tool bundle for a user's INSTALLED connectors — body {user_id, credentials?}; returns {tools, tool_dispatch, unresolved} (credentials rendered into headers only, never persisted)
POST	/v1/connectors/reference/{key}	Register a built-in reference connector (key: http
GET	/v1/connectors/catalog	Browse the ready-to-register connector catalog (~25 popular SaaS APIs; auth SCHEMES + typed action summaries only — no secret)
POST	/v1/connectors/catalog/seed	Bulk-seed catalog connectors into the org as addon_type='integration' items — body {keys?[], category?, base_urls?{}, developer_id?}; requires_base_url vendors without a base_url are skipped
POST	/v1/connectors/catalog/{key}	Register ONE catalog connector → published 'integration' item — body {base_url?, name?, developer_id?}; base_url REQUIRED for a requires_base_url vendor (your instance/store/subdomain host)
GET	/v1/connectors/{item_id}	Get one connector's stored spec (auth SCHEME only — never a secret value)
GET	/health	Liveness (open, tailnet-scoped)
GET	/metrics	Prometheus metrics (open, tailnet-scoped)

Schemas

Error

Field	Type	Description
error	string

Item

Field	Type	Description
item_id	string
developer_id	string
name	string
description	string
addon_type	string
category	string
tags	array
price	number
pricing_model	string
version	string
status	string
rating_avg	number
rating_count	integer
install_count	integer
created_at	number
updated_at	number

---

Generated by scripts/gen-capability-docs.py from contracts/marketplace/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page. The Edge route table section is synced from the live edge catalog snapshot (v1) — re-sync with python3 scripts/sync-edge-catalog.py.