<span id="ui-协议会话对象与读取规则"></span>

# UI protocol conversation objects and read rules

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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.

<span id="prepare"></span>
<span id="调用前准备"></span>

## 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.

<span id="session-object"></span>
<span id="会话对象"></span>

## 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.

<span id="message-object"></span>
<span id="消息对象"></span>

## 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.

<span id="pagination"></span>
<span id="普通页置顶子集与消息游标"></span>

## 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.

<span id="error-contract"></span>
<span id="成功错误与结果确认"></span>

## 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.

```json
{"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.
