App runtime OpenAPI

The OpenCloud app runtime specification is a machine-readable OpenAPI 3.1 reference for coding agents building deployed applications.

It covers the same-origin runtime surfaces:

• stable deployment-pinned JavaScript SDK metadata;
• SDK-internal session brokering;
• owner-approved app access-token exchange for non-browser clients;
• backing app-schema database transport for data.table(...);
• opaque managed Files transport;
• app-defined Functions;
• SDK-owned native Web Push subscription management;
• safe runtime telemetry; and
• Realtime WebSocket connection metadata.

The specification intentionally does not mix in the OpenCloud control plane. App creation, source drafts, deployments, verification, secrets, backups, and telemetry are covered by the separate control plane OpenAPI.

Use it

Give an agent the stable public URL:

https://docs.opencloud.ai/openapi.yaml

Or download the source from this repository:

docs/openapi/app-runtime.yaml

The OpenAPI file describes backing HTTP boundaries. Browser code imports the deployment-pinned singleton from /_opencloud/sdk.js; it should not call those routes directly. The SDK owns bearer tokens, cookies, app identity headers, managed file IDs, Function access, parsing, and refresh behavior.

Background-job enqueue and status calls are a Function-only broker capability. The private backing routes are intentionally absent from this browser-facing OpenAPI contract; app code imports jobs from the @opencloud/server Function context instead of constructing an /_internal/jobs request.

For API and MCP-created integrations, an owner-created oc_app_... token can be sent directly as the Bearer credential on any authenticated runtime path. The edge supplies infrastructure credentials internally and translates the secret into a short-lived owner JWT, so PostgREST RLS and other app policies behave exactly as they do for that owner in the web app. The token is app-scoped and cannot call control-plane APIs.

Database records and Function request/response bodies are app-defined, so those portions of the schema are intentionally open-ended. Realtime messaging uses a WebSocket protocol; the file provides connection metadata through an x-opencloud-realtime extension while the JavaScript SDK owns subscription and publish behavior.