---
title: "Hand this session's context to another agent [write]"
method: POST
path: "/sessions/{id}/handoff"
tags: ["sessions"]
---

# Hand this session's context to another agent \[write\]

`POST /sessions/{id}/handoff`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/sessions/{id}/handoff`
- Auth: HTTP bearer

Accepted immediately; the move runs in the background. Poll the `status_url` in the response (also sent as the `Location` header) until `status` is terminal, then talk to `target_session`. `target_agent` is an agent id or a catalog `@handle`; `llm` and `reasoningEffort` choose the new session's model and thinking level. `last_message_id` bounds how much history is carried; omitted = all of it. The `Idempotency-Key` header is required and dedupes retries.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- RequestSessionHandoff
  - `target_agent` string, required: The agent to continue with: an agent id, or "@handle" for an agent from the catalog
  - `last_message_id` string
  - `llm` string: The new session's model; omitted = the target agent's model
  - `reasoningEffort` 'none' | 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra', nullable: The new session's thinking level; omitted or null = the target agent's

## Response `202`

Accepted — poll status_url

- object
  - `handoff` SessionHandoff, required: `resolved_mode` is how the move was actually made: `native_fork` when source and target share a harness and the pod's own state could be forked, else `summary` — a written handover the target reads as history, never as instructions. `target_session` is null until the move completes.
    - `id` string, required: handoff_…
    - `source_session` string, nullable
    - `target_session` string, nullable
    - `last_message_id` string, nullable
    - `target_agent` string, nullable
    - `status` string, required: Lowercased HandoffStatus: pending · checkpointing · provisioning · restoring · completed · retry_wait · failed · cancelled. Terminal: completed, failed, cancelled.
    - `resolved_mode` 'native_fork' | 'summary', required
    - `resolution_reason` string, nullable
    - `hands` 'carry' | 'attach' | 'null', nullable: `carry` copies the source's workspace files into the new session's sandbox; `attach` keeps the source's sandbox under the new agent
    - `workspace_carried` boolean, nullable: For `carry`: whether the workspace files were copied. False when the source sandbox was too old to export them; the conversation still moved
    - `workspace_folder` string, nullable: For a Mac-synced chat its owner continued: where the folder the Mac stored was restored in the new session. Null otherwise
    - `checkpoint` object, nullable: What was carried across, without its content
      - `format` string, nullable
      - `format_version` string, nullable
      - `sha256` string, nullable
      - `size_bytes` integer, nullable
    - `summary` object, nullable: What was carried across, without its content
      - `format` string, nullable
      - `format_version` string, nullable
      - `sha256` string, nullable
      - `size_bytes` integer, nullable
    - `error` object, nullable
      - `code` string
      - `message` string
      - `retryable` boolean
    - `status_url` string, required: GET it to poll the move
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `completed_at` string, date-time, nullable

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 breaking, 6 info
  - added the new required `header` request parameter `Idempotency-Key`
  - added the new optional request property `llm`
  - added the new optional request property `reasoningEffort`
  - added the optional property `error/request_id` to the response with the `default` status
  - …3 more

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/sessions/:id/handoff/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)