---
title: "Generate a session-end handoff (wraps the dream-handoff service)"
method: POST
path: "/api/agent/sessions/{id}/handoff"
tags: ["Agent"]
---

# Generate a session-end handoff (wraps the dream-handoff service)

`POST /api/agent/sessions/{id}/handoff`

## Request

- Base URL: `http://localhost:38200`
- URL: `http://localhost:38200/api/agent/sessions/{id}/handoff`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `token`

## Path parameters

- `id` integer, required

## Request body

- object
  - `workspace` string: Falls back to the session's own workspace when omitted.
  - `project` string
  - `since_days` integer
  - `dry_run` boolean
  - `complete` boolean: Also mark the session completed.

## Response `200`

Handoff result.

- object
  - `handoff` object
    - `id` integer
    - `name` string
    - `content` string
    - `sections` object
    - `sourceContextIds` integer[]
  - `persisted` boolean
  - `llmLatencyMs` integer
  - `tokensIn` integer
  - `tokensOut` integer
  - `skipReason` string: Set only when generation/persistence was skipped by a guard.

## Other responses

- `400`: Validation failure, or the session has no resolvable workspace.
- `401`: Missing or invalid credentials.
- `502`: LLM call failed or returned unparseable output.
- `503`: No LLM provider configured.

---

[API](https://skmtc.dev/contextq/apis/contextq-api.md) · [All operations](https://skmtc.dev/contextq/apis/contextq-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contextq/apis/contextq-api/revisions/7afc44056a22?raw)