Project-scoped GET routes that currently power the live Refine workbench.
Project API
Integration contracts and server-owned route posture.
Integration-facing view for read contracts, guarded mutations, and broader platform-edge routes.
Live publishingRefine migration activeCadence: Monthly issue cycleRead-only previewUpdated Apr 5, 2026, 8:29 AM UTC12 read contracts
Refine runtime
The API lane now turns the workbench into a clearer SaaS platform, not only an internal UI shell.
Instead of hiding contracts in route files and release notes, the project now exposes its read surface, guarded mutation inventory, and platform-edge posture inside one server-backed integration desk.
Server baseline ready12 read contracts9 guarded writesBaseline Apr 5, 2026, 8:29 AM UTCWaiting for live sync
List endpoints with Refine-friendly pagination and richer project metadata.
Stable server-baseline resources for project-specific SaaS posture and contracts.
Operator-only mutations kept behind the server-side auth boundary.
Health, commerce, and webhook routes living outside the project UI shell.
Distinct read, operator, public-commerce, and verified-callback postures.
Latest guarded workbench actions now leave a visible audit trail.
The audit trail stays project-scoped so route governance can be checked quickly.
Auth modes
Each API path now has a clearer audience and trust rule.
- Project preview: Anonymous or non-operator viewers can read project-scoped workbench resources, but they cannot trigger side effects.
- Owner read lane: A signed owner session can keep project reads and operator-facing runtime views available without immediately widening into a heavier account-center model.
- Fresh owner write lane: Guarded project mutations now require a fresher owner-bound session, so compile, review, delivery, governed settings, and demand, telemetry, or usage intervention writes do not ride indefinitely on an older read cookie.
- Public commerce edge: Checkout creation and status lookup stay public-facing, but they still resolve through validated server handlers.
- Verified callback: Provider-originated webhook traffic is signature-verified before it can affect billing or activation state.
Operator ledger
Guarded writes now leave a visible audit trail instead of disappearing into private memory.
Recent guarded actions will appear here after the next operator write or pipeline run.
Response shapes
The route family is more useful when the browser and the server agree on one contract language.
| Shape | Contract | Detail |
|---|---|---|
| List response | { data, total, page, pageSize, ...summary } | Collection routes keep Refine-friendly pagination while still returning project-specific metadata such as summaries and warnings. |
| Detail response | { data } | Project detail resources stay calm and stable on first paint because the server baseline and client hydration share the same shape. |
| Mutation success | { data } or action-state payload | Operator routes return a machine-readable success shape while still supporting redirect-based flows for form posts. |
| Error response | { error, code, fieldErrors? } | Contract errors are normalized so browser runtime panels can surface safe messages without leaking service internals. |
Project read contracts
The resource family now has a visible read map instead of an implied one.
| Resource | Method | Access | Contract |
|---|---|---|---|
| Overview /api/workbench/project/core-publication/overview | GET | project | Detail resource with project-scoped summary data for the workbench. |
| Automation /api/workbench/project/core-publication/automation | GET | project | Detail resource with compile readiness, downstream lane posture, and protected operator compile actions. |
| Issues /api/workbench/project/core-publication/issues | GET | project | Collection resource with refine-friendly pagination and normalized list shape. |
| Reviews /api/workbench/project/core-publication/reviews | GET | project | Collection resource with refine-friendly pagination and normalized list shape. |
| Delivery /api/workbench/project/core-publication/delivery | GET | project | Collection resource with refine-friendly pagination and normalized list shape. |
| Audience /api/workbench/project/core-publication/audience | GET | project | Detail resource with aggregate demand posture, operator-safe watch controls, and no contact-level lead exposure. |
| Usage /api/workbench/project/core-publication/usage | GET | project | Detail resource with project-scoped usage throughput, intervention controls, and lane-utilization signals. |
| API /api/workbench/project/core-publication/api | GET | project | Detail resource with integration contracts, guarded mutation inventory, and platform edge coverage. |
| Billing /api/workbench/project/core-publication/billing | GET | project | Detail resource with commercial readiness, project-owned billing controls, and safe operator-only writes. |
| Events /api/workbench/project/core-publication/events | GET | project | Detail resource with telemetry posture, operator-safe watch controls, and no raw event-row exposure. |
| Settings /api/workbench/project/core-publication/settings | GET | project | Detail resource with governed project settings reads and safe operator-only writes. |
| Guide /api/workbench/project/core-publication/guide | GET | project | Detail resource with runbooks, release references, route maps, and durable operator memory for the live project. |
Writes and platform edges
The broader SaaS feel comes from exposing the real boundaries, not by pretending every route is the same.
| Mutation | Method | Access | Detail |
|---|---|---|---|
| Audience watch update /api/workbench/project/core-publication/audience | PATCH | operator | Saves aggregate-only audience focus, watch window, and operator note without exposing contact-level lead rows. |
| Usage intervention update /api/workbench/project/core-publication/usage | PATCH | operator | Saves project usage focus, intervention mode, target lane, and operator note without exposing billing or recipient-level internals. |
| Compile cycle /api/workbench/project/core-publication/automation/compile | POST | operator | Triggers the guarded compile lane while the service layer keeps issue materialization and downstream invalidation server-owned. |
| Review run /api/workbench/project/core-publication/reviews/run | POST | operator | Runs quality review for one issue slug through the protected operator lane instead of trusting browser access alone. |
| Review sweep /api/workbench/project/core-publication/reviews/sweep | POST | operator | Executes the full project review sweep to refresh gate posture across the current issue ledger. |
| Delivery run /api/workbench/project/core-publication/delivery/run | POST | operator | Runs the latest delivery candidate without exposing recipient-side side effects directly to the browser. |
| Governance update /api/workbench/project/core-publication/settings | PATCH | operator | Saves safe project-owned settings while provider secrets, billing authority, and execution control remain outside this route. |
| Billing controls update /api/workbench/project/core-publication/billing | PATCH | operator | Saves safe project-owned billing focus, primary public billing surface, and operator notes without exposing merchant secrets or buyer records. |
| Telemetry watch update /api/workbench/project/core-publication/events | PATCH | operator | Saves project telemetry focus, watch window, and operator note without exposing raw event rows or callback internals. |
| Edge route | Method | Access | Detail |
|---|---|---|---|
| Health check /api/health | GET | public | Release-proof and uptime route for validating the live worker without opening a protected operator screen. |
| Checkout create /api/billing/checkout | POST | public | Starts commerce from the public product surface while billing services keep provider credentials and validation server-side. |
| Checkout status /api/billing/status/[sessionId] | GET | public | Lets the member desk and recovery paths resolve billing state without forcing a heavyweight account system. |
| Paddle webhook /api/webhooks/paddle | POST | callback | Receives signed provider callbacks and turns them into billing proof inside the server boundary. |
Provider boundaries
The UI feels more mature when contract ownership is obvious.
- dataProvider: Builds project-scoped API URLs, pagination, and response normalization for Refine without owning security or business policy.
- accessControlProvider: Controls preview and operator affordances in the browser, but it is not treated as the final permission layer.
- Next.js route handlers: Remain the first enforcement boundary for auth, payload validation, and the public-versus-operator API split.
- Services and stores: Own D1 access, fallback behavior, and real side effects so the workbench can widen without coupling the UI to persistence.
Live notes
The integration desk should stay tied to current runtime truth, not only theory.
- Current compile posture: Automation currently resolves through the openai compile provider while the server keeps prompt and side-effect authority.
- Current billing environment: Commerce edges are running against the live billing environment with checkout enabled.
- Resource coverage: 12 project read contracts now exist across overview, execution, audience, usage, API, billing, events, settings, and guide lanes.
- Guarded write coverage: 9 operator mutation routes are mapped explicitly so broader SaaS posture does not weaken server ownership.
- Owner session posture: Protected ops and workbench writes now bind new sessions to a reserved owner email and require a fresher session window before sensitive mutations can proceed.
- Operator audit trail: Guarded workbench actions now emit a project-scoped audit trail, but no recent entries have landed for this project yet.