Read an agent configuration presentation

GET

/open/v1/role/detail

curl --request GET \
  --url 'https://api.harperharbor.com/open/v1/role/detail?roleId=example' \
  --header 'X-XMLV3-Feature-Level: 1' \
  --header 'language: zh-Hant'

• Production

Guest-readable for public or unlisted configurations by ID across application tenants. Explicit private configurations require the author with role.read; invalid bearer tokens are rejected. Only the author with role.read receives model-facing instructions, translated private definitions and other private author fields. Other callers receive presentation fields only. Deleted or provider-taken-down configurations are unavailable to players; authorized authors can inspect their own taken-down configuration. Community review does not gate this endpoint.

Parameters

Query Parameters

roleId

required

string

Role id (characterRoleId). A missing or unknown id yields 400 with record not found.

Header Parameters

language

string

default: zh-Hans

Allowed values: zh-Hant zh-Hans en ja ko

Viewer language. Selects the asset host used in roleAvatar/roleBackground and the locale used for commentNum.

X-XMLV3-Feature-Level

integer

default: 1 >= 1

Client XMLV3 renderer feature level; reflected in xmlV3Compatibility.clientFeatureLevel.

Responses

200

Role card.

Media typeapplication/json

object

world

Present only on world cards. Viewers get each member’s id, name, avatar and profile plus maxSpeakers; the author also gets description, lorebookId, sex and strictness.

object

version

required

integer

Allowed values: 1

maxSpeakers

Members that may reply in one turn; default 2.

integer

>= 1 <= 3

strictness

How far the world honours outcomes the player declares.

string

Allowed values: lenient balanced strict

characters

required

Array<object>

>= 1 items <= 12 items

object

id

required

Stable member id; used by mention and by the speaker blocks.

string

/^[a-z0-9][a-z0-9_-]{0,31}$/

name

required

string

<= 60 characters

avatar

Https URL, optional.

string

sex

string

profile

Short public side note everyone in the world knows; shown to viewers.

string

<= 600 characters

description

Private full definition; only this member’s own turns see it. Author only in responses.

string

<= 60000 characters

lorebookId

A Lorebook the author owns, recalled only for this member. Author only in responses.

string

id

Numeric row id (not the public role id).

integer format: int64

characterRoleId

Public role id used as roleId everywhere.

string

characterUrl

string

roleName

string

userName

Player name the author chose for the card (empty when unset).

string

roleWelcome

Opening message.

string

roleWelcomeEn

string

roleWelcomeJa

string

roleWelcomeKo

string

roleNameEn

string

roleNameJa

string

roleNameKo

string

roleEngName

string

slug

URL slug, may be null.

string

nullable

roleDesc

Short intro.

string

roleDescEn

string

roleDescJa

string

roleDescKo

string

roleReadme

Detail introduction in Markdown, shown on the card’s public page like a README (base language). Empty string when the author wrote none. Readable by anyone who can see the card; never sent to the model during chat. Render it as sanitized Markdown.

string

roleReadmeEn

Detail introduction, English translation (present only when that translation exists).

string

roleReadmeJa

Detail introduction, Japanese translation (present only when that translation exists).

string

roleReadmeKo

Detail introduction, Korean translation (present only when that translation exists).

string

roleAvatar

HarperHarbor: compatibility alias for the portrait background of the agent configuration; no independent avatar is stored.

string format: uri

roleBackground

string format: uri

roleBackgroundLandscape

Optional landscape (16:9) background URL. The chat page uses it on wide screens and falls back to roleBackground; keep important elements in the central 75%.

string format: uri

roleShareImage

Optional share image URL (1.91:1, 1200×630) used as the link-preview og:image. Empty string when unset; callers fall back to another image.

string

roleSex

string

Allowed values: man women other ""

roleDetailDesc

Private definition; empty string for non-owners on /role/detail.

string

roleDetailDescEn

string

roleDetailDescJa

string

roleDetailDescKo

string

roleSpeech

string

roleVisibility

HarperHarbor defaults to unlisted (usable by ID without community listing).

string

Allowed values: private public waitReview unlisted

roleDefinitionVisibility

Whether the definition is shown publicly (private/public).

string

highDefined

string

roleState

Creation state (RoleStateWaitCreate, RoleStateCreating, RoleStateComplete).

string

roleType

Card type (e.g. story, companion, game, generator).

string

followNum

integer

talkNum

Conversation count (server substitutes the real count).

integer

talkNumReal

integer

isDefineByTemplate

boolean

roleOutputContract

Output contract; empty string for non-owners on /role/detail.

string

speechSpeed

number

from

Platform scope (all for cards created through this API).

string

language

Card language (zh-Hant, zh-Hans, en, ja, ko, all).

string

imageNeedReview

boolean

enMarketSuitable

boolean

nullable

enMarketScore

