API Map

Current API Worker

Source: apps/api-worker/src/index.ts

Method	Path	Status	Purpose
`GET`	`/`	Implemented	Returns `Hello Hono!`. Smoke test only.
`GET`	`/health`	Implemented	Returns `{ ok, service, time }` for worker health.
`GET`	`/openapi.json`	Implemented	Returns the first minimal OpenAPI document for local API exploration.
`GET`	`/docs`	Implemented	Serves Scalar API Reference for the local worker.

The current OpenAPI document is a small hand-authored skeleton. Zod/OpenAPI route registration is planned, not implemented.

Current Shell API Usage

Current facts:

No fetch(...) calls were found in apps/os-shell/src.
QueryClientProvider is wired in apps/os-shell/src/providers, but no useQuery calls are active yet.
openapi-fetch is installed but not used.
msw is installed as a dev dependency but no handlers are present.
/app-dev/scalar-api embeds the local Scalar docs at http://localhost:8787/docs.
Local fixtures live in packages/apps/system-apps/src/shared/mock-data.ts and app-local arrays.

Platform Foundation v0 API Direction

Status: Proposed.

When implementation starts, API routes should follow the accepted MSW + Hono + OpenAPI + Scalar direction:

Define Hono + Zod route definitions.
Generate or expose OpenAPI from the same route definitions.
Treat OpenAPI as the API truth for docs, typed clients, and mock parity.
Mirror the same route shapes in MSW for frontend development.
Use TanStack Query for server state in shell and app surfaces.
Keep remote server data out of Zustand.

Production DB writes, auth providers, and permission enforcement require explicit implementation approval.

Early Proposed Routes

These routes are proposed for v0.2.x planning. They do not exist unless marked Implemented above.

The older /api/spaces* sketches below predate the Runtime-first resource model. They should be treated as historical planning placeholders until they are renamed or replaced by an explicit Studio API design. They do not make /spaces/:spaceId a canonical Studio resource URL.

Method	Path	Status	Notes
`GET`	`/api/user/session`	Proposed	Current user/session and anonymous/authenticated state.
`GET`	`/api/spaces`	Proposed	List Spaces visible to the current viewer.
`POST`	`/api/spaces`	Proposed	Create a minimal Space; authenticated write.
`GET`	`/api/spaces/:spaceId`	Proposed	Read a Space by internal ID.
`PATCH`	`/api/spaces/:spaceId`	Proposed	Update minimal Space metadata; authenticated write.
`GET`	`/api/apps`	Proposed	List catalog or registered app summaries.
`POST`	`/api/apps`	Proposed	Register a minimal app; authenticated write.
`GET`	`/api/apps/:appId`	Proposed	Read app metadata by internal ID.
`PATCH`	`/api/apps/:appId`	Proposed	Update app metadata; authenticated owner/publisher write.
`POST`	`/api/apps/:appId/install`	Proposed	Persist profile-scoped or Space-scoped installation.
`POST`	`/api/apps/:appId/uninstall`	Proposed	Persist uninstall state.
`GET`	`/api/spaces/:spaceId/apps`	Proposed	List apps installed into a Space.
`GET`	`/api/apps/:appId/permissions`	Proposed	Read declared app permissions and grant seed state.

Later Proposed Routes

These are later routes for owner/slug URLs and Source/View work. They are not first-stage requirements.

Method	Path	Status	Notes
`GET`	`/api/spaces/by-slug/:owner/:slug`	Proposed later	Resolve public or shareable Space by owner/slug.
`GET`	`/api/apps/by-slug/:owner/:slug`	Proposed later	Resolve public or shareable App by owner/slug.
`GET`	`/api/sources`	Proposed later	List Sources visible to the current viewer.
`POST`	`/api/sources`	Proposed later	Create or attach a Source; authenticated write.
`POST`	`/api/sources/:sourceId/sync`	Proposed later	Start a Source sync run.
`GET`	`/api/views`	Proposed later	List Views visible to the current viewer.
`POST`	`/api/views`	Proposed later	Create a View over one or more Sources.

Access And Visibility Rules

Public reads may be allowed for public Spaces, public Apps, catalog listings, and selected Source/View outputs.
Authenticated writes are required for Space creation, App registration, install/uninstall, Source creation, View creation, and permission grants.
Internal IDs come first for v0.2.x; owner/slug resolution comes later.
API docs and OpenAPI should be protected by Cloudflare Access in early development, as documented in cloudflare-deploy-and-access.md.
Public API docs should only expose stable public contracts after the internal contract has settled.

API Ownership

Hono worker owns HTTP routes, validation, and edge runtime behavior.
Zod/OpenAPI owns request and response shape once implemented.
Scalar exposes API exploration.
MSW mirrors the same contract for frontend development.
Shell apps call typed clients through app-local API modules or shared API clients.
Zustand should not hold remote data responses.