Kit SDK and API boundaries
The real installation-scoped browser API, isolated operation capabilities, and developer control plane.
Start with the public packages
An independent Kit uses versioned @sine-kits/kit-contracts, @sine-kits/kit-sdk, @sine-kits/kit-ui, and @sine-kits/kit-cli packages. It must not import platform database, auth, worker, or application-shell internals. See the developer workflow for package access and CLI commands.
The seven platform applications have separate responsibilities: web for the public site and login, console for user workspaces, developer for publishing, admin for independent review, backend for trusted APIs, worker for asynchronous execution/deployment coordination, and docs for help. A Kit site is a separate deployment, not an eighth platform application that can read private platform code.
Browser authorization
Import browser APIs from @sine-kits/kit-sdk/browser:
readLaunchDescriptor()reads public installation and authorization bindings from a platform launch.completeKitAuthentication()completes the same-origin popup callback and removes authorization callback parameters from its URL.createKitClient({ platform, installationId })creates an installation-bound client.client.authenticate(launch)performs authorization-code + PKCE and checks the resulting installation/release binding.client.clearAuthorization()clears that client's in-memory authorization. It is not a server-side revocation of every session.
The browser client keeps the access token in memory and sends requests with credentials: "omit". It does not read a shared platform cookie. Use the platform's registered launch flow; do not invent a bearer token, persist it in local storage, or pass one in a URL. Endpoint URLs require HTTPS except on loopback.
A local development site can use the CLI's development proxy context. That is a development-only path, not an anonymous production credential or an Agent grant. Developer login does not confer access to buyer installations.
Installation-scoped HTTP surface
The routes below are implemented by the backend; call them through the SDK where possible. Here :installationId, :recordId, :assetId, and :runId denote real returned IDs, not literal path text.
| Browser SDK method | Backend route | Behavior |
|---|---|---|
installation() | GET /api/v1/installations/:installationId | Read the authorized installation |
records.list({ type }) | GET /api/v1/installations/:installationId/records?type=... | List records, optionally by type |
records.get(id) | GET /api/v1/installations/:installationId/records/:recordId | Read one record |
records.create({ type, data }) | POST /api/v1/installations/:installationId/records | Persist JSON domain data |
assets.list() / assets.get(id) | GET /api/v1/installations/:installationId/assets and .../assets/:assetId | Read resource metadata |
assets.create(metadata) | POST /api/v1/installations/:installationId/assets | Allocate metadata using name, MIME type, byte size, and SHA-256 |
assets.upload({ name, content }) | Metadata creation, then PUT /api/v1/installations/:installationId/assets/:assetId/content | Upload a Blob with integrity metadata |
assets.download(id) | GET /api/v1/installations/:installationId/assets/:assetId/content | Download authorized binary content |
runs.list() / runs.create(input) | GET / POST /api/v1/installations/:installationId/runs | List runs or submit a declared operation |
runs.get(id) / runs.logs(id) | GET /api/v1/runs/:runId and .../:runId/logs | Read an authorized run and its logs |
runs.cancel(id) | POST /api/v1/runs/:runId/cancel | Cancel a queued/running operation |
Changing an ID in a request does not change its authorization scope. Creating or launching a deployed installation is a first-party owner action, not a general Kit SDK capability. Current creation is restricted to publisher sandboxes with an available release and ready deployment.
The current browser upload limit is 16 MiB per asset. List endpoints currently return at most 1,000 records, assets, or runs; the SDK does not expose a pagination cursor. These are specific implementation limits, not a promise of unlimited storage or a universal API rate limit.
Submit work and follow the result
runs.create accepts operationId, JSON input, and an optional idempotencyKey. The backend requires a key; the SDK generates one when omitted. To retry the same submission after an ambiguous network result, retain and reuse the original key and input. Reusing a key with different operation/input/release content returns IDEMPOTENCY_CONFLICT.
Run creation returns HTTP 202 and a run object. It does not wait for the operation to finish. Use the returned ID with runs.get() and runs.logs(). The operation must be declared by the installation's active manifest. Cancelling a terminal run returns RUN_TERMINAL; cancellation cannot undo completed external side effects or already persisted records.
Operations run behind a capability boundary
Import defineOperation from @sine-kits/kit-sdk/server. A handler receives validated operation input and an installation/run-bound context. Declare the handler, input/output schemas, required capabilities, side effects, and execution mode in kit.manifest.json.
The current Game Dev Kit projects.create operation accepts a name and brief, then uses context.records.create to store a game-project record. This is a real data write, not a model-generation endpoint.
| Operation context | Available methods |
|---|---|
records | list, get, create |
assets | list, get, create, write, read |
| Logging | log(message) with redaction before transport |
| Bindings | Read-only installationId and runId |
The host authorizes each capability call. Operation asset RPC uses canonical base64 with a 512 KiB per-content limit, distinct from the browser upload limit. The context is not a database connection, a provider secret store, or an unrestricted HTTP client. The current SDK does not expose a generic 3D-generation capability.
Local development executes code with the developer's OS permissions; do not treat it as containment for malicious code. Deployed operations use the separate runner boundary, not imports into the web, backend, or platform worker process.
Publishing and review are separate APIs
The CLI and developer application use /api/v1/developer/... for publisher projects, environments, artifacts, releases, deployments, and authorized logs. Independent review uses the admin API. Prefer the documented CLI instead of constructing upload, revision, or approval requests manually.
A release identifies immutable content; a deployment places that content in an environment. A marketplace listing and a paid entitlement are different product concepts. publish --env preview does not approve, sell, or grant a Kit. Promotion uses an observed environment revision and explicit production confirmation; it does not rebuild the artifact.
Errors and diagnostics
Kit JSON success responses wrap their result in data; asset downloads return bytes. Kit API failures carry error.code, error.message, and a requestId when available. The browser SDK raises KitApiError with code, HTTP status, and optional requestId.
When reporting an error, include the operation or deployment ID, status, and request ID—not authorization headers, access tokens, provider secrets, or private record contents. A missing connection or denied authorization must be resolved explicitly; do not silently switch to a paid platform account or fabricate a successful result.