List messages of a conversation (newest first) or fetch specific messages by id

GET

/open/v1/conversation/messages

const url = 'https://api.harperharbor.com/open/v1/conversation/messages?conversationId=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0&pageNum=1&page=1&pageSize=50';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

curl --request GET \
  --url 'https://api.harperharbor.com/open/v1/conversation/messages?conversationId=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0&pageNum=1&page=1&pageSize=50' \
  --header 'Authorization: Bearer <token>'

Returns stored messages, newest first, plus durable operation outcomes. Requires chat.play and conversation ownership. pageNum starts at 1 (page is accepted as an older alias); pageSize defaults to 50 and is limited to 100. chats contains public chat IDs, message text, thinking text, model, turnStatus and completion state. Partial output remains visible after interruption. HarperHarbor advertises responseSettingsVersion=1 for conversation response preferences.

Authorizations

userToken

Parameters

Query Parameters

conversationId

required

string format: uuid

pageNum

integer

default: 1 >= 1

page

integer

default: 1 >= 1

Older alias of pageNum; used only when pageNum is absent.

pageSize

integer

default: 50 >= 1 <= 100

Responses

200

Successful response.

application/json

object

total

integer

size

integer

pages

integer

hasNextPage

boolean

chats

Array<object>

object

chatId

string format: uuid

chatRole

string

Allowed values: USER AI

chatMessage

string

contentThinking

string

isComplete

boolean

isFirst

boolean

model

string

turnStatus

string

operations

Array<object>

object

operationId

string format: uuid

clientOperationId

string

conversationId

string format: uuid

kind

string

Allowed values: send

state

string

Allowed values: accepted generating completed failed_retryable interrupted stopped

version

integer

outputDisposition

string

retryable

boolean

assistantChatId

string format: uuid

sourceChatId

string format: uuid

chargeCredits

integer

settled

boolean

allowedActions

Array<string>

operationStatusAvailable

boolean

schemaVersion

string

responseSettingsVersion

integer

Allowed value: 1

Example

{
  "chats": [
    {
      "chatRole": "USER"
    }
  ],
  "operations": [
    {
      "kind": "send",
      "state": "accepted"
    }
  ],
  "responseSettingsVersion": 1
}

400

Invalid_request

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

Unauthorized

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

Insufficient_scope: requires chat.play

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

Not_found: inaccessible resource

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

Chat_operation_conflict

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

Temporarily_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
}

List messages of a conversation (newest first) or fetch specific messages by id

Authorizations

Parameters

Query Parameters

Responses

200

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

404

Examplegenerated

409

Examplegenerated

503

Examplegenerated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated