API reference

Every operation a studio calls. A studio calls them through its runtime SDK client, with the token helmstudio or helm dev gives it in HELM_TOKEN; each operation below names the capability its token needs. The two public operations need no token.

Generated from api/openapi.yaml, whose conventions apply to every page here. They are quoted from the document as it is written:

Conventions that apply everywhere, so they are not repeated per operation:

- Tags. Every operation is `studio-api`, `launcher` or `public`, exactly one
  (Q1; `public` added in M6, Q9). Only `studio-api` operations are generated
  into helm-runtime-sdk. Every `studio-api` operation requires a studio token,
  with no exception (Q7): the launcher reads the job queue through its own
  `/launcher/jobs` paths (M4 first review, #2). A `public` operation needs no
  token, is a GET, carries nothing but the launcher's theme, and is the only
  kind of operation a studio's page may reach from its own origin.
- x-helm-group / x-helm-method name the SDK method, identical in Go, Python
  and Node (04 §4): `x-helm-group: assets`, `x-helm-method: adopt` is
  `c.Assets.Adopt`, `c.assets.adopt`, `c.assets.adopt`.
- x-helm-capability names the manifest capability a studio token needs
  (Q8). `token` means any valid studio token. Absent on launcher operations.
- x-helm-events on an SSE operation maps each event name to its data schema.
- Ids are bare ULIDs; timestamps are RFC 3339 (Q29).
- Errors are always the Error schema (Q4, 04 §4). Status → SDK error kind:
    400, 413, 416, 422 Invalid · 401 Unauthenticated · 403, 421 Forbidden ·
    404, 410 NotFound · 409 Conflict · 429, 507 QuotaExceeded ·
    501 Unsupported · 503 or no connection Unavailable · anything else Internal.
- PATCH always means a JSON merge patch (RFC 7396) over the resource's
  writable fields, sent as application/merge-patch+json: an object member
  merges, an array or scalar replaces, `null` removes (M4 first review, #11).
- Browser access (M6 Q10, resolving M4 Q27 and first review #12). A studio's
  page never holds a token. The runtime SDK's same-origin proxy, mounted at
  /helm/ on the studio's own server, forwards /helm/api/v1/<studio-api path>
  here with the studio's Bearer token added, and forwards nothing else. So
  <img src="/helm/api/v1/assets/{id}"> works, and /assets/{id} and
  /assets/{id}/thumb keep their Bearer security unchanged.
- Outside this document's servers.url, the daemon serves the helm packages
  as static files at /sdk/v1/ (helm.css, helm-runtime.js, …; 04 §8), GET and
  HEAD only, exempt from the Origin check like `public` operations (M6 Q14).
- Collections return a page: {items, next_cursor} with `limit` (default 50,
  max 200) and an opaque `cursor` (Q5). A cursor is only valid with the same
  filters it was issued for. Reclaim previews are single documents, not
  collections: their confirm digest covers the whole set.
- JSON request bodies are capped at 1 MiB (413 `too_large`).

The types every request and response is made of.