Workspace LLM conversation objects and calling rules¶
These APIs maintain separate conversation/message records and tags. They submit neither model inference nor agent tasks.
Before you call this API¶
Use product API credentials and a valid workspace role in the target environment.
Set
BASE_URLto that environment’s full product API prefix. The workspace path value must matchX-Workspace-ID.Obtain positive integer
SESSION_IDfrom the same environment’s conversation list, thenMESSAGE_IDfrom its message list. Keep numeric IDs separate from agent conversation string IDs and A2A task IDs.Nonempty
sourceandnamejointly 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.
Conversation records¶
Workspace conversation data or data.sessions[] uses this object. Timestamps are integer Unix seconds.
Field |
Type |
Description |
|---|---|---|
|
integer |
Server-generated positive integer conversation ID. |
|
string |
Conversation title; may be empty. |
|
string |
Application source; open string. |
|
string |
Current user ID owning the conversation. |
|
string |
Configuration text. JSON configuration is still returned as a string. |
|
integer |
Creation time in Unix seconds;0 when not recorded. |
|
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.
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 |
|---|---|---|
|
integer |
Message ID. |
|
string |
User ID owning the message. |
|
integer |
Associated conversation ID. |
|
string |
Application source of the message. |
|
integer |
0=user、1=system、2=assistant、3=agent_tool。 |
|
string |
Original content text. |
|
string |
Saved content text. |
|
string |
Saved model name. |
|
string |
Saved message state; default pending. |
|
string |
Saved original response text. |
|
string |
Saved modified response text. |
|
string |
Configuration text. |
|
integer |
Creation time in Unix seconds. |
|
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.
LLM tag definitions¶
Tags appear in data or data.tags[].
Field |
Type |
Description |
|---|---|---|
|
string |
Tag source, jointly identifying the definition with name. |
|
string |
Tag name. |
|
integer |
Creation time in Unix seconds. |
|
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.
Error format and result confirmation¶
Workspace operation business errors use numeric code and message:
{"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.