APIs¶

Target Architecture — Final-State Design

This page describes the final-state API surface of the Marketplace Platform. All endpoints follow the REST resource conventions in Naming Conventions and are versioned, tenant-scoped, and OAuth2-protected.

The Marketplace exposes six public REST APIs for catalog discovery, publishing, installation, and compatibility evaluation, plus internal APIs and gRPC contracts for high-throughput inter-service calls. Public APIs are fronted by the factory API gateway, carry the tenant context in a validated bearer token, and emit a canonical event for every state change.

API design principles¶

Resource-oriented — plural, hyphenated collection nouns under /marketplace; sub-resources nest under their parent asset.
Tenant-scoped — tenantId is derived from the bearer token, never from the request body; every query is filtered by it.
Idempotent writes — mutating endpoints accept an Idempotency-Key header; duplicate keys return the original result.
Async-friendly — long-running operations (publish, install) return 202 Accepted with an operation handle and emit completion events.
Provenance — traceId and correlationId from the event envelope propagate via traceparent / cs-correlation-id headers.

Public APIs¶

Method	Path	Purpose	Owning Service
`GET`	`/marketplace/assets`	List/search/facet catalog assets	MarketplaceCatalogService / MarketplaceSearchService
`GET`	`/marketplace/assets/{assetId}`	Get asset detail with versions	MarketplaceCatalogService
`POST`	`/marketplace/assets`	Publish (register) a new asset	AssetPublishingService
`POST`	`/marketplace/assets/{assetId}/versions`	Release a new asset version	AssetPublishingService / AssetVersionService
`POST`	`/marketplace/assets/{assetId}/install`	Install an asset version into a target	AssetInstallationService
`POST`	`/marketplace/assets/{assetId}/compatibility/evaluate`	Evaluate compatibility against a target	AssetCompatibilityService

Internal APIs¶

Internal APIs are reachable only within the platform mesh (mTLS, service identity) and are not exposed through the public gateway:

POST /marketplace/assets/{assetId}/dependencies/resolve — DependencyResolutionService
POST /marketplace/licenses and POST /marketplace/licenses/{licenseId}/revoke — LicenseService
GET /marketplace/pricing-plans and POST /marketplace/quotes — PricingService
POST /marketplace/publishers, GET /marketplace/publishers/{publisherId} — PublisherPortalService
POST /marketplace/assets/{assetId}/reviews — ReviewRatingService

gRPC¶

High-frequency, low-latency internal calls use gRPC contracts hosted on each service's .Api project:

CatalogQuery — GetAsset, BatchGetAssets (used by Agent Mesh during planning).
CompatibilityEvaluator — Evaluate, BatchEvaluate (used by the installation saga).
DependencyResolver — Resolve, DetectConflicts.
LicenseChecker — CheckEntitlement (called synchronously on the installation hot path).

gRPC messages carry the same envelope identity fields (tenantId, traceId, correlationId) as metadata, and gRPC is preferred over REST for inter-service traffic where round-trip latency matters.

Authorization¶

All endpoints require an OAuth2 bearer token issued by the factory authorization server. Authorization combines scopes and tenant-scoped roles:

Scope	Grants
`marketplace.read`	Browse catalog, view asset detail, search
`marketplace.install`	Install assets into projects the caller can access
`marketplace.publish`	Publish assets and release versions (requires verified Publisher)
`marketplace.review`	Submit reviews and ratings
`marketplace.admin`	Manage publishers, pricing plans, and trust tiers

Publishing additionally requires the caller's publisherId to be verified (see Security). Installation requires a valid License for paid assets, checked synchronously via LicenseChecker.

Versioning¶

The API is versioned by URL prefix at the gateway (/v1/marketplace/...); the table above omits the prefix for brevity.
Asset content is versioned independently through AssetVersion (semantic versioning), distinct from API versioning.
Breaking response changes introduce a new API version; additive fields are non-breaking and clients must tolerate unknown fields.

Examples¶

List / search assets¶

GET /marketplace/assets?type=AgentPack&q=billing&facet=publisher,rating&page=1&pageSize=20

