UI protocol conversation objects and read rules

These APIs read and maintain persisted records without submitting model inference or agent tasks. UI refers to this protocol and SDK method family; it does not mean current console entries have been verified.

Before you call this API

  1. Set BASE_URL to the target environment’s full product API prefix and prepare its personal access token MOI_KEY.

  2. Select a workspace through X-Workspace-ID. These paths have no workspace segment but still require a workspace identity and valid role in the same environment.

  3. Read positive integer SESSION_ID or MESSAGE_ID from the current user’s records. Keep them separate from agent conversation string IDs and A2A task IDs.

  4. Confirm the original record before writing. Read again when the result is unknown to avoid duplicate creation or repeated rating toggles.

Regular product endpoints reject additional task-runtime authorization headers. SDK conversations(workspace_id) also requires a workspace. Do not omit it merely because the URL has no workspace segment.

Conversation object

Details, creation, and update data, and list data.sessions[], use this object.

Field

Type

Description

id

integer

Server-generated conversation ID.

title

string

Conversation title.

source

string

Application source; open string. Empty source defaults to moi for UI creation and lists.

user_id

string

User ID owning the conversation.

config

string

Configuration text, not an embedded JSON object.

tags

array (array of objects)

Display tags. Current conversation storage reads return an empty array; this does not establish pinned status.

tags[].source

string

Tag source.

tags[].name

string

Tag name.

tags[].created_at

integer

Tag creation time in Unix seconds.

tags[].updated_at

integer

Tag update time in Unix seconds.

created_at

integer

Conversation creation time in Unix seconds.

updated_at

integer

Conversation update time in Unix seconds.

Although creation/update tags bind to the request type, they do not write tag relations. UI update source also has no effect. Creation/list source defaults differ from workspace LLM endpoints; do not conflate their omission behavior.

Message object

Message-list data[], message details, and like/dislike data use this object.

Field

Type

Description

id

integer

Message ID.

user_id

string

User ID owning the message.

session_id

integer or null

Associated conversation ID; null for historical records without an association.

source

string

Application source saved with the message.

role

string

Output role user, system, or assistant. Internal agent_tool maps to user in this protocol.

original_content

string

Original content text.

content

string

Saved message content.

model

string

Saved model name.

status

string

Saved message state, not a model task state.

response

string

Original response text.

modified_response

string

Modified response text.

config

string

Saved configuration text.

tags

array (array of objects)

Available message tags; may also be empty when optional tag projection fails.

tags[].source

string

Tag source.

tags[].name

string

Tag name. Product ratings use system/liked and system/disliked.

tags[].created_at

integer

Tag creation time in Unix seconds.

tags[].updated_at

integer

Tag update time in Unix seconds.

created_at

integer

Message creation time in Unix seconds.

updated_at

integer

Message update time in Unix seconds.

Message lists filter roles as strings. Only user, system, and assistant filter results; other strings currently mean no role filtering. source/model may bind but do not filter this list.

Regular pages, pinned subsets, and message cursors

Regular and unpinned conversation lists echo raw requested page/page_size. When omitted, responses may show0 while actual queries use 1/20. Regular page_size above 100 uses 20. Unpinned lists have separate compatibility behavior and do not normalize to that cap. Use explicit valid page numbers/sizes rather than treating echoed raw values as effective query values.

Pinned reads first take a regular conversation page and filter that page by system/pinned. Responses contain sessions only, without total or page numbers. For completeness, determine the page range through the regular list, then read pinned items on every page. Do not stop at one empty page. Tag-relation query failures may also yield empty pinned results, so emptiness alone does not establish there are no pinned conversations.

Message lists return a direct array sorted by ascending ID. Set after to the preceding page’s last ID and continue until an empty array. There is no total. Handle this separately from workspace message-list data.messages/total objects.

Success, errors, and result confirmation

All fourteen UI protocol operations return HTTP 200 on success with string OK in both code and msg. Creation is not201 and deletion is not204. Each action page defines its returned object type.

{"code":"ErrParamInvalid","msg":"Bad Request","data":null}

HTTP status

code

Current mapping

400

ErrWorkspaceRequired

Missing workspace context.

400

ErrParamInvalid

Invalid path ID, request decoding, or business input.

404

ErrNotFound

Not-found when reading conversation details.

500

ErrServer

General service error, including not-found cases not separately mapped by other operations.

Outer authentication and workspace admission may reject before the business handler. Do not apply the conversation-detail404 mapping to every message, update, deletion, pin, or rating operation; their current general error classifications differ.

Like/dislike operations toggle ratings. Repeated requests may remove the rating just added. Read the message after a timeout rather than automatically replaying. Failures removing an opposite rating are currently ignored, and optional tag-read failures may return an empty array. Mutual exclusion or cleared ratings are therefore not guaranteed on every failure path.

Conversation/message ownership is still scoped to the current user. Empty messages, maximum message ID0, empty tags, and successful conversation deletion do not independently prove target existence, model completion, or cleanup of other resources.

Last updated on