Agent configurations and authoring

Reading an agent configuration

GET /role/detail?roleId=… returns everything a client needs to start a conversation: 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.

User 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 instructions (customInstructions)	the turn

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

Authoring an agent configuration

A signed-in author can create and edit their own agent configurations through v1. Ownership checks, scopes, validation and quotas apply. New configurations default to unlisted: anyone with the ID can view their public presentation and use them through an authorized application, including a different application tenant. Communities manage review, listing and discovery independently. Private instructions and Lorebooks are not returned to players.

Use POST /role/:roleId/visibility with {"visibility":"private"} for owner-only access, or {"visibility":"unlisted"} to allow use by ID. The compatibility publish endpoint enables use by ID; it does not submit a community review or create a public listing. Provider takedowns and deleted resources remain unavailable. Conversations, player settings and charges belong to the calling application and player.

POST  /role                          → { roleId, roleVisibility, reviewStatus }
PATCH /role/:roleId                  basic profile, only sent fields change
POST  /role/:roleId/document         configuration text as one document ({ fields: {…} })
PATCH /role/:roleId/welcome          { roleWelcome, alternates?, prologue? }
GET   /role/validate?roleId=         configuration validation
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.

Lorebooks

GET  /worldbook/mine
POST /worldbook?roleId=               { 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" selects the keyword-matching Lorebook format: 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 Lorebooks keep the platform’s own matching. Keyword fields are always arrays.

When synchronizing to an existing configuration from another application, pass its roleId to Lorebook creation and to POST /media/references ({ url, roleId }). New resources are then stored with the owned target configuration. Only its author can use this placement option.

Limits

Per-language text limits: opening 8,000 characters (10,000 for English configurations), definition 10,000 (50,000), intro 500 (2,500). Lorebook entries follow the language of the configuration they are bound to: 4,000 characters each for Chinese, 6,000 for Japanese and Korean, 12,000 for English; a Lorebook bound to several configurations gets the largest of their limits. Image uploads share the site’s size limit and quota.