Skip to content
HarperHarborDocs

Read the heat of several role cards at once

POST
/open/v1/role/heat
curl --request POST \
  --url https://api.harperharbor.com/open/v1/role/heat \
  --header 'Content-Type: application/json' \
  --data '{ "roleIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ] }'

Batch read for scheduled sync. Guest-readable: no Authorization header is required. Returns the heat (see RoleDetail.heat) of each requested card that an anonymous reader can see; private, deleted, taken-down or unknown ids are left out of the result rather than reported as errors. At most 200 ids per request.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
roleIds
required

Role ids (characterRoleId).

Array<string>
<= 200 items
Examplegenerated
{
  "roleIds": [
    "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Heat by role id.

Media typeapplication/json
object
heat
required

Map from role id to heat. Only readable cards appear.

object
key
additional properties
integer format: int64
talkNum

Map from role id to play-round count, matching RoleDetail.talkNum across published versions. Staging versions are excluded. Only readable cards appear.

object
key
additional properties
integer format: int64
Examplegenerated
{
  "heat": {
    "additionalProperty": 1
  },
  "talkNum": {
    "additionalProperty": 1
  }
}

400

Section titled “400”

Malformed body, an id that is not a UUID, or more than 200 ids.

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
}