REST — apps

JSON endpoints for native and web apps, protected by the same OAuth 2.1 tokens and scopes as MCP. Auth endpoints: /register (dynamic client registration), /authorize, /token — standard PKCE flow; public clients use token_endpoint_auth_method: "none".

GET /api/subjects

Scope: likeness. The user's cast — refs only.

GET https://vault.helix.ai/api/subjects
Authorization: Bearer <token>

200 → { "subjects": [
  { "id": "a1b2c3d4", "name": "Fergus", "species": "dog",
    "photo_count": 5, "thumb": "data:image/jpeg;base64,..." }
]}

Refs and thumbnails are yours to cache for UI (a cast picker, a roster). Full photos are not exposed by any endpoint. Reads are audited to the user.

POST /api/subjects

Scope: likeness:write. Device-direct subject creation — call this from client code so photos travel user-device → vault and your servers never receive them. Downscale on device (~1024px JPEG works well).

POST https://vault.helix.ai/api/subjects
Authorization: Bearer <token>
Content-Type: application/json

{ "name": "Fergus", "species": "dog",
  "thumb":  "data:image/jpeg;base64,...",     // ~96px
  "photos": ["data:image/jpeg;base64,...", ...] }  // 1–8

201 → { "subject": { "id", "name", "species", "photo_count", "thumb" } }

User-initiated writes save directly (no review queue) but are audited: "added subject 'Fergus' — user-initiated, device-direct." Limits: 8 photos per request, 20 subjects per vault, 413 on oversized payloads.

POST /api/generate

Scope: likeness. Server-side generation from vault photos.

POST https://vault.helix.ai/api/generate
Authorization: Bearer <token>
Content-Type: application/json

{ "subject_ids": ["a1b2c3d4", "e5f6a7b8"],   // max 4
  "prompt": "A vintage four-panel photobooth strip...",
  "refs_per_subject": 2,                      // optional, 1–3
  "quality": "low",                           // optional: low | medium | high
  "size": "1536x1536" }                       // optional (default)

200 → { "image_b64": "...", "mime": "image/png",
        "model": "gpt-5.6-sol", "subjects": ["James","Fergus"] }

Reference photos go from the vault to the image provider only; your app receives finished pixels. Expect 30–60s — design your UI for it. Fewer, better references beat more: 2 per subject is the sweet spot.

Errors