Skip to content
HarperHarborDocs

List the caller's own role cards

GET
/open/v1/role/mine
curl --request GET \
  --url 'https://api.harperharbor.com/open/v1/role/mine?pageNum=1&pageSize=20' \
  --header 'Authorization: Bearer <token>'

Lists role cards owned by the bearer account, newest first (by creation time). Only the caller’s cards are ever returned; identity comes from the bearer, not from any parameter. Requires the role.read capability. Cards that are hosted revisions or pending hosting transfers are excluded. Name and summary are returned in the card’s origin language (language). q searches the name and summary in every language of the card, case-insensitively and as a plain substring (no pattern syntax); Traditional and Simplified Chinese characters match each other, so 夜行侦探 finds 夜行偵探. total counts every card matching the filters, and hasNextPage tells whether a later page has more.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
pageNum
integer
default: 1 >= 1 <= 1000000

1-based page number. Out-of-range or non-numeric values are clamped to 1..1000000.

pageSize
integer
default: 20 >= 1 <= 100

Items per page. Out-of-range or non-numeric values are clamped to 1..100; the default is 20.

creationMethod
string

Only cards created through this origin. Empty = every origin. Not validated: an unknown value yields an empty list.

q
string
<= 100 characters

Keyword matched against the card name and summary in any of its languages: case-insensitive substring, Traditional and Simplified Chinese interchangeable. Surrounding spaces are ignored and only the first 100 characters are used. Empty = no keyword filter.

Responses

Section titled “Responses”

200

Section titled “200”

Page of the caller’s role cards.

Media typeapplication/json
object
roleList
required
Array<object>
object
characterRoleId
required

Card id.

string format: uuid
roleNumId
required

Public card number.

integer format: int64
language
required

Origin language of the card; name and summary are in this language.

string
roleName
required
string
roleDesc
required

Summary in the origin language.

string
roleAvatar
required

Same as roleBackground; kept for older clients.

string
roleBackground
required

Portrait image URL; empty string when the card has none.

string
roleVisibility
required

Card visibility, e.g. unlisted, public.

string
reviewStatus
required
string
talkNum
required

Chat count.

integer format: int64
creationMethod
required

Where the card was created.

string
total
required

Cards matching the filters across all pages.

integer format: int64
hasNextPage
required

Whether a later page has more cards.

boolean
Examplegenerated
{
  "roleList": [
    {
      "characterRoleId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "roleNumId": 1,
      "language": "example",
      "roleName": "example",
      "roleDesc": "example",
      "roleAvatar": "example",
      "roleBackground": "example",
      "roleVisibility": "example",
      "reviewStatus": "example",
      "talkNum": 1,
      "creationMethod": "example"
    }
  ],
  "total": 1,
  "hasNextPage": true
}

401

Section titled “401”

unauthorized — missing or invalid bearer.

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
Examplegenerated
{
  "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
}