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¶
Set
BASE_URLto the target environment’s full product API prefix and prepare its personal access tokenMOI_KEY.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.Read positive integer
SESSION_IDorMESSAGE_IDfrom the current user’s records. Keep them separate from agent conversation string IDs and A2A task IDs.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 |
|---|---|---|
|
integer |
Server-generated conversation ID. |
|
string |
Conversation title. |
|
string |
Application source; open string. Empty source defaults to moi for UI creation and lists. |
|
string |
User ID owning the conversation. |
|
string |
Configuration text, not an embedded JSON object. |
|
array (array of objects) |
Display tags. Current conversation storage reads return an empty array; this does not establish pinned status. |
|
string |
Tag source. |
|
string |
Tag name. |
|
integer |
Tag creation time in Unix seconds. |
|
integer |
Tag update time in Unix seconds. |
|
integer |
Conversation creation time in Unix seconds. |
|
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 |
|---|---|---|
|
integer |
Message ID. |
|
string |
User ID owning the message. |
|
integer or null |
Associated conversation ID; null for historical records without an association. |
|
string |
Application source saved with the message. |
|
string |
Output role user, system, or assistant. Internal agent_tool maps to user in this protocol. |
|
string |
Original content text. |
|
string |
Saved message content. |
|
string |
Saved model name. |
|
string |
Saved message state, not a model task state. |
|
string |
Original response text. |
|
string |
Modified response text. |
|
string |
Saved configuration text. |
|
array (array of objects) |
Available message tags; may also be empty when optional tag projection fails. |
|
string |
Tag source. |
|
string |
Tag name. Product ratings use system/liked and system/disliked. |
|
integer |
Tag creation time in Unix seconds. |
|
integer |
Tag update time in Unix seconds. |
|
integer |
Message creation time in Unix seconds. |
|
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.