{
  "page": 1,
  "pageSize": 20,
  "total": 3,
  "items": [
    {
      "assetId": "asset-7c1f",
      "name": "Billing Agent Pack",
      "assetType": "AgentPack",
      "publisherId": "pub-connectsoft",
      "latestVersion": "2.4.0",
      "rating": 4.7,
      "ratingCount": 128,
      "shortDescription": "Agents and skills for subscription billing workflows.",
      "tags": ["billing", "saas", "agents"]
    }
  ],
  "facets": {
    "publisher": [{ "value": "pub-connectsoft", "count": 3 }],
    "rating": [{ "value": "4+", "count": 3 }]
  }
}

Get asset detail¶

GET /marketplace/assets/asset-7c1f

{
  "assetId": "asset-7c1f",
  "name": "Billing Agent Pack",
  "assetType": "AgentPack",
  "publisherId": "pub-connectsoft",
  "description": "A pack of agents and skills implementing subscription billing, dunning, and metering workflows.",
  "tags": ["billing", "saas", "agents"],
  "rating": 4.7,
  "ratingCount": 128,
  "versions": [
    { "version": "2.4.0", "releasedAt": "2026-06-01T10:00:00Z", "signed": true, "compatibility": "dotnet10" },
    { "version": "2.3.1", "releasedAt": "2026-04-12T09:00:00Z", "signed": true, "compatibility": "dotnet10" }
  ],
  "pricingPlanId": "plan-team",
  "licenseRequired": true
}

Publish a new asset¶

POST /marketplace/assets

{
  "name": "Billing Agent Pack",
  "assetType": "AgentPack",
  "publisherId": "pub-connectsoft",
  "description": "Agents and skills for subscription billing workflows.",
  "tags": ["billing", "saas", "agents"],
  "pricingPlanId": "plan-team"
}

Response — 202 Accepted:

{
  "assetId": "asset-7c1f",
  "status": "PendingQualityScan",
  "operationId": "op-9a31",
  "traceId": "trace-9f1c2b7d"
}

Release an asset version¶

POST /marketplace/assets/asset-7c1f/versions

{
  "version": "2.4.0",
  "packageRef": "blob://marketplace/staging/asset-7c1f/2.4.0/package.zip",
  "releaseNotes": "Adds dunning skill and metering connector.",
  "dependencies": [
    { "assetId": "asset-billing-lib", "versionRange": ">=1.2.0 <2.0.0" }
  ]
}

Response — 202 Accepted:

{
  "assetId": "asset-7c1f",
  "version": "2.4.0",
  "status": "PendingSigning",
  "operationId": "op-9a32"
}

Evaluate compatibility¶

POST /marketplace/assets/asset-7c1f/compatibility/evaluate

{
  "version": "2.4.0",
  "target": {
    "projectId": "proj-booking-saas",
    "runtime": "dotnet10",
    "installedAssets": [
      { "assetId": "asset-billing-lib", "version": "1.3.0" }
    ]
  }
}

Response — 200 OK:

{
  "assetId": "asset-7c1f",
  "version": "2.4.0",
  "verdict": "Compatible",
  "evaluatedAt": "2026-06-11T12:00:00Z",
  "findings": [
    { "kind": "Dependency", "severity": "Info", "message": "asset-billing-lib 1.3.0 satisfies >=1.2.0 <2.0.0" }
  ],
  "traceId": "trace-9f1c2b7d"
}

Install an asset¶

POST /marketplace/assets/asset-7c1f/install

{
  "version": "2.4.0",
  "target": { "projectId": "proj-booking-saas", "environment": "development" },
  "requestedBy": "task-4d21"
}

Response — 202 Accepted:

{
  "installationId": "inst-5e2a",
  "assetId": "asset-7c1f",
  "version": "2.4.0",
  "status": "Resolving",
  "operationId": "op-9a40",
  "correlationId": "corr-3a6e1d40"
}

The installation progresses asynchronously through compatibility, dependency resolution, license check, and apply; completion emits AssetInstalled (see Events and Workflows).

Continue to Workers, Events, and Security.