<span id="工作区-llm-会话对象与调用规则"></span>

# Workspace LLM conversation objects and calling rules

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

These APIs maintain separate conversation/message records and tags. They submit neither model inference nor agent tasks.

<span id="request-prerequisites"></span>
<span id="调用前准备"></span>

## Before you call this API

1. Use product API credentials and a valid workspace role in the target environment.
2. Set `BASE_URL` to that environment's full product API prefix. The workspace path value must match `X-Workspace-ID`.
3. Obtain positive integer `SESSION_ID` from the same environment's conversation list, then `MESSAGE_ID` from its message list. Keep numeric IDs separate from agent conversation string IDs and A2A task IDs.
4. Nonempty `source` and `name` jointly identify a tag. Encode each independently in URLs. Do not directly concatenate values containing `/`, spaces, or `?` into paths.

`MOI_KEY` is a personal access token for the current environment. `WORKSPACE_ID`, `SESSION_ID`, `MESSAGE_ID`, `TAG_SOURCE`, and `TAG_NAME` must use actual values from that environment. Continue with response IDs after creating objects.

Conversation and message-body operations query by the current user. Details and conversation lists do not enumerate all workspace members' records. Tag definitions form a workspace-level collection. Reading, adding, and removing tag relations use separate endpoints. Empty lists or HTTP 204 do not prove target existence or current-user ownership.

<span id="session-object"></span>
<span id="会话记录"></span>

## Conversation records

Workspace conversation `data` or `data.sessions[]` uses this object. Timestamps are integer Unix seconds.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer | Server-generated positive integer conversation ID. |
| `title` | string | Conversation title; may be empty. |
| `source` | string | Application source; open string. |
| `user_id` | string | Current user ID owning the conversation. |
| `config` | string | Configuration text. JSON configuration is still returned as a string. |
| `created_at` | integer | Creation time in Unix seconds;0 when not recorded. |
| `updated_at` | integer | Update time in Unix seconds;0 when not recorded. |

Workspace conversation objects have no embedded `tags`, `page`, or `page_size`. Read tags through separate relation APIs. Shared SDK objects may expose these properties; default properties do not prove the server returned corresponding data.

<span id="message-object"></span>
<span id="消息记录"></span>

## Message records

Message detail `data` and list `data.messages[]` use this object. Stored states and model names do not establish that a model call actually occurred.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer | Message ID. |
| `user_id` | string | User ID owning the message. |
| `session_id` | integer | Associated conversation ID. |
| `source` | string | Application source of the message. |
| `role` | integer | 0=user、1=system、2=assistant、3=agent_tool。 |
| `original_content` | string | Original content text. |
| `content` | string | Saved content text. |
| `model` | string | Saved model name. |
| `status` | string | Saved message state; default pending. |
| `response` | string | Saved original response text. |
| `modified_response` | string | Saved modified response text. |
| `config` | string | Configuration text. |
| `created_at` | integer | Creation time in Unix seconds. |
| `updated_at` | integer | Update time in Unix seconds. |

Message objects have no embedded tags; read message tag relations separately. Creation permits role3, while current list service omits role filtering for `role=3`. This does not mean results contain only tool messages.

Message pagination uses `after`, not `offset`. Messages sort by ascending ID and next after is the preceding page's last ID. Returned `total` counts by role/state before applying `after`, so it is not a remaining count. Conversation and workspace tag lists use `page/page_size`. Handle these pagination schemes separately.

<span id="tag-object"></span>
<span id="llm-标签定义"></span>

## LLM tag definitions

Tags appear in `data` or `data.tags[]`.

| Field | Type | Description |
| --- | --- | --- |
| `source` | string | Tag source, jointly identifying the definition with name. |
| `name` | string | Tag name. |
| `created_at` | integer | Creation time in Unix seconds. |
| `updated_at` | integer | Update time in Unix seconds. |

Create definitions using `source/name`; add relations using `tag_source/tag_name`. Adding a relation may also create a missing tag definition. Removing a relation retains the definition. Deleting a definition removes all conversation/message relations for that source/name in the workspace.

`system/pinned`, `system/liked`, and `system/disliked` are product system tags. Use your own source names for business tags to avoid confusing them with product pin/like/dislike states.

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

## Error format and result confirmation

Workspace operation business errors use numeric `code` and `message`:

```json
{"code":2,"message":"invalid request"}
```

| HTTP status | Business code | Condition |
| --- | --- | --- |
| 400 | 2 | Workspace mismatch, nonpositive integer ID, invalid role/tag, or business parameters. |
| 404 | 3 | Conversation/message reads cannot find a record within the current user's scope. |
| 500 | 1 | Storage, conversion, or other service error. |

Body JSON decoding uses another error layer and may return HTTP 400 with string `code=ErrParamInvalid` and `msg`. Authentication/admission have their own errors. Do not decode every failure into the same numeric code type.

A conditional title mismatch may return HTTP 200 and the original value, not409 conflict. Repeated deletion of a missing conversation may return 404, while deleting a missing tag definition/relation may return 204. An empty tag-relation read does not replace existence checks through conversation/message details.

Saving messages and modifying response text do not call a model. Success describes only the storage operation. Conversation/message creation has no business-request-ID deduplication, and appending text is not idempotent. Read and confirm after timeouts to avoid duplicate creation/appends.

Confirm cleanup of messages, tags, and files separately after deleting a conversation. An empty deletion response does not prove other resources were cleaned. Track actual generated conversations, messages, and tags during verification and retain records of objects whose cleanup is unconfirmed.
