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

  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.

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.

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.

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.

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.

Last updated on