Manifest

Every app folder contains a manifest.json. The platform validates it when it syncs a source; a manifest that fails validation is skipped with an error.

{
  "appId": "ai.justadd.stickyboard",
  "slug": "stickyboard",
  "name": { "en": "Stickyboard", "de": "Stickyboard" },
  "version": "2.3.0",
  "sdkVersion": "1.0.0",
  "artifactPath": "app.html",
  "iconPath": "icon.svg",
  "events": ["board-updated"],
  "scopes": ["workspace:own"],
  "apiScopes": ["meetings:read"],
  "connectOrigins": ["https://api.example.com"]
}

Fields

* Provide either icon or iconPath.

Scopes

Scopes are the only capabilities an app has beyond rendering itself. Request the minimum you need.

workspace:own and store:own are granted automatically. Any other scope must be approved by an organization admin from Manage availability before the app can use it — an un-approved call is rejected.

Web Workers are available to every app (worker-src blob:), so heavy work can leave the main thread without asking for anything. WebAssembly is different: it widens what may execute in the sandbox, so it is opt-in through capability:wasm and, like any other approval, the org admin sees it before turning it on. Libraries such as pdf.js that can run either way will fall back to their non-WASM path when it is not granted.

REST API scopes

apiScopes lists the parts of the HUB.KI REST API (/v1/*) the app wants to call as the user who has it open — from the app through createAppApiClient / requestApi, or from its backend with the REST API token. Every REST API scope except responses:write is allowed; apps run AI through the responses:run scope and hub.responses instead.

"apiScopes": ["meetings:read", "documents:write"]

With any approved REST API scope the app can also call GET /v1/models and GET /v1/jobs.

Like scopes, declaring a REST API scope is a request. An organization admin approves each one in Manage availability; scopes that change data or act on the user's behalf — every *:write, connectors:invoke, connectors:approve, tracing:read and tracing_content:read — are marked Sensitive there. Requests act as the user who has the app open, so they never reach more than that user may see. You do not need api:access to call the REST API from the app; you need it only to hand the REST API token to your backend.

An entry that is not in the table above — including responses:write — skips the app on sync with the problem api_scopes_unknown.

Validation

A sync validates every manifest and its files. An app that fails any rule is skipped as a whole — and if it was published before, it goes offline (see Syncing). The admin interface only reports the number of skipped apps, so check these before uploading:

Further limits: name values up to 200 characters, description values up to 2,000, version up to 32, and up to 100 events of up to 100 characters each.

Network access

Apps run in a sandboxed iframe whose Content-Security-Policy blocks all network requests by default — fetch, XMLHttpRequest, WebSocket, EventSource, and sendBeacon to any origin, including your own backend. To let your app talk to a server, list its exact origins in connectOrigins:

"connectOrigins": ["https://api.example.com", "wss://realtime.example.com"]

Rules:

• Each entry must be an exact origin — scheme + host + optional port, no path, no wildcards. Use https:// for HTTP requests and wss:// for WebSockets; http:// and ws:// are allowed only for localhost / 127.0.0.1 during development. Up to 8 origins.
• The scheme is part of the origin. https://api.example.com does not allow wss://api.example.com, so a host you call with both fetch and WebSocket needs two entries. Count them against the limit of 8 when you plan your manifest.
• Declaring an origin is a request, not a grant. An organization admin approves each origin in Manage availability; only approved origins are added to the app's connect-src. Unapproved origins stay blocked.
• Requests and WebSocket handshakes from the app carry Origin: null, because the sandbox has no origin of its own. Your server must accept that origin.
• connect-src only covers connections the page opens itself. WebRTC media traffic is not governed by it, but WebRTC SDKs usually open a wss:// signaling connection, and some also fetch configuration over https:// — declare both.

See Calling HUB.KI from your backend for the end-to-end flow and the CORS requirement.

Versioning

• version identifies your release. Publish a new version to roll out changes; the platform re-reads the artifact on its next sync.
• sdkVersion declares the bridge contract. If its major version is not supported, the host refuses to run the app and shows an upgrade notice.