Fork a session
POST/v1/projects/:project_id/sessions/:session_id/fork
Branches a new session from a point in this session's history: same context, different continuation.
The fork gets its own conversation whose messages reference the same documents as the parent rather than copying them, so there is one stored copy of the content and a retention purge erases it from both. Recorded tool results ride along on those messages and are replayed as model input on the fork's next turn — forking never re-invokes a tool, so exploring a "what if" cannot send an email or charge a card a second time. The consequence to accept is that a forked turn sees the tool data as it was, not as it is now.
The fork is created inert: auto_generate is false and no generation is triggered. Drive it with the normal message and generate endpoints. The fork has no actor — attach one only if the branch is meant to be driven by the same end user, since single_session_per_actor agents allow one open session per actor.
Request
Responses
- 201
- 400
- 401
- 403
- 404
- 413
- 429
- 500
- 502
- 4XX
Fork created
fork_at_position names no message in the parent conversation, or agent_id is unknown or belongs to another project
Missing or invalid credentials.
The credential is scoped to a different project, or the caller's role in the project does not carry this action.
The resource does not exist (existence is not leaked).
REQUEST_REJECTED — the request body is over the size the body parser accepts
QUOTA_EXCEEDED — a requests quota on the calling API key or its project is spent for the window; Retry-After says when it reopens
Response Headers
Seconds until the quota window admits a request again
Unexpected server error — INTERNAL_ERROR, with the raw message never forwarded
The deployment's admission service is asked about this write and did not answer — ADMISSION_UNAVAILABLE; the write did not happen
The deployment's admission service refused this write — answered under the service's own 4xx status, with its code (matching ^[A-Za-z_][A-Za-z0-9_]{0,63}$, not necessarily an ERROR_CODES key), message and meta; the write did not happen. A status this operation also declares on its own is documented there