Fork a conversation from an answer¶
Create a child conversation from a completed answer in the source conversation. The child retains conversation content leading to that answer and continues with an independent Provider session.
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/conversations/{conversation_id}/forks
Before you call this API¶
BASE_URL uses the product API prefix https://api.moi.matrixorigin.cn/v5. For a dedicated deployment, use its corresponding product API address.
Use regular product identity credentials and a workspace for the target environment. Set
BASE_URLto its full product API prefix. This endpoint rejects additional task-runtime authorization headers.Read a source conversation created by the current user and its messages. The source must have
purpose=chat,status=active, andvisibility=visible.Select a native
assistantoragentmessage and provide itsid. It must reference a completed Astra task in the same conversation and agent and have a Provider session record matching the current user and workspace.Generate and retain
REQUEST_IDfor this fork. If the outcome is unknown, retain the original request ID, source conversation, source message, title, and effective role used when starting it.
Messages inherited from an existing branch have source_message_id and cannot directly serve as a new fork point. Select a native answer subsequently generated in that branch. Other later tasks still running in the source conversation do not prevent forking the selected completed answer.
Request¶
Prepare WORKSPACE_ID, CONVERSATION_ID, SOURCE_MESSAGE_ID, and the saved REQUEST_ID. This request creates a child conversation but submits no new conversation task.
jq -n \
--arg request_id "$REQUEST_ID" \
--arg source_message_id "$SOURCE_MESSAGE_ID" \
'{request_id: $request_id, source_message_id: $source_message_id}' > fork-request.json
curl --request POST \
"$BASE_URL/workspaces/$WORKSPACE_ID/conversations/$CONVERSATION_ID/forks" \
--header "X-API-Key: $MOI_KEY" \
--header "X-Workspace-ID: $WORKSPACE_ID" \
--header "Content-Type: application/json" \
--data-binary @fork-request.json
Save the child conversation data.id from the success response. Check the parent conversation, source message, and inherited content through conversation details and message lists, then continue with the child conversation ID.
Parameter |
Location |
Type |
Required |
Description |
|---|---|---|---|---|
|
Path |
string |
Yes |
Workspace ID of the current user. |
|
Path |
string |
Yes |
Source conversation ID. |
|
Query |
string |
No |
Restricts the agent of the source conversation. |
|
Query |
string |
No |
Restricts the agent workspace to the current workspace or |
|
Body |
string |
Yes |
Stable request ID for this fork, up to 128 bytes. |
|
Body |
string |
Yes |
Message ID of the selected answer, up to 128 bytes. |
|
Body |
string |
No |
Child conversation title: valid UTF-8, up to 256 Unicode code points. |
request_id and source_message_id cannot be empty, . or .., contain /, \, or control characters, or have leading/trailing whitespace.
When agent_workspace_id is omitted and agent_id is specified, the agent workspace defaults to the path workspace. title is trimmed. If omitted, empty, or whitespace-only, a numbered title is generated from the source conversation title. Both omitted and null title bind to an empty string under the current string binding.
Forking copies the selected answer’s ancestor branch, including the answer itself. Other regenerated answer versions and their subsequent messages are not copied merely because their timestamps are earlier. Child messages receive new IDs and identify their source through source_message_id. Inherited messages do not retain source task or execution-manifest identities. File references in display content remain references; this does not copy all physical files or grant new file privileges.
Within a workspace and user, the request ID identifies the same fork operation. Keep the source conversation, source message, title, and original effective role unchanged when confirming results. Reusing a request ID with different content conflicts; changing only the effective role returns a role-change error. The request ID is not a caller-specified child conversation ID.
Successful response¶
{
"code": 0,
"data": {
"id": "7d694ce0-e9e6-5e16-b7aa-ef0ecbe261d5",
"workspace_id": "workspace-example",
"agent_workspace_id": "workspace-example",
"agent_id": "agent-example",
"agent_summary": {
"id": "agent-example",
"workspace_id": "workspace-example",
"display_name": "知识问答",
"status": "active",
"available": true
},
"title": "数据分析(2)",
"title_user_edited": true,
"status": "active",
"purpose": "chat",
"visibility": "visible",
"parent_conversation_id": "conversation-example",
"source_message_id": "assistant-example",
"pinned": false,
"head_message_id": "child-message-example",
"last_message_at": "2026-11-12T01:00:00Z",
"created_at": "2026-11-12T02:00:00Z",
"updated_at": "2026-11-12T02:00:00Z"
}
}
Field |
Type |
Description |
|---|---|---|
|
integer |
|
|
string |
Server-generated child conversation ID. Success means the forked conversation has been published. |
|
string |
Workspace ID of the conversation. |
|
string |
Workspace ID of the agent. |
|
string |
Agent ID, the same as the source conversation. |
|
object |
Current display information and availability of the agent. |
|
string |
Agent ID. |
|
string |
Agent workspace ID; returned when present. |
|
string |
Agent name; returned when present. |
|
string |
Avatar reference; returned when present. |
|
string |
Agent state; returned when present. |
|
boolean |
Whether the agent is currently available. |
|
string |
Unavailability reason; returned when present. |
|
string |
Child conversation title; returned when present. |
|
boolean |
The fork title is marked edited and will not be overwritten by asynchronous title generation. |
|
string |
Conversation state; |
|
string |
Conversation purpose; |
|
string |
Conversation visibility; |
|
string |
Source conversation ID. |
|
string |
Message ID of the selected source answer. |
|
boolean |
Whether pinned; |
|
string |
ID of the last copied message in the child conversation. |
|
string |
Current task ID; returned when present. Forking itself creates no task. |
|
string |
Most recent task ID; returned when present. A new branch does not inherit the source task ID. |
|
string |
Most recent task state; returned when present. |
|
string |
Time of the last inherited message; returned when present. |
|
string |
Child conversation creation time in RFC 3339. |
|
string |
Child conversation update time in RFC 3339. |
Error response¶
{"code":"conversation_fork_role_changed","msg":"此分支操作由另一个角色发起。请切回发起时使用的角色,再重试以确认结果。"}
HTTP status |
|
Conditions and recovery |
|---|---|---|
400 |
|
Invalid fork parameters or fork record. Check the request fields. |
403 |
|
Current principal or Provider session identity does not satisfy fork requirements. |
404 |
|
Source conversation, selected message, or associated Provider object missing or outside read scope. |
409 |
|
Selected task incomplete or corresponding Provider position not ready. Retain the original request identity when confirming results. |
422 |
|
Forking is unsupported for this conversation purpose, message type, Provider position, or historical file reference. |
409 |
|
Same request ID with different content, or a fork conflict returned by the Provider. |
409 |
|
Retry used a different effective role. Switch to the original role to confirm the result. |
409 |
|
The same operation is still executing, competing for execution ownership, or waiting to resume. Retry with unchanged request content. |
410 |
|
Provider confirmed this fork was aborted. Use a new request ID if starting again. |
429 |
|
Insufficient Provider user session count, concurrent session count, or daily token quota. Resolve the quota before starting a new operation. |
503 |
|
Dependency, storage, or response-confirmation failure; the operation may already have taken effect. Retain original request content to confirm the result. |
Authentication, path/query validation, and workspace admission may return general errors before fork validation. Error msg is localized according to request language; programs should read code.
Timeouts, disconnections, and 503 do not prove no branch was created. The system retains operations with unconfirmed results and attempts recovery. Recovery revalidates admission with the initiating user and effective role. Until results are confirmed, do not repeat the same fork with a new request ID or treat closing the page as cancellation.