Create session¶

Creates a visible session for the specified active agent. This interface only creates sessions and displays information, does not send messages, and does not start agent tasks.

POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/conversations

Preparation before calling¶

First confirm that the target agent is active. Prepare the personal access token, target workspace ID, and agent ID that have access to the target workspace.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: Target workspace ID, passed through the X-Workspace-ID Header and as workspace_id in the path.
$AGENT_ID: target agent ID.

Request example¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/conversations" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "'"$AGENT_ID"'",
    "title": "销售分析",
    "purpose": "chat",
    "pinned": false
  }'

Path parameters¶

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	Current workspace ID, must be consistent with `X-Workspace-ID`.

Request body¶

Parameters	Type	Is it required	Description
`agent_id`	string	Yes	Target agent ID; target agent must be active.
`agent_workspace_id`	string	No	ID of the workspace to which the target agent belongs. If not provided, the current workspace is used; only the current workspace or the system workspace can be specified.
`id`	string	No	Session ID. Generated by the server if not provided.
`title`	string	No	Session title, length cannot exceed 256.
`status`	string	No	Session state, can be `active` or `archived`; if not provided, `active`.
`purpose`	string	No	Session usage, can be `chat` or `workflow`; if not provided, `chat`. `workflow` Applies only to system workflow agents.
`visibility`	string	No	Session visibility. This interface only accepts `visible`; when not provided, `visible`.
`pinned`	boolean	No	Whether to pin the conversation to the top.

The workspace_id, user_id, agent display name and avatar in the request are determined by the server based on the current identity, path and agent data, and do not need to be passed in. This interface does not accept hidden sessions, nor does it accept parent_conversation_id.

Successful response¶

Returns 201 on success. data is a newly created session; save data.id, which is used to read, update sessions and query saved messages.

{
  "code": 0,
  "data": {
    "id": "conv_01",
    "workspace_id": "ws_01",
    "agent_workspace_id": "ws_01",
    "agent_id": "agent_01",
    "agent_summary": {
      "id": "agent_01",
      "display_name": "销售分析助手",
      "available": true
    },
    "title": "销售分析",
    "status": "active",
    "purpose": "chat",
    "visibility": "visible",
    "pinned": false,
    "created_at": "2026-01-02T15:04:05Z",
    "updated_at": "2026-01-02T15:04:05Z"
  }
}

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.id`	string	Session ID.
`data.workspace_id`	string	ID of the workspace to which the session belongs.
`data.agent_workspace_id`	string	ID of the workspace to which the target agent belongs.
`data.agent_id`	string	Target agent ID.
`data.agent_summary`	object	Agent display summary; can contain `id`, `display_name`, `avatar_ref`, `status`, `available`, and `unavailable_reason`.
`data.title`	string	Session title; not returned if not set.
`data.status`	string	Current session status.
`data.purpose`	string	Current session usage.
`data.visibility`	string	Session visibility.
`data.pinned`	boolean	Whether to pin it to the top.
`data.head_message_id`	string	Recent message ID; does not return if there is no message yet.
`data.active_task_id`	string	Active task ID; not returned if there is no active task.
`data.last_message_at`	string	Last message time; does not return if there is no message yet.
`data.created_at`	string	Creation and last update times, in RFC 3339 format.
`data.updated_at`	string	Creation and last update times, in RFC 3339 format.

Error response¶

{
  "code": 2,
  "message": "请求参数无效",
  "details": {
    "cause": "invalid runtime conversation"
  }
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	The request body cannot be parsed, the agent workspace is not within the allowed range, or the session title, status, purpose, and visibility do not meet the requirements.	Check the request fields; do not pass in a hidden session or parent session ID.
`404`	`3`（`NOT_FOUND`）	The specified agent does not exist.	Check `agent_id` and the workspace to which the agent belongs.
`500`	`1`（`INTERNAL`）	The server cannot create a session or generate session display information.	Record the request time and error message and try again.
`503`	`15`（`UNAVAILABLE`）	Session service is temporarily unavailable.	Try again later.

Follow-up operations¶

Use Query session messages to read messages that have been written during runtime. To send messages, use the agent call interface.

Last updated on Sep 3, 2026