Save conversation response preferences

POST

/open/v1/conversation/response-settings/save

const url = 'https://api.harperharbor.com/open/v1/conversation/response-settings/save';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"conversationId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","expectedRevision":1,"patch":{"agency":"protect","style":"default","perspective":"card","length":"auto","lengthTarget":"200","pace":"natural","customStyle":"example","agencyNote":"example","styleNote":"example","perspectiveNote":"example","lengthNote":"example","paceNote":"example","streaming":"on"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.harperharbor.com/open/v1/conversation/response-settings/save \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "conversationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "expectedRevision": 1, "patch": { "agency": "protect", "style": "default", "perspective": "card", "length": "auto", "lengthTarget": "200", "pace": "natural", "customStyle": "example", "agencyNote": "example", "styleNote": "example", "perspectiveNote": "example", "lengthNote": "example", "paceNote": "example", "streaming": "on" } }'

HarperHarbor-only operation. Requires chat.play and conversation ownership.

Authorizations

userToken

Request Body^required

application/json

object

conversationId

required

string format: uuid

expectedRevision

required

integer

patch

required

object

agency

Any of:

string
null

string

Allowed values: protect coauthor

style

Any of:

string
null

string

Allowed values: default vivid guided card custom

perspective

Any of:

string
null

string

Allowed values: card first_character second_user third_limited third_omniscient

length

Any of:

string
null

string

Allowed values: auto recommended brief balanced detailed target

lengthTarget

Any of:

string
null

Reply length target, required with length=target and rejected otherwise; null removes it. A string holding one ladder value: 200, 300, 400, 500, 600, 800, 1000, 1200, 1500, 2000, 2500, 3000, 4000, 5000, 7000, 10000. Counted in characters for Chinese, Japanese and Korean replies and in words for English. brief, balanced and detailed stay accepted and mean 300, 800 and 1500.

string

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

pace

Any of:

string
null

string

Allowed values: natural linger advance

customStyle

Any of:

string
null

string

<= 1000 characters

agencyNote

Any of:

string
null

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

styleNote

Any of:

string
null

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

perspectiveNote

Any of:

string
null

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

lengthNote

Any of:

string
null

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

paceNote

Any of:

string
null

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

streaming

Any of:

string
null

string

Allowed values: on off

Responses

200

Authoritative saved settings and resolved effective preferences.

application/json

object

conversationId

required

string format: uuid

revision

required

integer

scope

required

Allowed value: conversation

schemaVersion

required

Allowed value: 1

compilerVersion

required

integer

overrides

required

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 brief balanced detailed target

lengthTarget

Effective reply length target when length is target, absent otherwise. Characters for Chinese, Japanese and Korean replies, words for English.

integer

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

<= 1000 characters

agencyNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

styleNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

perspectiveNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

lengthNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

paceNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

streaming

Reply output: when on, content is returned incrementally; when off, the complete result is returned once generation finishes. On by default. World-mode turns always return content incrementally.

string

default: on

Allowed values: on off

effective

required

object

agency

required

string

Allowed values: protect coauthor

style

required

string

Allowed values: default vivid guided card custom

perspective

required

string

Allowed values: card first_character second_user third_limited third_omniscient

length

required

string

Allowed values: auto recommended brief balanced detailed target

lengthTarget

Effective reply length target when length is target, absent otherwise. Characters for Chinese, Japanese and Korean replies, words for English.

integer

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

pace

required

string

Allowed values: natural linger advance

customStyle

string

<= 1000 characters

agencyNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

styleNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

perspectiveNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

lengthNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

paceNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

streaming

Reply output: when on, content is returned incrementally; when off, the complete result is returned once generation finishes. On by default. World-mode turns always return content incrementally.

string

default: on

Allowed values: on off

defaults

required

What applies when the player has chosen nothing: platform defaults with the card’s author defaults on top. Show these for axes absent from overrides; resetting an axis returns to this value.

object

agency

required

string

Allowed values: protect coauthor

style

required

string

Allowed values: default vivid guided card custom

perspective

required

string

Allowed values: card first_character second_user third_limited third_omniscient

length

required

string

Allowed values: auto recommended brief balanced detailed target

lengthTarget

Effective reply length target when length is target, absent otherwise. Characters for Chinese, Japanese and Korean replies, words for English.

integer

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

pace

required

string

Allowed values: natural linger advance

customStyle

string

<= 1000 characters

agencyNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

styleNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

perspectiveNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

lengthNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

paceNote

Optional refinement of the selected option for this axis only; where it differs from the option, the note takes precedence. Nonblank, at most 200 Unicode code points.

string

>= 1 characters <= 200 characters

streaming

Reply output: when on, content is returned incrementally; when off, the complete result is returned once generation finishes. On by default. World-mode turns always return content incrementally.

string

default: on

Allowed values: on off

Example

{
  "scope": "conversation",
  "schemaVersion": 1,
  "overrides": {
    "agency": "protect",
    "style": "default",
    "perspective": "card",
    "length": "auto",
    "lengthTarget": 200,
    "pace": "natural",
    "streaming": "on"
  },
  "effective": {
    "agency": "protect",
    "style": "default",
    "perspective": "card",
    "length": "auto",
    "lengthTarget": 200,
    "pace": "natural",
    "streaming": "on"
  },
  "defaults": {
    "agency": "protect",
    "style": "default",
    "perspective": "card",
    "length": "auto",
    "lengthTarget": 200,
    "pace": "natural",
    "streaming": "on"
  }
}

400

Invalid request or patch. No settings changed.

application/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

Missing or invalid bearer token.

application/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

Chat.play scope required.

application/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
}

404

Conversation is unavailable to this caller.

application/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
}

409

Stale expectedRevision; reload without discarding the local draft.

application/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
}

503

Service unavailable.

application/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
}

Save conversation response preferences

Authorizations

Request Bodyrequired

Responses

200

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

404

Examplegenerated

409

Examplegenerated

503

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated