Skip to content
HarperHarborDocs

Read agent display rules for rendering

GET
/open/v1/role/author-asset/serve
curl --request GET \
  --url 'https://api.harperharbor.com/open/v1/role/author-asset/serve?roleId=example' \
  --header 'Authorization: Bearer <token>'

Returns presentation rules for an accessible agent configuration by ID across application tenants. Public and unlisted configurations are guest-readable; an explicit private configuration requires its author with role.read or chat.play. Missing, inaccessible or taken-down assets return 404. The compatibility status passed describes render eligibility, not community approval. Private instructions and Lorebooks are not included.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
roleId
required
string

Role id.

Responses

Section titled “Responses”

200

Section titled “200”

Player-visible asset.

Media typeapplication/json

Same as AuthorAssetResponse without rejectReason.

object
rules
required
Array<object>
object
id
required
string
name
required
string
find
required
string
replace
required
string
enabled
required
boolean
mountTrigger
string
mountLayer
string
Allowed values: under over cover ""
pageMode
required
string
Allowed values: classic immersive sandbox
status
required

passed when served; none when nothing is served.

string
Allowed values: none passed
version
required
integer format: int64
variants
object
key
additional properties
string
sharedState

Shared state the card declares: polls and counters players can write. Keys and option IDs are 1–64 letters, digits, ., _ or -, starting with a letter or digit; {} declares nothing. An invalid declaration is rejected with validate_reject (reason: sharedState).

object
polls

Up to 16 polls by key. options lists 2–12 option IDs; share: true also allows the poll on share links.

object
<= 16 properties
key
additional properties
object
options
required
Array<string>
>= 2 items <= 12 items unique items
share
boolean
counters

Up to 16 counters by key. maxStep is 1–1000 per write, perMember caps each player per period, goal is optional, and period is none, day or week (UTC+8).

object
<= 16 properties
key
additional properties
object
goal
integer
<= 1000000000000
maxStep
required
integer
>= 1 <= 1000
perMember
required
integer
>= 1 <= 1000000000
period
string
Allowed values: none day week
Example
{
  "mountLayer": "under",
  "pageMode": "classic",
  "status": "none",
  "sharedState": {
    "counters": {
      "additionalProperty": {
        "period": "none"
      }
    }
  }
}

400

Section titled “400”

invalid_param — roleId missing.

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
}

401

Section titled “401”

unauthorized.

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
}

404

Section titled “404”

role_not_found.

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
}

500

Section titled “500”

generic_error.

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
}