---
title: "Fork agent conversation from a message"
method: POST
path: "/agents/{agentKey}/conversations/{conversationId}/message/{messageId}/fork"
tags: ["Agents"]
---

# Fork agent conversation from a message

`POST /agents/{agentKey}/conversations/{conversationId}/message/{messageId}/fork`

## Request

- Base URL: `https://app.pipeshub.com/api/v1`
- URL: `https://app.pipeshub.com/api/v1/agents/{agentKey}/conversations/{conversationId}/message/{messageId}/fork`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `/api/v1/oauth2/authorize`
    - Client credentials
    - Token URL: `/api/v1/oauth2/token` scopes: `agent:execute`

Copy this agent conversation into a new private chat owned by the
caller, including every message up to and including `messageId`. The
original conversation is left unchanged.

Only the owner of the conversation can fork it; anyone else gets 404.

## Path parameters

- `agentKey` string, required
- `conversationId` string, objectId, required
- `messageId` string, objectId, required

## Response `201`

Forked conversation created

- ForkConversationResponse
  - `id` string, objectId, required: New conversation identifier
  - `title` string, required: Title of the forked conversation
  - `projectId` string, objectId: Project the fork is linked to. Present only when the source conversation belonged to a project that the caller can still view; otherwise omitted.
  - `forkedFrom` object, required
    - `conversationId` string, objectId, required
    - `messageId` string, objectId, required
  - `messageCount` integer, required: Number of messages copied into the new conversation
  - `meta` object, required
    - `requestId` string
    - `timestamp` string, date-time, required
    - `duration` integer, required: Server-side processing time in milliseconds

## Other responses

- `400`: Invalid conversation, message or agent id (`VALIDATION_ERROR`)
- `401`: Unauthorized
- `403`: Forbidden - token is missing the `agent:execute` scope
- `404`: `Conversation not found` when the conversation does not exist, is deleted, is not a conversation with this agent, or is not the caller's own (an archived one can be forked); `Message not found` when `messageId` is not a message of that conversation.
- `500`: Internal server error, for example when an artifact of the conversation could not be copied into the fork (`Could not copy <n> artifact(s) into the fork`); no fork is created then. A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.

## Changes

- **2026-10-28** `dbb5e203b445`: 5 info
  - added the media type `application/json` for the response with the status `400`
  - added the media type `application/json` for the response with the status `401`
  - added the media type `application/json` for the response with the status `404`
  - added the non-success response with the status `403`
  - …1 more
- **2026-10-21** `a90ab79f26a1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api/changes/agents/:agentKey/conversations/:conversationId/message/:messageId/fork/post.md)

---

[API](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api.md) - [All operations](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api/revisions/dbb5e203b445?raw)