# SkillSafe Deploy — agent entry point

> Build hosted mini-apps on the SkillSafe app platform. Drive the platform HTTP API with a SkillSafe API key: save an agent prompt, create an app at https://{slug}.skillsafe.ai, upload a scanned frontend, and optionally publish it to the public directory.

This host IS the API: every `/v1/*` endpoint below is served directly on https://deploy.skillsafe.ai (Bearer auth only — cookies are ignored on this host). The same endpoints are also available at https://api.skillsafe.ai, interchangeably.

Agents call the platform API directly, as documented below. (Humans who prefer a conversational builder: https://creator.skillsafe.ai/ hosts the App Creator chat — browser sign-in required, not for agents.)

## Authentication

Send a SkillSafe API key as a Bearer token: `Authorization: Bearer <api-key>`.

- Create a key (sign in first): https://skillsafe.ai/account/keys — or mint one with zero signup (next section).
- Keys carry full account authority; the platform endpoints accept them in the Authorization header only (never cookies).

### No account? Temp deploy key (zero signup)

`POST https://deploy.skillsafe.ai/v1/auth/temp-key` — no auth, no body, strictly rate-limited (3/hour/IP) → `201 {"api_key", "expires_at", "account_id", "username", "namespace"}`.

The key works immediately for the whole deploy flow below: save the skill under the returned `namespace`, create an app, upload releases. It is scope-restricted — one app per temp account; no custom domains, secrets, schedules, or skill sharing.

Temp-key apps are **unlisted by default**, like any other deploy. They can be published to the public directory (`PATCH /v1/apps/{slug}` with `{"visibility": "public"}`) subject to the usual clean-scan gate, and appear there marked "Unclaimed" until the account is claimed via email verification.

**The key and everything deployed with it expire in 7 days** (`expires_at`). To keep them, verify an email before the deadline (Bearer: the temp key):

1. `POST https://deploy.skillsafe.ai/v1/account/email/send-code` with `{"email"}` — a 6-digit code is emailed (10-minute TTL).
2. `POST https://deploy.skillsafe.ai/v1/account/email/verify-code` with `{"email", "code"}` → `{"verified": true, "transferred", "account_id", "username"}`.

On success the temp key becomes a permanent, full-authority key and the account a normal one (signup credits included). If the email already belongs to a SkillSafe account, the temp account's apps, skills, and the key itself transfer into that account instead (`"transferred": true`); credit balances do not transfer. Without verification, the platform permanently deletes the account, its apps, and its skills after day 7.

**Always tell your user the 7-day deadline and the verify steps** — the deployed app is deleted otherwise.

```
curl -X POST https://deploy.skillsafe.ai/v1/auth/temp-key
# -> {"ok":true,"data":{"api_key":"sk_...","expires_at":"2026-…","username":"temp-a1b2c3d4","namespace":"@temp-a1b2c3d4"}}
```

### No key yet? Browser sign-in (device flow)

Mint a key the same way the SkillSafe CLI logs in — open a sign-in URL for your user, then poll until they approve:

1. `POST https://deploy.skillsafe.ai/v1/auth/cli` with `{"label": "my-agent"}` (label names the key, max 50 chars) → `201 {"session_id", "login_url", "expires_in"}`. The session lasts 15 minutes — create it immediately before opening the URL, not ahead of time.
2. Open `login_url` in the user's browser (or show it to them). They sign in to SkillSafe and click Approve.
3. Poll `GET https://deploy.skillsafe.ai/v1/auth/cli/{session_id}` about every 10 seconds (`/v1/auth/*` is limited to 10 req/min/IP). Response is `{"status": "pending"}` until approval, then once: `{"status": "approved", "api_key", "account_id", "username", "namespace"}`.

The approved response is a **one-time read** — the session is deleted as it's returned, so store `api_key` immediately. Keys minted this way are valid for 1 year. `410` means the session expired (start over); `404` means the session id is unknown or already consumed.

Pitfalls (each one ends in a "failed" page or a lost key):

- Use `login_url` **exactly as returned** — never compose the URL yourself. Opening `/auth/cli/?session=` with an empty or placeholder value (e.g. an unset `$SESSION` shell variable) shows "Missing session parameter".
- **Quote the URL** in shell commands: `open "$LOGIN_URL"` — unquoted, the `?` is a glob character in zsh and the command fails.
- After the user approves, do **not** re-open or refresh the page: the page's own status check would consume the one-time `api_key` before your poll does, and your next poll gets `404`.

```
curl -X POST https://deploy.skillsafe.ai/v1/auth/cli \
  -H "Content-Type: application/json" -d '{"label": "my-agent"}'
# -> {"ok":true,"data":{"session_id":"...","login_url":"https://skillsafe.ai/auth/cli/?session=...","expires_in":900}}

curl https://deploy.skillsafe.ai/v1/auth/cli/{session_id}
# -> {"ok":true,"data":{"status":"pending"}}            (keep polling)
# -> {"ok":true,"data":{"status":"approved","api_key":"sk_...","username":"alice","namespace":"@alice"}}
```

## Bootstrap endpoint

GET https://deploy.skillsafe.ai/v1/creator/me (Bearer auth) returns `{"username", "apps": [{"slug", "title", "visibility", "status", "has_release", "url"}]}` — who you are and what you own. Use `username` as your `@namespace` for skill saves. (Skippable for temp-key and device-flow keys — their mint responses already include `username`/`namespace`.)

## Deploying an app

1. Save a skill (the app's agent prompt / SKILL.md): `POST /v1/skills/@{you}/{name}` — multipart form with `file_SKILL.md` plus a `metadata` JSON field `{"version", "description", "category", "file_manifest": [{"path", "hash": "sha256:...", "size"}]}`.
2. Create the app: `POST /v1/apps` with `{"slug", "skill_id", "title", ...}`
3. Upload a frontend: `POST /v1/apps/{slug}/releases` with `{"files": [{"path", "content"}]}` or an App Spec `{"spec": {...}}`. The same request can declare database collections (see below), the per-user sandbox (`"sandbox": true` — see sandbox exec), and, for file releases, include a `functions/index.mjs` server function.
4. Publish: `PATCH /v1/apps/{slug}` with `{"visibility": "public"}`

The app is live at `https://{slug}.skillsafe.ai/` as soon as step 3 succeeds (visibility `unlisted` until published).

Every release is security-scanned; critical/high findings block it, and public visibility requires a clean scan on both the skill and the release. Release limits: max 500 files, 10 MB per file, 50 MB per bundle (spec app.json: 32 KB). Scanner tips: avoid dynamic code execution, document-write calls, environment-variable reads, and zero-width unicode (including ZWJ compound emoji) — these compose into blocking findings.

**Binary assets and vetted ML runtimes.** A release file may set `"encoding": "base64"` to ship binary content (WASM, model weights). Binary bytes can't be pattern-scanned, so base64 files are accepted only when their decoded bytes SHA-256-match the platform's vetted-bundle allowlist of exact published artifacts; anything else is rejected at upload. Files whose bytes match the allowlist (text or binary) skip pattern scanning — this is how ML runtimes whose glue code inherently combines file writes and fetches can ship — and are exempt from the 10 MB per-file cap (the 50 MB bundle cap still applies). Ship the published npm files verbatim; one changed byte falls off the allowlist and back under the full scanner. Currently vetted: the MediaPipe solutions suite (`@mediapipe/selfie_segmentation@0.1.1675465747`, `face_detection@0.4.1646425229`, `face_mesh@0.4.1633559619`, `hands@0.4.1675469240`, `pose@0.5.1675469404`, `camera_utils`, `drawing_utils` — models included in each package), `onnxruntime-web@1.27.0`, and `@tensorflow/tfjs@4.22.0` + `@tensorflow/tfjs-backend-wasm@4.22.0`. Apps are not cross-origin-isolated and blob workers are CSP-blocked, so WASM runs single-threaded — ONNX apps must set `ort.env.wasm.numThreads = 1` (tfjs falls back on its own). ONNX/TF.js MODEL files (`.onnx`, `model.json` weight shards) are separate binaries that also need vetting — request them, or another runtime, from the platform.

**Strict CSP — no inline JavaScript.** Apps are served with `Content-Security-Policy: script-src 'self'` (plus the platform SDK host): the browser executes only same-origin `.js` files shipped in the release. Inline `<script>` blocks, `on*=` handler attributes (`onclick=`, `onsubmit=`, …), and `javascript:` URLs never run — the page renders but every button and script is silently dead. Releases whose HTML contains any of these are **rejected at upload** (400 `VALIDATION_ERROR`; offending files and constructs listed in `error.details.violations`). Rules:

- Put ALL JavaScript in separate `.js` files: `<script src="/app.js" defer></script>`. Bind events with `addEventListener`, never `onclick=` attributes or `javascript:` hrefs.
- Third-party CDN scripts are blocked too — vendor any library into the release as a file.
- Inline `<style>` blocks and `style=` attributes are fine (`style-src` allows them). Inert `<script type="application/ld+json">` data blocks are also fine.
- `fetch`/XHR may only call same-origin paths and https://api.skillsafe.ai (`connect-src`).
- WebAssembly compilation is allowed (`script-src` includes `'wasm-unsafe-eval'` — WASM only, never JS eval), so client-side ML runtimes like MediaPipe work when shipped via the vetted-bundle allowlist above.

Manage apps with `GET /v1/apps` (yours), `GET /v1/apps/{slug}` (owner view), `PATCH /v1/apps/{slug}` (title, description, visibility, model, price; pass `"skill_id"` to re-snapshot that skill's latest SKILL.md as the app's system prompt — same ownership and scan gates as deploy), `DELETE /v1/apps/{slug}`.

Completely-free apps: the platform assigns a "Completely free" badge (shown in the public directory instead of "Usage-based") automatically — it is never set by hand. At release time the scanner checks the uploaded source for paid-API usage (`/v1/app-api/run`, `/v1/app-api/purchase`, `ss.run(`, `ss.purchase(`; a verbatim vendored copy of the platform SDK is recognized and ignored), and the label is granted while the app also has no `model`, `markup_bps` 0, `price_credits` 0, and no server functions or sandbox. It is re-derived on every release and settings change: adding any billable surface clears it, removing them restores it. While labeled, `/v1/app-api/run` and `/v1/app-api/purchase` return 403 and data-API usage is not metered to users — the badge is enforced, not advisory. Spec releases always submit agent jobs, so spec apps are never labeled free. Releases uploaded before this scan existed are unverified; upload a new release to earn the label.

Reference for the skill-save step: https://skillsafe.ai/docs/ and the OpenAPI spec at https://skillsafe.ai/openapi.json (the spec covers the skills registry API; the app platform endpoints are documented on this page).

## App capabilities: users & sign-in

Every app gets platform-managed identity — there is no user table to build. An app-user token (`aut_*`) binds {app, subject}; the subject is either a **guest** (anonymous browser identity) or a signed-in **SkillSafe user**. All `/v1/app-api/*` calls take it as `Authorization: Bearer {aut_*}`; app A's token can never touch app B's data.

- Guest session: `POST /v1/app-api/guest` with `{"slug"}` -> `{"token", "guest_id"}`. Always available, no sign-in. Guests can use the data and file APIs and view their balance, but cannot call server functions, use the sandbox, or make purchases — and can run the app's agent only while the owner sponsors usage (see payments).
- Sign-in (SkillSafe SSO) — **recommended: the popup flow, `ss.loginPopup()`**. It opens `https://skillsafe.ai/auth/app-login?app={slug}&display=popup&return={current-url}` in a small window; the user signs in there (or is authorized instantly from an existing session), the popup posts the `aut_*` token back to your page via `postMessage` (origin- and slug-checked) and closes itself. Your page never navigates, so in-memory state — an open document, a half-filled form, an undo history — survives sign-in. The promise resolves `{token}` (already stored by the SDK) and REJECTS on popup-block or a closed window: fall back to `ss.login()` then.
- Redirect fallback: `ss.login()` sends the browser to the same bridge without `display=popup`; the user returns to `return` with `?ss_token={aut_*}` appended — call `ss.captureRedirectToken()` on page load to capture/strip it, and stash any draft state in sessionStorage yourself before navigating. Use this lane directly only when popups are unacceptable (kiosk webviews, some in-app browsers).
- Under the hood, either lane's bridge page calls `POST /v1/app-api/authorize`; when the signed-in user is the app's own publisher the minted token also carries the `data:app` owner scope (writes app-owned records).
- Who am I: `GET /v1/app-api/me` -> `{"subject_type": "user"|"guest", "subject_id", "credits"}`. `subject_id` is the stable per-user id: it is the `owner_id` on every record the user creates, so collections give you per-user data (orders, profiles, carts) with no extra bookkeeping.
- Guest -> user upgrade: `POST /v1/app-api/authorize` (platform auth) accepts an optional `"guest_token"` and migrates that guest's credit wallet into the account. The stock app-login bridge does not pass the guest token through (cross-origin), so run this call yourself if guest wallets matter to your app.

SDK: `ss.guest()`, `ss.loginPopup()` (recommended, no page reload), `ss.login()` (redirect fallback), `ss.captureRedirectToken()` (call on page load for the redirect lane), `ss.user()`. The token persists in localStorage under `skillsafe_app_token:{slug}`.

## App capabilities: database

Apps persist structured data in declared **collections** of JSON records (max 50 per app). Declarations ship with the release:

- File release: top-level `"collections": [...]` next to `"files"` on `POST /v1/apps/{slug}/releases`. Omitting it leaves existing declarations unchanged.
- Spec release: `"collections": [...]` inside the app.json spec. The spec is authoritative: a collection absent from the spec is un-declared (records are kept but unreachable until re-declared).

```json
{
  "collections": [
    {
      "name": "orders",
      "acl_read": "owner",
      "acl_write": "user",
      "fields": [
        { "name": "total", "type": "number" },
        { "name": "status", "type": "string" },
        { "name": "placed_at", "type": "timestamp" },
        { "name": "gift", "type": "boolean" }
      ]
    }
  ]
}
```

- `name`: `^[a-z][a-z0-9_]{0,63}$`; `kv` is reserved.
- `acl_read`: `owner` (each user reads only their own records) or `shared` (all users read all records).
- `acl_write`: `owner` (only the publisher writes, app-owned records), `user` (each user/guest writes their own records), or `server` (only the app's server function writes).
- `fields` (optional, max 32): typed fields (`string | number | boolean | timestamp`) that become queryable and sortable; types are enforced at write time. Undeclared doc keys are stored but not queryable. Reserved field names: `record_id`, `owner_id`, `owner_type`, `created_at`, `updated_at`.
- `embed` (optional, max 4): declared string fields to embed for vector search — see "Vector similarity" below.

### Runtime endpoints

All take `Authorization: Bearer {aut_* app-user token}` (see Tokens below):

- `GET /v1/app-api/collections` - list declared collections
- `POST /v1/app-api/collections/{c}/records` with `{"doc": {...}}` - create (server-generated record_id)
- `PUT /v1/app-api/collections/{c}/records/{id}` with `{"doc": {...}}` - upsert with a chosen id (`^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$`)
- `GET /v1/app-api/collections/{c}/records/{id}` - read one
- `DELETE /v1/app-api/collections/{c}/records/{id}` - delete
- `POST /v1/app-api/collections/{c}/query` - query:

```json
{
  "where": { "status": { "eq": "draft" }, "total": { "gte": 20, "lt": 50 } },
  "sort": { "field": "total", "dir": "asc" },
  "limit": 50
}
```

Operators: `eq`, `ne`, `lt/lte/gt/gte` (string/number/timestamp), `in` (1-20 values), `contains` (string substring). Max 10 where-fields, 1-4 operators each. Filter/sort on declared fields plus `record_id`, `owner_id`, `created_at`, `updated_at`; default sort is `created_at` desc. `limit` max 100 (default 50); responses include `has_more` and a keyset `next_cursor` (resend with the same sort). Reads are ACL-filtered - with `acl_read: "owner"` a user's query only ever returns their own records.

### Tokens

Guest and signed-in tokens are covered in "users & sign-in" above. Access lanes for writes:

- Publisher (owner lane): the app publisher's own token carries `data:app` — it writes `acl_write: "owner"` collections as app-owned records and reads everything.
- Server lane: requests dispatched to the app's server function carry a gateway-minted `X-SkillSafe-App-Context` capability (HMAC-signed, 60 s TTL, stripped from inbound public traffic - unforgeable). With it the function can write `acl_write: "server"` collections and create records owned by the calling user.
- SDK: `ss.collection("orders").create(doc) / .get(id) / .put(id, doc) / .delete(id) / .query(q)`, `ss.collections()`. Spec apps load the SDK automatically from `/__sr/sdk.js`; file-release apps bundle their own copy of https://skillsafe.ai/apps-sdk/v1.js.

### Quotas and metering

- 64 KB per record doc; 10,000 records per collection; 1 MiB total per (app, user) including guests; 50 MiB total for app-owned (shared) records.
- Data ops accrue nano-dollars to the caller's credits (1 credit = $0.0001 = 10^5 nanos): read 100, write/delete 400, query 300 + 20 per row returned. Accrual settles one cent (100 credits) at a time; $0.03 (300 credits) of unpaid accrual blocks further ops with 402.

### Vector similarity

Declare `embed: ["title", "notes"]` on a collection and query it semantically:

- `POST /v1/app-api/collections/{c}/similar` with `{"text": "...", "limit": 10}` -> records ordered by similarity, ACL-filtered like every read. `text` max 2,000 chars; `limit` max 20 (default 10).
- Indexing is asynchronous (a `/similar` right after a write may lag by seconds) and there is no backfill — only records written after `embed` was declared are indexed.
- Metering: +1,000 nanos per record write that embeds; 1,500 nanos per query + 20 per row returned.

SDK: `ss.collection("notes").similar("vacation ideas", { limit: 10 })`.

### Legacy per-user KV

Simpler key-value storage per user: `GET /v1/app-api/data` (list keys), `GET/PUT/DELETE /v1/app-api/data/{key}` with `{"value": ...}` (SDK: `ss.data.get/set/delete/keys`). Limits: 100 keys, 32 KB per value, 256 KB total per (app, user). Internally this is the reserved `kv` collection.

## App capabilities: files

Four supported patterns:

1. **Static assets ship in the release**: up to 500 files, 10 MB per file, 50 MB per bundle (HTML, JS, CSS, JSON, images, fonts, WASM, ...), served at `https://{slug}.skillsafe.ai/{path}` with SPA fallback and a 5-minute cache.
2. **User files in the browser**: handle uploads client-side with the File API. The app CSP allows `blob:` and `data:` URLs for img/media/font, so viewers and editors can render user files entirely in memory (this is how pptx-viewer.skillsafe.ai works) — right for files that never need to reach a server.
3. **Server-side file storage** (R2-backed): per-user uploads with signed download URLs — and the bridge into the vision path (attach images to agent runs — see "AI agent runs").
4. **Small structured payloads** go in collection records (up to 64 KB of JSON each) or the KV store.

### File storage API

All take the `aut_*` app-user token (guests included):

- `POST /v1/app-api/files` — multipart upload: `file` (required), optional `name`; elevated lanes may pass `owner` (JSON) to store an app-owned shared asset
- `GET /v1/app-api/files` — list caller-visible files (own + app-owned; `limit`, `cursor`)
- `GET /v1/app-api/files/{id}` — metadata
- `GET /v1/app-api/files/{id}/url` — mint a signed download URL (10-minute TTL, no auth header needed — safe in `<img src>`)
- `GET /v1/app-api/files/{id}/content` — bytes (Bearer token, or `?token=` from `/url`)
- `DELETE /v1/app-api/files/{id}` — delete (revokes outstanding signed URLs)

Ownership is the ACL: files a user/guest uploads are private to them; app-owned files (uploaded with `owner` by the publisher or a server function) are readable by every user of the app. Limits: 10 MB per file, 20 MB per user, 200 MB app-owned, 500 MB per app across all owners, 500 files per owner. Metering (nanos to the caller): upload 2,000, read 200, delete 400.

SDK: `ss.files.upload(file, { name?, owner? })`, `ss.files.list()`, `ss.files.get(id)`, `ss.files.url(id)`, `ss.files.delete(id)`.

## App capabilities: server functions

**Availability: not currently enabled in production.** Server functions require the Workers-for-Platforms dispatch binding on the deployment; until it is active, a release containing `functions/` is rejected with `503 "Server functions are not enabled on this deployment"`. Build on client-side + data-layer patterns instead (see the store recipe below) — everything else on this page works today. The contract below applies once functions are enabled.

A file release may include `functions/index.mjs` (or `.js`) - deployed as an isolated Cloudflare Worker and routed at `https://{slug}.skillsafe.ai/api/*` (prefix configurable via `fn_route_prefix` on `PATCH /v1/apps/{slug}`). Constraints:

- Signed-in SkillSafe users only (guests get 401 before dispatch); inbound cookies and outbound Set-Cookie are stripped, and gateway security headers are enforced on the response.
- The function receives the original request with the caller's `Authorization: Bearer {aut_*}` app-user token intact, plus a fresh gateway-injected `X-SkillSafe-App-Context` capability.
- 30 ms CPU per invocation (50 ms max), 50 subrequests, 10,000 requests per app per day.
- Outbound fetch is restricted to an owner-managed allowlist: `GET/POST /v1/apps/{slug}/egress`, `DELETE /v1/apps/{slug}/egress/{domain}`.
- No direct database or storage bindings - call `/v1/app-api/*` with the forwarded user token; the `X-SkillSafe-App-Context` capability unlocks `acl_write: "server"` collections.
- Usage accrues to the calling user's credits (300 nanos per request + 20 per CPU-ms) with the same flush/debt rules as data ops; a user at the debt cap gets 402 until they top up.

## App capabilities: sandbox exec (containers)

**Availability: not currently enabled in production.** The sandbox needs the container binding on the deployment; until it is active, every sandbox op returns `503 "Sandbox execution is not enabled on this deployment"` and a release declaring `"sandbox": true` is rejected with the same 503 (identical dormancy model to server functions). The contract below applies once the sandbox is enabled.

Each signed-in user of the app gets an isolated Linux container (Python + Node preinstalled) for shell commands, code-interpreter runs, and scratch files. Declare it per release with a top-level `"sandbox": true` on `POST /v1/apps/{slug}/releases` (works for both file and spec releases; a release without the flag un-declares it, same model as `functions/`). Requires a verified email. The publisher can pause it any time with `PATCH /v1/apps/{slug}` `{"sandbox_disabled": true}`.

Endpoints (user `aut_*` tokens only — guests get 403):

- `GET /v1/app-api/sandbox` — preflight: `{"available", "declared", "disabled", "user_allowed", "daily_ops_remaining"}`. Never starts a container; guests may call it to decide whether to show a sign-in prompt.
- `POST /v1/app-api/sandbox/exec` — `{"command", "timeout_ms"?, "cwd"?}` -> `{"stdout", "stderr", "exit_code", "success", "truncated", "duration_ms"}`.
- `POST /v1/app-api/sandbox/run-code` — `{"code", "language"? ("python" default | "javascript"), "timeout_ms"?}` -> `{"output", "stderr", "error", "results", "truncated", "duration_ms"}`.
- Files: `GET /v1/app-api/sandbox/files?path=` (list, default `/workspace`), `GET /v1/app-api/sandbox/files/content?path=` (read, text only), `PUT /v1/app-api/sandbox/files` `{"path", "content"}`, `DELETE /v1/app-api/sandbox/files?path=`, `POST /v1/app-api/sandbox/mkdir` `{"path"}`. Paths must be absolute, no `..`.
- `DELETE /v1/app-api/sandbox` — destroy the caller's container (state is lost; the next op boots a fresh one).

Limits and behavior: commands cap at 8 KB, code at 128 KB, file writes at 1 MiB; stdout/stderr truncate at 64 KB with a `truncated` flag; `timeout_ms` clamps to 1-60 s (default 30 s); 2,000 ops per app per day (429 when spent). The container sleeps after ~2 minutes idle and state persists until it sleeps or is destroyed — treat the filesystem as scratch space, not storage (use the data layer or files API to persist). Expect a 2-3 s cold start on the first op after idle. The container has outbound internet access.

Billing: every op accrues to the calling user (100,000 nanos = 0.01 credit per op, + 10 nanos per wall-ms) on the same flush/debt pipeline as data ops — a user at the debt cap gets 402 until they top up. Declaring the sandbox marks the app billable, so it is never labeled "Completely free".

SDK: `ss.sandbox.status()`, `ss.sandbox.exec(command, {timeoutMs, cwd})`, `ss.sandbox.runCode(code, {language, timeoutMs})`, `ss.sandbox.files.list/read/write/delete/mkdir`, `ss.sandbox.destroy()`.

## App capabilities: AI agent runs

Every app is backed by its skill: the SKILL.md saved in step 1 is snapshotted as the app's system prompt, and users can submit jobs to it. Runs are usage-priced (model cost plus the publisher's `markup_bps` cut, which accrues to the publisher as earnings net of the platform fee) and charged to the calling user's credits. Signed-in users only, with one exception: guests may run while the owner sponsors usage (see payments).

### Models

Chosen via `model` on `POST /v1/apps` or `PATCH /v1/apps/{slug}`. Leave it unset and jobs run on the platform default — `@cf/google/gemma-4-26b-a4b-it` (keyless Workers AI, the cheapest option). Upgrade when output quality matters:

- `@cf/google/gemma-4-26b-a4b-it` — the default; roughly 30x cheaper than Claude Sonnet
- `claude-haiku-4-5`, `claude-sonnet-5`, `claude-sonnet-4-6`, `claude-opus-4-8` — Anthropic
- `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.1`, `gpt-5-mini` — OpenAI

Per-model hard caps (max output tokens + wall clock) bound spend regardless of the app price. A premium model is never silently downgraded: if its provider key is missing on the deployment the job fails and fully refunds.

### Endpoints

- `POST /v1/app-api/estimate` - worst-case credit cost for a run with this input; no charge, no job. Guests may call it, so you can show pricing before prompting sign-in. Body: the same JSON the run would submit (may be `{}`). -> `{"hold_credits", "min_credits", "model", "markup_bps", "sponsor_enabled"}`
- `POST /v1/app-api/run` - submit a job. Body: arbitrary JSON input, max 1 MB. Optional `Idempotency-Key` header makes retries safe (a replay returns `{"job_id", "deduped": true}`). A worst-case hold is reserved up front and the unused part is refunded at settlement - see "Pricing, holds & refunds" below for the 402 rules. -> `202 {"job_id"}`
- `POST /v1/app-api/run-stream` - same contract, streamed as SSE: a `job` event, `delta` events carrying `{"text"}`, then `done` (with the full output + charge) or `error`.
- `GET /v1/app-api/jobs/{id}` - poll for status + output: `{"status": "queued"|"running"|"succeeded"|"failed", "output", "error", "price_credits"` (the hold)`, "charged_credits"` (what was actually charged)`, "created_at", "completed_at"}`
- `POST /v1/app-api/extract` - reduce a link or an uploaded document to plain text for a run-input field (the gateway CSP pins your frontend to this API, so this is how an app ingests a user's URL or file). Body: JSON `{"url"}` (server-side fetch, redirects & size capped at 4 MB) or multipart with a `file` field (max 8 MB). Formats: PDF, .docx, HTML, text/markdown; legacy `.doc` is 415. Signed-in users only (guests 403); no charge; rate-limited. -> `{"text", "name", "content_type", "bytes", "truncated", "url"?}` — `text` is capped at 200k chars (`truncated: true` past it). Unreachable/blocking sites return 422 with a "paste the text instead" message to surface to the user.
- `POST /v1/app-api/import-url` - fetch a .pptx from a link and return the RAW BYTES (`Content-Type` is the pptx MIME type, not the JSON envelope — read with `res.arrayBuffer()`). Google Slides share URLs (`docs.google.com/presentation/d/{id}/...`) auto-rewrite to their `/export/pptx` endpoint; the deck must be shared "Anyone with the link" (a private deck returns 422 explaining how to share or upload instead; published-to-web `/d/e/` links are rejected with guidance). Direct `.pptx` links pass through; response is magic-byte-verified as a zip. Same SSRF discipline as `/extract`, 25 MB cap, signed-in users only, no charge, rate-limited.

SDK: `ss.estimate(input)`, `ss.run(input, idempotencyKey)`, `ss.runStream(input, { onDelta })`, `ss.jobs.get(jobId)`, `ss.jobs.wait(jobId)` (polls until terminal).

### Pricing, holds & refunds

Runs are prepaid by a worst-case hold and settled to actual usage:

- **Hold** (at submit): estimated input tokens (chars ÷ 4, plus a per-image surcharge) at the model's input list rate, PLUS the run's **output-token cap** priced in full at the output list rate — × 1.2 platform margin, + the publisher's `markup_bps` — rounded up to a whole credit. `estimate` returns it as `hold_credits`. The output cap dominates on premium models: gpt-5.6-sol holds 8,192 tokens × $30/MTok ≈ 2,958 credits (~$0.30) even for a one-word prompt.
- **Settle** (at completion): the charge is recomputed from ACTUAL token usage, never above the hold, and the remainder refunds immediately. `GET /v1/app-api/jobs/{id}` reports both `price_credits` (the hold) and `charged_credits` (the exact cost). A failed run refunds the whole hold. The user's billing activity (https://skillsafe.ai/account/billing/) shows one row per run with the exact settled cost.
- Build pricing UX on `charged_credits`; present `hold_credits` as "reserved", never as the price.

**Budget-scaled runs.** A balance below `hold_credits` does not reject the run. The platform scales the run's output-token cap down to what the balance affords and holds the balance instead; the provider-enforced `max_tokens` makes overrun impossible, so generation simply stops when the budget is spent. Contract:

- `estimate.min_credits` is the smallest balance that can run this input at all (enough for ~256 output tokens at the model's rates). 402 `PAYMENT_REQUIRED` happens only below `min_credits`.
- With `min_credits ≤ balance < hold_credits`, the run executes with a reduced output cap. A budget-truncated run is a SUCCESSFUL run: it settles and charges normally, and the job reports `"truncated": true` (`GET /v1/app-api/jobs/{id}` and the `done` SSE event) when the output hit the run's cap.
- On `truncated`, show a "response cut short — top up to continue" affordance. Session turns are jobs, so the same applies to chat; after a top-up the next turn continues the conversation with full budget.

### Vision — attach images to a run

Upload images through the files API, then reference them from a top-level `"$files"` array in the run input:

```js
const f = await ss.files.upload(fileInput.files[0]);   // the user's photo
const { job_id } = await ss.run({ instruction: "list the items", $files: [f.file_id] });
```

The platform loads the bytes from storage and passes them to the model as image content blocks — the model sees the images, never the raw id list. Rules: max 4 images per run; `image/jpeg`, `image/png`, `image/webp`, `image/gif`; 5 MB per image; each ref must be a file the caller may read (own upload or app-owned). The estimate adds a per-image surcharge to the hold; settlement charges actual provider usage. Works on `/run`, `/run-stream`, and `/estimate`.

### Per-run model override

A run input may carry a reserved top-level `"$model"` key to run THIS job on a different model than the app's configured one — the primitive behind multi-model comparison apps:

```js
const { job_id } = await ss.run({ prompt: "explain quicksort", $model: "claude-haiku-4-5" });
```

Rules: the value must be one of the platform model ids listed above (400 on anything else); only apps that have a `model` configured accept overrides (400 otherwise — a model-less "completely free" app stays free); absent/empty means the app's model, as always. The hold is priced on the override, the publisher BYOK lane is chosen by the override's provider, and settlement bills the override — all snapshotted at submit, so a later `PATCH` of the app's model never changes what an in-flight job runs or costs. `$model` is stripped before the model sees the input (like `$files`). `estimate` accepts it and echoes the effective `model`. Idempotent replays return the ORIGINAL job even if a retry passes a different `$model`. Works on `/run`, `/run-stream`, `/estimate`, and session turns (body field: `{"content", "stream"?, "$model"?}`; SDK `ss.sessions.send(id, content, { model })`).

### Sessions — multi-turn conversations

Server-kept history, so a chat app needs no message bookkeeping:

- `POST /v1/app-api/sessions` — create (max 20 live sessions per user)
- `GET /v1/app-api/sessions` — list own sessions; `GET /v1/app-api/sessions/{id}` — session + full history
- `POST /v1/app-api/sessions/{id}/messages` — run a turn: `{"content", "stream"?}`. A turn is a job — same holds, pricing, and sponsorship as `/run` (guests can chat on sponsored apps).
- `DELETE /v1/app-api/sessions/{id}` — delete, messages included

History is truncated oldest-pair-first to fit the model budget; max 200 messages per session. Sessions are strictly own-subject — no owner or server-lane reads. SDK: `ss.sessions.create()`, `ss.sessions.send(id, content, { stream?, onDelta?, model? })`, `ss.sessions.list()`, `ss.sessions.get(id)`, `ss.sessions.delete(id)`.

## App capabilities: payments

Apps can sell things for SkillSafe credits ($1.00 = 10,000 credits): `POST /v1/app-api/purchase` with `{"amount_credits": N, "idempotency_key": "..."}` atomically moves credits from the signed-in buyer's wallet to the app publisher's wallet. The publisher receives the amount minus the platform fee (10% standard; a per-account rate may apply) as publisher earnings — same as run markup. SDK: `ss.purchase(amountCredits, idempotencyKey)`.

- Takes the user's `aut_*` token — callable from the app frontend or a server function. The recipient is pinned to the app's publisher and the amount capped, so page code can only move a bounded, fully-ledgered amount to the accountable publisher, never to itself.
- Signed-in users only (guests get 403). Publishers MAY buy from their own app: every transfer pays the platform fee, so a self-purchase is a priced round trip, never an arbitrage.
- `amount_credits` is an integer 100–1,000,000 ($0.01–$100.00 per purchase). `idempotency_key` (required, max 128 chars, scoped per app+buyer) makes retries safe: a replay moves nothing and responds `deduped: true`.
- 402 when the buyer's balance can't cover the amount. Success response: `{"paid": true, "amount_credits", "deduped", "balance"}` (the buyer's balance after).

Wallet mechanics:

- Users top up at https://skillsafe.ai/account/billing at face value ($1 = 10,000 credits, no purchase fee). New accounts start with 3,000 free credits ($0.30) and active users get a 1,000-credit ($0.10) daily grant, so small purchases work without a card. Free-grant credits expire 7 days after they are granted.
- Balance check: `GET /v1/app-api/me` (`credits`). Runs, data ops, and function calls meter against the same wallet.
- Credit classes (cashability follows how money arrived): credits RECEIVED from other users (purchases, subscriptions, run/fn markup) arrive net of the platform fee and are redeemable; credits a user BOUGHT are spendable but not directly redeemable; free-grant credits expire after 7 days and can never convert to cash — not even after passing through an app (a grant-funded sale reaches the publisher as spend-only value).
- Cash-out: earnings mature 14 days after each sale, then redeem at face value in US dollars — no payout fee, $25.00 minimum, manual review. Aggregate shows on `GET /v1/apps/{slug}` (owner view, `earnings_credits`); redeem via `POST /v1/billing/redeem` or https://skillsafe.ai/account/redeem.
- There is no purchase-history endpoint on the app API: record an order in a collection right after a successful purchase, reusing the purchase `idempotency_key` as the record id so a retried checkout converges to one paid order (see the store recipe).

### Subscriptions (recurring, in-credit)

Monthly plans, charged from the subscriber's wallet to the publisher on the same rails as purchases. Read the division of labor first — it decides what code you must write:

**The platform runs the billing and reports status; your app manages the subscribers.** The platform charges the first period at subscribe, re-charges each month via a daily renewal sweep, applies the platform fee, and tracks status per subscription: `active` → `past_due` (failed renewal; retried daily for a 3-day grace window, still entitled) → `canceled`. That status is *displayed* read-only — subscribers see their plans at https://skillsafe.ai/account/billing, owners see live subscriber counts and monthly recurring revenue on the app dashboard — but the platform never *enforces* it: no run, data op, or API call behaves differently because a subscription exists, there are no subscription webhooks, and owners get no subscriber list (aggregate counts only; identities stay private). Everything a subscription *means* inside the app is code you write:

- render the plan offer and call subscribe (sign-in required — guests get 403)
- gate premium features by querying entitlements — at page load, after subscribe/cancel, and before each gated action; treat `active` AND `past_due` as entitled (matches what the user is charged for)
- expose a cancel button — the platform billing page shows status but has no cancel control; canceling is an app-API call only your app can offer
- if you need per-subscriber data (onboarding state, member since, usage), record it yourself in a collection keyed by `subject_id`

Declaring plans (owner, Bearer key): `PATCH /v1/apps/{slug}` with `"plans": [{"key": "pro", "title": "Pro", "credits_per_period": 50000}]` — up to 3 plans; `key` matches `^[a-z][a-z0-9_-]{0,31}$`; price is 100–1,000,000 credits per month ($0.01–$100.00); `"plans": null` withdraws the offer. Plans show on the public listing (`GET /v1/apps/{slug}/public`). Terms are snapshotted onto each subscription at subscribe time — editing or removing a plan affects future subscribers only, never a live subscription's price. Completely free apps cannot sell subscriptions.

App-API calls (user `aut_*` token):

- `POST /v1/app-api/subscribe` with `{"plan_key": "pro"}` — charges the first period immediately. 201 → `{"subscription": {...}, "deduped": false}`; already live on that plan → 200 with `"deduped": true` (no second charge); 402 insufficient balance; 403 guest or completely-free app.
- `GET /v1/app-api/entitlements` — the caller's live subscriptions for THIS app (never other apps): `{"entitlements": [{"sub_id", "plan_key", "status", "credits_per_period", "current_period_end", "cancel_at_period_end"}]}`. Empty array = not subscribed; guests always get an empty array.
- `POST /v1/app-api/subscriptions/{sub_id}/cancel` — cancel at period end: entitlement continues to `current_period_end`, then ends. No partial refunds; re-subscribing later starts a fresh period.

Billing mechanics you can rely on: each subscription's cycle is anchored to its own subscribe date (new period = old period end + 1 month — no proration, no drift; a late past-due recovery does not shift the cycle). Each period is one idempotent wallet transfer, so a user subscribed to several apps holds independent subscriptions that succeed or fail on their own. A user may hold one live subscription per plan — two different plans on the same app can be held simultaneously, so design plan sets as exclusive tiers or deliberate add-ons. Publisher earnings arrive net of the platform fee per period (see wallet mechanics above).

Gating pattern:

```js
const ents = await ss.entitlements();                    // [] for guests
const isPro = ents.some((e) => e.plan_key === "pro");    // active + past_due both count
if (isPro) showPremium(); else showPaywall();
// Re-check after ss.subscribe(), after cancel, and on page load. Entitlements
// are a query, not a push — there are no webhooks; poll at the moments that matter.
```

SDK: `ss.subscribe(planKey)` → `{subscription, deduped}`; `ss.entitlements()` → the entitlements array.

### Sponsored usage (owner-paid runs)

The owner can sponsor usage so users — guests included — run the app free within daily budgets: `PATCH /v1/apps/{slug}` with `"sponsor_enabled": true`, `"sponsor_daily_credits_per_user"` (max 5,000 = $0.50), `"sponsor_daily_total_credits"` (max 500,000 = $50.00). Sponsored holds come from the publisher's wallet; when a budget is exhausted, signed-in users silently fall back to self-pay and guests get 402 with `"reason": "sponsor_exhausted"` (prompt sign-in). `estimate` reports `sponsor_enabled` so the UI can show "free — sponsored". Sponsorship requires a `model` to be set on the app. This is the free-preview funnel: sponsor a cheap model, convert to sign-in/purchase when the allowance runs out.

### Profile + email notifications (opt-in scopes)

`POST /v1/app-api/authorize` accepts `"grant_profile": true` and/or `"grant_notify": true` (set `wants_profile`/`wants_notify` on the app so the login bridge asks for consent). With `profile`, `GET /v1/app-api/me` includes `{"display_name", "avatar_url"}`. With `notify`, the app's elevated lanes (owner-scoped token or server capability — never plain page code) can email that user without ever seeing the address:

- `POST /v1/app-api/notify` with `{"subject_id": "acc_…", "subject_line", "body_text"}` — plain text, escaped into a fixed template with a "via SkillSafe" footer + unsubscribe link. Limits: 1 email per (app, user) per day, 100 per app per day; subject 120 chars, body 4,000. Costs the app OWNER 10 credits ($0.001) per send.

## Owner operations

Owner-only management calls, Bearer API key:

- `GET /v1/apps/{slug}` - publisher view: status, latest release, aggregate metering, `earnings_credits`, sponsored spend today.
- `PATCH /v1/apps/{slug}` - beyond metadata/model/price: `plans`, `sponsor_*` (see payments), `wants_profile`/`wants_notify` (consent screen), `releases_keep` (retained release history), `fn_route_prefix`.
- `GET /v1/apps/{slug}/usage` - function/data usage counters; `GET /v1/apps/{slug}/logs` - recent function invocation logs (incl. captured `console.log` output).
- Releases: `GET /v1/apps/{slug}/releases` - history; `POST /v1/apps/{slug}/releases/{releaseId}/promote` - point the app back at a retained release (instant rollback).
- **Preview hosts**: every retained release also serves at `https://{slug}--{releaseId last 8}.skillsafe.ai/` without promoting it (static/spec only, noindex) - review a release before rollback/promote.
- **CI deploy tokens**: `POST /v1/account/keys` with `{"label", "scopes": ["apps:deploy"]}` mints a key restricted to pushing releases + reading own apps - safe to put in CI.
- Resource review (backs the /dashboard/app/{slug} page): `GET /v1/apps/{slug}/storage`, `.../releases/{id}/files`, `.../data/collections`, `.../data/files` (+ `DELETE .../data/files/{id}`), `.../users`, `.../jobs`, `.../earnings`.
- Custom domains: `GET/POST /v1/apps/{slug}/domains` (returns the `cname_target` DNS record to create; activates after admin approval), `DELETE /v1/apps/{slug}/domains/{domainId}`.
- Server-function config (stored now, active once functions are enabled - see above): egress allowlist `GET/POST /v1/apps/{slug}/egress` + `DELETE /v1/apps/{slug}/egress/{domain}`; secrets `GET /v1/apps/{slug}/secrets`, `PUT/DELETE /v1/apps/{slug}/secrets/{name}` (max 16, values write-only); ingress lanes `GET/POST/DELETE /v1/apps/{slug}/ingress` + `POST /v1/apps/{slug}/webhook-token/rotate` (anonymous public/webhook routes, owner-billed); schedules `GET/POST /v1/apps/{slug}/schedules`, `PATCH/DELETE /v1/apps/{slug}/schedules/{id}` (interval minutes).

## Recipe: a store (users + payments + inventory)

A full storefront with no backend, on the primitives above:

1. Declare two collections in the release: `products` (`acl_read: "shared"`, `acl_write: "owner"`) - the catalog/inventory, readable by everyone, writable only by you; `orders` (`acl_read: "owner"`, `acl_write: "user"`) - each buyer reads and writes only their own orders.
2. Seed inventory as the publisher: sign in to your own app (your token carries the owner lane) and `PUT` each product with a chosen record id - upserts, so re-running the seed is safe.
3. Storefront: `ss.guest()` on load so anonymous visitors can browse (`products` is shared-read); `ss.loginPopup()` when they want to buy (the cart survives sign-in).
4. Checkout: generate an order id, call `ss.purchase(price, orderId)`, then on success `ss.collection("orders").put(orderId, {...})`. Purchase idempotency + put-by-id make a retried checkout converge to one paid order.
5. Order history / entitlements: query `orders` - ACL filtering means a user's query only ever returns their own records. To gate a feature on payment, check for the matching order record.

Caveat: a buyer's token cannot write `products` (`acl_write: "owner"`), so client-side checkout cannot decrement stock - reconcile stock as the publisher, or move checkout into a server function (`acl_write: "server"`) once functions are enabled.

## SDK quick reference

File-release apps bundle https://skillsafe.ai/apps-sdk/v1.js; spec apps get it automatically at `/__sr/sdk.js`.

```js
const ss = SkillSafe.init({ slug: "my-app" });
ss.captureRedirectToken();                   // on page load: pick up ?ss_token from a redirect sign-in
await ss.guest();                            // anonymous session (or resume the stored token)
await ss.loginPopup().catch(() => ss.login());  // sign in WITHOUT reloading (recommended); redirect on popup-block
const me = await ss.user();                  // { subject_type, subject_id, credits, profile? }
await ss.estimate(input);                    // { hold_credits, sponsor_enabled, ... } - no charge
const { job_id } = await ss.run(input, idemKey);   // input may carry $files: [file_id, ...]
const job = await ss.jobs.wait(job_id);      // or ss.jobs.get(job_id)
await ss.runStream(input, { onDelta: (t) => out.append(t) });  // SSE run
const s = await ss.sessions.create();        // multi-turn AI (server-kept history)
await ss.sessions.send(s.session_id, "hello", { stream: true, onDelta });
const f = await ss.files.upload(fileInput.files[0]);  // R2-backed file storage
img.src = await ss.files.url(f.file_id);     // signed URL - <img>-safe
await ss.purchase(amountCredits, idemKey);   // { paid, deduped, balance }
await ss.subscribe("pro");                   // in-credit subscription plans
const subs = await ss.entitlements();
const orders = ss.collection("orders");      // .create(doc) .get(id) .put(id, doc) .delete(id) .query(q) .similar(text)
await ss.collections();                      // declared collections + ACLs
await ss.data.set("k", v);                   // legacy per-user KV: .get .set .delete .keys
```

## Limits

- 60 requests per minute per IP on `/v1/creator/*`; standard platform rate limits elsewhere.
- Daily save/publish limits apply to skill saves (see the platform guide).

## More

- SkillSafe platform guide for agents: https://skillsafe.ai/llms.txt
- App directory: https://skillsafe.ai/apps/
- Support: support@skillsafe.ai