# TOPOS Marketplace Stable Alias Map and Deprecation Policy (EN)

Last updated: 2026-03-22

This document defines how experimental marketplace endpoints move to stable aliases.

## Machine endpoint

- `GET /topos/api/experimental/marketplace-stable-aliases.php`
- `GET /topos/api/experimental/marketplace-stable-canary-readiness.php`
- `GET /topos/api/experimental/marketplace-stable-promotion-dry-run.php`
- `GET /topos/api/experimental/marketplace-experimental-fallback-policy.php`
- `GET /topos/api/experimental/marketplace-deprecation-guardrails.php`
- `GET|POST /topos/api/experimental/marketplace-sunset-pilot.php`
- `GET|POST /topos/api/experimental/marketplace-sunset-pilot-validation.php`
- `GET /topos/api/experimental/marketplace-sunset-wave-dry-run.php`

Optional filters:
- `status=planned|pilot|ready`
- `family=discovery|catalog|runtime|events|ops`
- `include_policy=0|1`

## Policy summary

- Stable aliases are additive at rollout start.
- Experimental routes remain available during a documented grace period.
- Deprecation/sunset are announced via policy snapshots before removals.
- Current default grace period: 90 days.

## Current rollout target

- `Phase 21 — Stable Expansion`
- `Phase 22 — Stable Operations`
- `Phase 23 — Deprecation Execution`
- `Phase 24 — Sunset Pilot`
- `Step 3 — cohort ramp policy and rollback drill hardening`

## Pilot stable shims (canary)

- `GET /topos/api/v1/marketplace/manifest`
- `GET /topos/api/v1/marketplace/listings`
- `GET /topos/api/v1/marketplace/read-models`
- `POST /topos/api/v1/marketplace/routes/resolve`
- `POST /topos/api/v1/marketplace/jobs/run`
- `GET /topos/api/v1/marketplace/jobs`
- `GET /topos/api/v1/marketplace/jobs/status`
- `GET|POST /topos/api/v1/marketplace/partner/agents`
- `GET|POST /topos/api/v1/marketplace/events/triggers`
- `GET /topos/api/v1/marketplace/events/workflows`
- `GET /topos/api/v1/marketplace/events/runbook`
- `GET /topos/api/v1/marketplace/ops/wallet-balance`
- `GET /topos/api/v1/marketplace/ops/billing-summary`
- `GET /topos/api/v1/marketplace/ops/graduation-checklist`
- Canary activation during pilot:
  - query: `?canary=1`
  - header: `X-Marketplace-Canary: 1`

## Related docs

- External integrator guide:
  - `/topos/docs/MARKETPLACE_EXTERNAL_INTEGRATOR_GUIDE_EN.md`
- API integration examples:
  - `/topos/docs/MARKETPLACE_API_INTEGRATION_EXAMPLES_EN.md`
- Experimental-to-stable graduation checklist:
  - `/topos/docs/MARKETPLACE_EXPERIMENTAL_TO_STABLE_CHECKLIST_EN.md`
- Marketplace manifest:
  - `/topos/api/experimental/marketplace-manifest.php`