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.

  1. Use regular product identity credentials and a workspace for the target environment. Set BASE_URL to its full product API prefix. This endpoint rejects additional task-runtime authorization headers.

  2. Read a source conversation created by the current user and its messages. The source must have purpose=chat, status=active, and visibility=visible.

  3. Select a native assistant or agent message and provide its id. 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.

  4. Generate and retain REQUEST_ID for 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

workspace_id

Path

string

Yes

Workspace ID of the current user.

conversation_id

Path

string

Yes

Source conversation ID.

agent_id

Query

string

No

Restricts the agent of the source conversation.

agent_workspace_id

Query

string

No

Restricts the agent workspace to the current workspace or system. May occur only once; empty means the current workspace.

request_id

Body

string

Yes

Stable request ID for this fork, up to 128 bytes.

source_message_id

Body

string

Yes

Message ID of the selected answer, up to 128 bytes.

title

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

code

integer

0 on success; HTTP status is 201.

data.id

string

Server-generated child conversation ID. Success means the forked conversation has been published.

data.workspace_id

string

Workspace ID of the conversation.

data.agent_workspace_id

string

Workspace ID of the agent.

data.agent_id

string

Agent ID, the same as the source conversation.

data.agent_summary

object

Current display information and availability of the agent.

data.agent_summary.id

string

Agent ID.

data.agent_summary.workspace_id

string

Agent workspace ID; returned when present.

data.agent_summary.display_name

string

Agent name; returned when present.

data.agent_summary.avatar_ref

string

Avatar reference; returned when present.

data.agent_summary.status

string

Agent state; returned when present.

data.agent_summary.available

boolean

Whether the agent is currently available.

data.agent_summary.unavailable_reason

string

Unavailability reason; returned when present.

data.title

string

Child conversation title; returned when present.

data.title_user_edited

boolean

The fork title is marked edited and will not be overwritten by asynchronous title generation.

data.status

string

Conversation state; active for a new branch.

data.purpose

string

Conversation purpose; chat for a fork.

data.visibility

string

Conversation visibility; visible after successful publication.

data.parent_conversation_id

string

Source conversation ID.

data.source_message_id

string

Message ID of the selected source answer.

data.pinned

boolean

Whether pinned; false for a new branch.

data.head_message_id

string

ID of the last copied message in the child conversation.

data.active_task_id

string

Current task ID; returned when present. Forking itself creates no task.

data.latest_task_id

string

Most recent task ID; returned when present. A new branch does not inherit the source task ID.

data.latest_task_state

string

Most recent task state; returned when present.

data.last_message_at

string

Time of the last inherited message; returned when present.

data.created_at

string

Child conversation creation time in RFC 3339.

data.updated_at

string

Child conversation update time in RFC 3339.

Error response

{"code":"conversation_fork_role_changed","msg":"此分支操作由另一个角色发起。请切回发起时使用的角色,再重试以确认结果。"}

HTTP status

code

Conditions and recovery

400

conversation_fork_invalid

Invalid fork parameters or fork record. Check the request fields.

403

conversation_fork_forbidden

Current principal or Provider session identity does not satisfy fork requirements.

404

conversation_fork_not_found

Source conversation, selected message, or associated Provider object missing or outside read scope.

409

conversation_fork_not_ready

Selected task incomplete or corresponding Provider position not ready. Retain the original request identity when confirming results.

422

conversation_fork_unsupported

Forking is unsupported for this conversation purpose, message type, Provider position, or historical file reference.

409

conversation_fork_conflict

Same request ID with different content, or a fork conflict returned by the Provider.

409

conversation_fork_role_changed

Retry used a different effective role. Switch to the original role to confirm the result.

409

conversation_fork_pending

The same operation is still executing, competing for execution ownership, or waiting to resume. Retry with unchanged request content.

410

conversation_fork_aborted

Provider confirmed this fork was aborted. Use a new request ID if starting again.

429

conversation_fork_quota_exceeded

Insufficient Provider user session count, concurrent session count, or daily token quota. Resolve the quota before starting a new operation.

503

conversation_fork_unavailable

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.

Last updated on