Trial cards

A trial card is a temporary private card imported from a local file. It can include a tavern card, a worldbook and display rules, and supports worldbook recall, memory and model selection.

When a trial expires, the server removes it along with the conversations, worldbooks and display rules created for that trial.

Client keys

The client names each trial with a client key it controls, typically the id of the local draft (1–64 characters from A-Z a-z 0-9 _ -). Re-sending the same key updates the same trial instead of creating a second one; the server hashes every section and writes only what changed.

PUT    /trial-cards/:clientKey     create or update  → summary
GET    /trial-cards                { list, slots: { used, max }, ttlHours }
GET    /trial-cards/:clientKey     one summary; 404 trial_not_found after expiry
DELETE /trial-cards/:clientKey     remove now → { deleted, released }

The PUT body

Every section is optional; the body is the whole trial, so a section that is absent is removed if it existed before.

{
  "name": "Display name",
  "card":        { "roleDesc": "…", "roleDetailDesc": "…", "roleAvatar": "https://…", "talkExample": [] },
  "welcome":     { "roleWelcome": "…", "alternates": ["…"], "prologue": ["…"] },
  "worldbook":   { "name": "…", "format": "tavern", "entries": [ { "name": "…", "content": "…", "keywords": ["…"], "secondaryKeywords": [], "matchOptions": { "caseSensitive": false, "matchWholeWords": false, "selectiveLogic": 0 }, "isConstant": false, "isEnabled": true } ] },
  "authorAsset": { "rules": [ { "id": "…", "name": "…", "find": "…", "replace": "…", "enabled": true } ], "mountTrigger": "…", "mountLayer": "under" },
  "evict": false
}

• card takes the same fields as the document endpoint; roleWelcome inside it is ignored — openings live in welcome.
• worldbook.entries are the entries in full. Entries are keyed by a hash of their content: identical entries collapse, disabled entries are not created.
• authorAsset is the display-rule set applied to AI output.

Response

{ "clientKey": "draft-8f1c", "roleId": "…", "created": true,
  "expiresAt": "2026-09-08T14:03:00Z", "slots": { "used": 2, "max": 5 },
  "sections": { "card": "sha256:…", "welcome": "sha256:…", "worldbook": "sha256:…", "authorAsset": "" },
  "changed": ["card", "worldbook"],
  "worldbook": { "worldbookId": "…", "entries": 120, "created": 3, "deleted": 1 } }

Play it like any card: roleId goes to /role/detail and /conversation/start.

Limits and errors

Limit	Value
trials per account	5
time to live	72 hours from the last import or the last message in any of its conversations
worldbook entries	1,000 per trial, 3,000 characters each
display rules	128 KB per rule, 1 MB for the whole set
request body	4 MB

Status	error	Meaning
400	trial_invalid_key · trial_invalid_body · trial_unsupported	shape or value the server does not accept; message/detail say which
409	trial_slots_full	all slots taken and this key is new; body carries oldest — resend with "evict": true to replace it
413	trial_payload_too_large	detail: { reason, section, name, index, max, actual, unit }
404	trial_not_found	never existed, deleted, or expired
503	worldbook_unavailable	nothing was written

Expiry is a server-side sweep, so a trial may survive a few minutes past expiresAt; cleanup will not occur before that timestamp.

Keeping a trial

A trial card is a real private card, so the authoring routes work on it. Submitting it for review or changing its visibility removes its trial status: it is released from the registry, no longer counts against the slots, is never expired, and DELETE on its key only releases it ({ deleted: false, released: true }).