Conventions

Base URL and headers

All v1 endpoints live under https://api.harperharbor.com/open/v1. Every request carries:

Header	Value
Authorization	Bearer <access token>
language	one of zh-Hant zh-Hans en ja ko — Accept-Language is not consulted
from	web (optional)

Do not send cookies, site keys or account identifiers with these requests. The access token identifies the user.

Identifiers

Responses never contain the internal account UUID. A user is the public numeric id; cards, conversations, worldbooks and templates are opaque string ids. Do not parse them.

Errors

{ "error": "unauthorized | forbidden | not_found | internal",
  "message": "one English sentence naming the offending part",
  "retryable": true }

• 401 — authentication failed. Refresh the token; if refresh fails, ask the user to authorize again.
• 402 insufficient_credits — the user’s wallet cannot pay for this call.
• 409 — a limit or conflict, for example conversation_limit_reached with { limit, count }.
• 413 — a payload limit, with detail naming the section, field, maximum and actual size.
• retryable: true means the same request may succeed later; false means do not retry without changing something.

message is safe to show verbatim when your client has no copy of its own.

Merge semantics

Preference and document endpoints merge: omitted keys remain unchanged. Older clients can update supported fields without removing newer ones. Where a field is a full replacement (for example alternates and prologue on the welcome endpoint) the reference says so.

Lists and paging

List endpoints return { list: [...] } or a named array with count and limit. Message history is paged; conversations, archives and templates are small enough to return whole.

Versioning

v1 is frozen. New fields and new stream events may appear; nothing existing changes meaning or disappears. Treat unknown fields and unknown S→C events as ignorable.