Cards and authoring

Reading a card

GET /role/detail?roleId=… returns everything a client needs to play: name, description, roleWelcome, welcomeAlternates, prologue, tags and the author’s display contract. GET /role/author-asset/serve?roleId=… returns the author’s page assets (display rules, styles, scripts) the canvas applies.

Player preferences and conversation settings use separate endpoints:

Endpoint	What it holds	Who reads it
player/preference	look settings — font, colours, wallpaper	your UI
player/role-settings	persona (userName, userSex, userDefine), chosen model/lane (selectModel), context tier, thinking depth, custom jailbreak	the turn

Both save endpoints merge: send only the fields you change. Persona text goes through moderation.

Authoring a private card

A signed-in author can create and edit their own private cards through v1. These HTTP endpoints use the same service logic, ownership checks, validation and quotas as the card-writer tools. Cards created here are private: the author can play them by id, nobody else can reach them until they are published and pass review.

POST  /role                          → { roleId, roleVisibility, reviewStatus }
PATCH /role/:roleId                  basic profile, only sent fields change
POST  /role/:roleId/document         card text as one document ({ fields: {…} })
PATCH /role/:roleId/welcome          { roleWelcome, alternates?, prologue? }
GET   /role/validate?roleId=         the pre-publish report
POST  /role/:roleId/publish          { userConfirmed: true, confirmationSummary }
POST  /image/upload                  multipart file (+ roleId) for avatars and backgrounds

document writes only the fields you send; omitted fields remain unchanged, including fields an older client does not support. On welcome, alternates and prologue are full replacements: omit to keep, send [] to clear.

Worldbooks

GET  /worldbook/mine
POST /worldbook                       { name, description?, tags?, format?: "tavern" }
POST /worldbook/:id/document          { metadata?, entries?: [{ op, … }], binding?: { roleId } }
GET  /worldbook/entry/list?worldbookId=&category?=
GET  /worldbook/bindings?roleId=

format: "tavern" marks a SillyTavern-style world info book. Its entries take the tavern path: keys are matched literally over the current user message plus the latest reply (single characters allowed, /pattern/flags keys as regular expressions, matchOptions.caseSensitive, matchWholeWords, selectiveLogic 0–3 = any / not all / none / all of secondaryKeywords); hits are inserted and only the rest is filled by semantic recall. Native worldbooks keep the platform’s own matching. Keyword fields are always arrays.

Limits

Per-language text limits: opening 8,000 characters (10,000 for English cards), definition 10,000 (50,000), intro 500 (2,500). Worldbook entries: 3,000 characters each. Image uploads share the site’s size limit and quota.