integer

nullable

storeVisible

boolean

createTime

string format: date-time

nullable

publishedAt

Set when the card first passed review.

string format: date-time

nullable

lastUpdateTime

Bumped on any row update, including counters.

string format: date-time

nullable

contentLastEditedAt

Last author content edit.

string format: date-time

nullable

recommendStatus

recommended / normal / demoted.

string

rebateRatio

number

reviewStatus

Moderation status; pending corresponds to roleVisibility=waitReview.

string

Allowed values: "" not_submitted pending passed rejected

reviewReason

Reason when rejected / sent to review.

string

reviewTime

string format: date-time

nullable

forceHumanReview

boolean

roleGuideSummary

string

nullable

shareTextZhHant

string

shareTextZhHans

string

shareTextEn

string

shareTextJa

string

shareTextKo

string

themeId

required

Attached theme id; empty for default rendering.

string

xmlV3MinFeatureLevel

required

integer

xmlV3SpecVersion

string

xmlV3Capabilities

string

sourceConversationId

Only for AI-generated cards.

string

nullable

sourceRoleId

string

nullable

creationMethod

E.g. open_api, mcp, manual, ai_summarize, import, clone.

string

nullable

systemTag

System classification tag; empty string on /role/detail, omitted on /role/mine items when empty.

string

nickname

What {{char}} expands to in prompts when it should differ from roleName. Empty string means roleName is used.

string

<= 70 characters

cardMeta

One of:

object

Character Card V3 provenance kept for export and never used in prompts. Absent or null when the card has none.

object

creator

Original author credit.

string

characterVersion

Card version string as written by the author.

string

source

Source URLs or identifiers.

Array<string>

creatorNotesMultilingual

Language code → creator notes in that language.

object

key

additional properties

string

creationDate

Unix seconds.

integer

modificationDate

Unix seconds.

integer

null

null

roleTag

required

Parsed tag list ([] when the stored value is not valid JSON).

Array<object>

Platform tag as stored in roleTag.

object

icon

Icon identifier; empty for tags written through this API.

string

text

Tag text.

string

type

Tag kind; tags written through this API use 2.

integer

roleTagDesc

Always empty.

string

roleSpeechDesc

Echo of roleSpeech when it matches a known voice, else empty.

string

talkExample

required

Parsed example dialogue ([] when not valid JSON). Item shape follows what the write routes store.

Array<object>

object

roleType

required

Speaker; assistant is accepted and stored as ai.

string

Allowed values: ai user

content

required

Line text; trimmed; must be non-blank.

string

xmlV3Compatibility

required

object

clientFeatureLevel

required

From the X-XMLV3-Feature-Level header (default 1).

integer

minFeatureLevel

required

Minimum renderer level this card needs.

integer

canRender

required

boolean

state

required

string

Allowed values: supported unsupported

latestFeatureLevel

required

Latest renderer level known to the server.

integer

authorName

required

Author nickname.

string

authorAvatar

required

Author avatar URL.

string

accountNumId

required

Public numeric author id.

integer format: int64

isUserFollow

required

Whether the viewer follows the author (false for guests).

boolean

isFollow

required

Whether the viewer follows this role (false for guests).

boolean

welcomeAlternates

required

Alternate AI openings the player can choose before the first turn.

Array<string>

prologue

required

Player-side first-line options; a client fills the input with the chosen line rather than replacing the opening.

Array<string>

hasPreviewPage

required

Whether a published custom preview page exists (see /role/preview-page).

boolean

roleEntry

required

Recommended landing surface when the card is opened.

string

Allowed values: chat home

previewShowComments

required

Whether the role home page should show the comments tab.

boolean

hasConversation

required

Whether the viewer has a current conversation with this role (false for guests or on lookup error).

boolean

commentNum

required

Approved top-level comment count for the viewer language (0 on error).

integer format: int64

theme

Theme attached to the card (present only when themeId is non-empty and the theme engine is enabled).

object

themeId

string

themeName

string

themeDesc

string

themeCategory

string

style

Theme style payload as stored (string).

string

previewData

Theme preview data as stored (string).

string

thumbnail

string

responseDefaults

Author only; absent when the card has none.

object

agency

string

Allowed values: protect coauthor

style

string

Allowed values: default vivid guided card custom

perspective

string

Allowed values: card first_character second_user third_limited third_omniscient

length

string

Allowed values: auto recommended target

lengthTarget

string

Allowed values: 200 300 400 500 600 800 1000 1200 1500 2000 2500 3000 4000 5000 7000 10000

pace

string

Allowed values: natural linger advance

customStyle

string

>= 1 characters <= 1000 characters

agencyNote

string

>= 1 characters <= 200 characters

styleNote

string

>= 1 characters <= 200 characters

perspectiveNote

string

>= 1 characters <= 200 characters

lengthNote

