Create or update a trial

PUT

/trial-cards/{clientKey}

curl --request PUT \
  --url https://api.harperharbor.com/open/v1/trial-cards/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "card": {}, "welcome": { "roleWelcome": "example", "alternates": [ "example" ], "prologue": [ "example" ] }, "worldbook": { "name": "example", "format": "tavern", "entries": [ { "entryId": "example", "name": "example", "content": "example", "keywords": [ "example" ], "secondaryKeywords": [ "example" ], "matchOptions": { "caseSensitive": true, "matchWholeWords": true, "selectiveLogic": 1 }, "category": "example", "isEnabled": true, "isConstant": true, "priority": 1, "sortOrder": 1, "lastUpdateTime": "example", "activationCount": 1 } ] }, "authorAsset": { "rules": [ { "id": "example", "name": "example", "find": "example", "replace": "example", "enabled": true } ], "mountTrigger": "example", "mountLayer": "under" }, "evict": true }'

• API base URL

The body is the whole trial; the server hashes every section and writes only what changed.

Authorizations

• oauth

Parameters

Path Parameters

clientKey

required

string

/^[A-Za-z0-9_-]{1,64}$/

Names the trial; re-sending the same key updates it.

Request Body^required

Media typeapplication/json

The whole trial. A section that is absent is removed from the trial if it existed before.

object

name

Display name for the trial card.

string

card

Same fields as /role/:roleId/document; roleWelcome inside it is ignored — openings live in welcome.

object

key

additional properties

any

welcome

object

roleWelcome

string

alternates

Array<string>

prologue

Array<string>

worldbook

object

name

string

format

Marks a SillyTavern-style world info book; omit for a native worldbook.

string

Allowed values: tavern

entries

Array<object>

object

entryId

string

name

string

content

string

keywords

Array<string>

secondaryKeywords

AND gate — the entry fires only when a main keyword and one of these both appear.

Array<string>

matchOptions

null for native entries; { caseSensitive, matchWholeWords, selectiveLogic } for tavern-format worldbooks.

object

caseSensitive

boolean

matchWholeWords

boolean

selectiveLogic

0 any · 1 not all · 2 none · 3 all of secondaryKeywords

integer

<= 3

category

string

isEnabled

boolean

isConstant

boolean

priority

integer

sortOrder

integer

lastUpdateTime

string

activationCount

integer

authorAsset

Display rules the canvas applies to AI output.

object

rules

Array<object>

object

id

string

name

string

find

string

replace

string

enabled

boolean

mountTrigger

string

mountLayer

string

Allowed values: under over

evict

Replace the oldest trial when all slots are taken.

boolean

Responses

200

Trial summary.

Media typeapplication/json

object

clientKey

string

roleId

string

created

boolean

expiresAt

Earliest expiry time. Cleanup may run a few minutes later.

string format: date-time

slots

object

used

integer

max

integer

sections

Sha256 per section

object

key

additional properties

string

changed

Array<string>

worldbook

object

worldbookId

string

entries

integer

created

integer

deleted

integer

Example^generated

{
  "clientKey": "example",
  "roleId": "example",
  "created": true,
  "expiresAt": "2026-04-15T12:00:00Z",
  "slots": {
    "used": 1,
    "max": 1
  },
  "sections": {
    "additionalProperty": "example"
  },
  "changed": [
    "example"
  ],
  "worldbook": {
    "worldbookId": "example",
    "entries": 1,
    "created": 1,
    "deleted": 1
  }
}

400

trial_invalid_key · trial_invalid_body · trial_unsupported

Media typeapplication/json

object

error

required

Machine-readable code. unauthorized means authentication failed. Refresh the token; if refresh fails, request authorization again.

string

message

required

One English sentence a client may show verbatim.

string

retryable

boolean

detail

Present on some 4xx errors with the offending part.

object

key

additional properties

any

Example

{
  "error": "unauthorized"
}

409

trial_slots_full — send the same PUT with evict true to replace oldest.

Media typeapplication/json

object

error

required

Machine-readable code. unauthorized means authentication failed. Refresh the token; if refresh fails, request authorization again.

string

message

required

One English sentence a client may show verbatim.

string

retryable

boolean

detail

Present on some 4xx errors with the offending part.

object

key

additional properties

any

Example

{
  "error": "unauthorized"
}

413

trial_payload_too_large — detail says exactly which limit.

Media typeapplication/json

object

error

required

Machine-readable code. unauthorized means authentication failed. Refresh the token; if refresh fails, request authorization again.

string

message

required

One English sentence a client may show verbatim.

string

retryable

boolean

detail

Present on some 4xx errors with the offending part.

object

key

additional properties

any

Example

{
  "error": "unauthorized"
}

503

worldbook_unavailable

Media typeapplication/json

object

error

required

Machine-readable code. unauthorized means authentication failed. Refresh the token; if refresh fails, request authorization again.

string

message

required

One English sentence a client may show verbatim.

string

retryable

boolean

detail

Present on some 4xx errors with the offending part.

object

key

additional properties

any

Example

{
  "error": "unauthorized"
}