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

```text
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

```bash
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.

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

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

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - 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](list-session-messages.md) to read messages that have been written during runtime. To send messages, use the agent call interface.