string

>= 1 characters <= 200 characters

paceNote

string

>= 1 characters <= 200 characters

heat

Popularity of this card, summed across all published versions of the work. Each paid use by someone other than the author adds heat, weighted by the model’s price and never less than the credits charged. Heat only increases. Staging versions are not counted.

integer format: int64

Example

{
  "roleSex": "man",
  "roleVisibility": "private",
  "reviewStatus": "",
  "talkExample": [
    {
      "roleType": "ai"
    }
  ],
  "xmlV3Compatibility": {
    "state": "supported"
  },
  "roleEntry": "chat",
  "responseDefaults": {
    "agency": "protect",
    "style": "default",
    "perspective": "card",
    "length": "auto",
    "lengthTarget": "200",
    "pace": "natural"
  }
}

400

record not found (unknown roleId) or a database error string. Body is {"error": "<raw error string>"} (no message/retryable).

Media typeapplication/json

object

error

required

Error code (snake_case) or, for legacy handlers, a free-text/localized message.

string

message

Human-readable sentence. Present only on middleware errors and /me, /me/wallet.

string

retryable

Whether retrying may succeed. Present only on middleware errors, /me, /me/wallet and service/share routes.

boolean

required_context_tier

Only on a first-turn context_capacity_exceeded: the smallest context tier that fits the whole card with room to talk. Save it as context in player settings and resend. Absent when no tier fits.

integer

>= 1 <= 5

required_context_tokens

The token budget of required_context_tier for the selected model, for display.

integer

constant_lore_trim_fits

Only on a first-turn context_capacity_exceeded: whether saving trimConstantLore=true lets the card play at the current tier. Absent on mid-conversation capacity errors.

boolean

credits_needed

Only on insufficient_credits: the credits this turn needs before it can start. Absent when the refusal came without an estimate.

integer

credits_available

Only on insufficient_credits: the credits the wallet could set aside for it.

integer

Example^generated

{
  "error": "example",
  "message": "example",
  "retryable": true,
  "required_context_tier": 1,
  "required_context_tokens": 1,
  "constant_lore_trim_fits": true,
  "credits_needed": 1,
  "credits_available": 1
}

401

unauthorized — an Authorization header was sent but the bearer is invalid (guest access only applies when the header is absent).

Media typeapplication/json

object

error

required

Error code (snake_case) or, for legacy handlers, a free-text/localized message.

string

message

Human-readable sentence. Present only on middleware errors and /me, /me/wallet.

string

retryable

Whether retrying may succeed. Present only on middleware errors, /me, /me/wallet and service/share routes.

boolean

required_context_tier

Only on a first-turn context_capacity_exceeded: the smallest context tier that fits the whole card with room to talk. Save it as context in player settings and resend. Absent when no tier fits.

integer

>= 1 <= 5

required_context_tokens

The token budget of required_context_tier for the selected model, for display.

integer

constant_lore_trim_fits

Only on a first-turn context_capacity_exceeded: whether saving trimConstantLore=true lets the card play at the current tier. Absent on mid-conversation capacity errors.

boolean

credits_needed

Only on insufficient_credits: the credits this turn needs before it can start. Absent when the refusal came without an estimate.

integer

credits_available

Only on insufficient_credits: the credits the wallet could set aside for it.

integer

Example^generated

{
  "error": "example",
  "message": "example",
  "retryable": true,
  "required_context_tier": 1,
  "required_context_tokens": 1,
  "constant_lore_trim_fits": true,
  "credits_needed": 1,
  "credits_available": 1
}

403

..`) cannot call this route.

Media typeapplication/json

object

error

required

Error code (snake_case) or, for legacy handlers, a free-text/localized message.

string

message

Human-readable sentence. Present only on middleware errors and /me, /me/wallet.

string

retryable

Whether retrying may succeed. Present only on middleware errors, /me, /me/wallet and service/share routes.

boolean

required_context_tier

Only on a first-turn context_capacity_exceeded: the smallest context tier that fits the whole card with room to talk. Save it as context in player settings and resend. Absent when no tier fits.

integer

>= 1 <= 5

required_context_tokens

The token budget of required_context_tier for the selected model, for display.

integer

constant_lore_trim_fits

Only on a first-turn context_capacity_exceeded: whether saving trimConstantLore=true lets the card play at the current tier. Absent on mid-conversation capacity errors.

boolean

credits_needed

Only on insufficient_credits: the credits this turn needs before it can start. Absent when the refusal came without an estimate.

integer

credits_available

Only on insufficient_credits: the credits the wallet could set aside for it.

integer

Example^generated

{
  "error": "example",
  "message": "example",
  "retryable": true,
  "required_context_tier": 1,
  "required_context_tokens": 1,
  "constant_lore_trim_fits": true,
  "credits_needed": 1,
  "credits_available": 1
}