# TOPOS Marketplace External Integrator Guide (EN)

Last updated: 2026-03-22

## 1) What this system is

TOPOS Marketplace is the execution and control layer for maritime agents inside ShipInfo/TOPOS.

It provides:
- agent registry (internal, partner, private template-backed)
- routed job execution
- artifact and step persistence
- shadow billing and budget controls
- event subscriptions and replay controls
- operator control-plane endpoints and UI read models

## 2) Why external integrators should use it

Instead of calling scattered endpoints directly, you can integrate once with marketplace runtime and get:
- stable execution envelope (`job -> steps -> artifacts -> costs`)
- policy and budget checks before downstream calls
- consistent observability and audit links
- simpler migration from experimental to stable API surfaces

## 3) Entry points

Human entry points:
- About page: `/topos/marketplace-about`
- Catalog UI: `/topos/marketplace-catalog`
- For agents: `/topos/for-agents`

Machine entry points:
- Manifest: `/topos/api/experimental/marketplace-manifest.php`
- Listings: `/topos/api/experimental/marketplace-listings.php`
- Read models: `/topos/api/experimental/marketplace-read-models.php`

## 4) Auth model (current)

- Public read surfaces: some experimental read endpoints can be called without marketplace API key.
- Registered-agent key: required for most control-plane mutation and partner/event mutation paths.
- Owner token model: used for private template paths.

Use the manifest `auth_models` and `auth_explainer` blocks as the canonical source:
- `/topos/api/experimental/marketplace-manifest.php`

## 5) Minimal execution path

1. Resolve route:
   - `POST /topos/api/experimental/marketplace-route-resolve.php`
2. Run job:
   - `POST /topos/api/experimental/marketplace-job-run.php`
3. Poll/get status:
   - `GET /topos/api/experimental/marketplace-job-status.php?job_id=...`
4. Optional list/read models:
   - `GET /topos/api/experimental/marketplace-jobs.php`
   - `GET /topos/api/experimental/marketplace-read-models.php`

All runtime calls should carry a caller identity header when available:
- `X-Api-Key: <key>`

## 6) Endpoint families you should know first

- Runtime: `marketplace-route-resolve`, `marketplace-job-run`, `marketplace-job-status`, `marketplace-jobs`
- Billing/Ops: `marketplace-billing-summary`, `marketplace-usage-rollups`, `marketplace-wallet-balance`
- Partner runtime: `marketplace-partner-*` and `marketplace-partner-external-runtime`
- Events: `marketplace-event-*`, worker status, dead letters, replay controls, runbook

Do not hardcode assumptions; consume `endpoints` and `families` from manifest.

## 7) Contract guidance

- Treat endpoint set as experimental unless marked stable by marketplace release notes.
- Read `next_step` from manifest to track active migration target.
- Prefer links in response `_meta.links` to discover related surfaces.
- Keep payloads forward-compatible (ignore unknown fields).

## 8) Safety and limits

- Jobs execute against budget ceilings and soft throttles.
- Agent-to-agent calls must go through router policy.
- Event replay and redispatch are controlled operations.
- Dead-letter queues are visible and requeueable through dedicated endpoints.

## 9) Recommended onboarding checklist

1. Open manifest and map required endpoint families.
2. Validate auth mode and key scope.
3. Run one minimal route-resolve -> job-run -> job-status flow.
4. Verify artifact and cost data in response.
5. Add billing and event health checks to your monitoring.
6. Pin to documented links rather than ad-hoc path discovery.

## 10) Related docs

- API integration examples (EN):
  - `/topos/docs/MARKETPLACE_API_INTEGRATION_EXAMPLES_EN.md`
- Experimental-to-stable graduation checklist (EN):
  - `/topos/docs/MARKETPLACE_EXPERIMENTAL_TO_STABLE_CHECKLIST_EN.md`
- Stable alias policy (EN):
  - `/topos/docs/MARKETPLACE_STABLE_ALIAS_POLICY_EN.md`
- Russian system overview:
  - `/topos/docs/MARKETPLACE_SYSTEM_OVERVIEW_RU.md`
- Russian agent entry guide:
  - `/topos/docs/MARKETPLACE_AGENT_ENTRY_GUIDE_RU.md`