REST reference
REST is the system of record for federation mutations and many reads. GraphQL composes queries on top; it does not replace these paths.
| Spec file | federation-v3.yaml (OpenAPI 3.1) |
| Contract | 2026-05-plexon-federation-v3 |
| Auth | See Auth |
This page explains the registered operations in the SDK OpenAPI for this docs build. Some product routes exist in runtime specs but are not fully in the OpenAPI registry yet — those are listed under Coverage gaps.
Common headers
X-Service-Secret: <product secret>
X-Plexon-Contract-Version: 2026-05-plexon-federation-v3
X-Plexon-User-Id: <viewer user id> # required on viewer-scoped routes
Build them with buildFederationHeaders from @chbrdk/plexon-federation.
Operations in this OpenAPI build
| Method | Path | Purpose | Auth notes |
|---|---|---|---|
POST | /api/auth/validate-credentials | Check login material | Controlled; do this from a server |
PUT | /api/platform/provisioning/projects/{platformProjectId} | Upsert Collection mirror into a product | Service; body validated by upsert schema |
POST | /api/platform/provisioning/metron-project-origin | Example origin create (product-first) | Service; other products follow the same pattern with their path |
GET | /api/platform/provisioning/accessible-collections | Collections the viewer may open | Service + viewer id |
GET/POST… | /api/platform/provisioning/collections/{platformProjectId}/members | Membership | Service + appropriate actor |
… | /api/platform/provisioning/collections/{platformProjectId}/invites | Invites | Service + appropriate actor |
POST | /api/services/usage/events | Usage events | Service |
Exact request/response schemas: download the YAML or import the Zod schemas from the SDK — do not hand-roll parallel types.
Example — list accessible Collections
curl -sS "${PLEXON_BASE}/api/platform/provisioning/accessible-collections" \
-H "X-Service-Secret: ${PLEXON_SERVICE_SECRET}" \
-H "X-Plexon-Contract-Version: 2026-05-plexon-federation-v3" \
-H "X-Plexon-User-Id: ${PLEXON_USER_ID}"
Example — upsert (Control Plane → product)
Your product exposes the upsert URL from its capability descriptor. The Control Plane sends a PUT with Collection metadata. Validate with PlatformProjectUpsertRequestSchema, persist, return the upsert response schema.
Coverage gaps (honest)
These areas have product/runtime specs or paths but are not fully represented as first-class operations in the OpenAPI download yet. Until they are, treat the linked behaviour as “follow the SDK when present; otherwise ask the DIC team / read the suite API spec your team shares”:
| Topic | Status in this portal build |
|---|---|
| Viewer product catalogue | Documented in suite API specs; expand OpenAPI in a follow-up |
| Service profile | Same |
| Notification feeds / visibility | Wire types may exist in the SDK; OpenAPI coverage is catching up |
| System banners | Runtime + app chrome; OpenAPI follow-up |
When a gap closes, this page and the YAML download update together.
Errors
Prefer FederationErrorBodySchema for shared error shapes. Typical HTTP:
| Code | Meaning |
|---|---|
| 401 | Missing/invalid auth or actor |
| 403 | Authenticated but not permitted |
| 404 | Unknown Collection / resource |
| 409 / 422 | Conflict or validation |
What usually goes wrong
| Symptom | Fix |
|---|---|
| YAML and running server disagree | Pin SDK version; regenerate OpenAPI from the registry |
| Origin path 404 | You called another product’s origin URL — use your descriptor path |
| Members call works in staging UI but not from your app | Missing viewer header or wrong Collection id |
Next: GraphQL · TypeScript SDK · Onboarding recipe