---
title: "Create a handover and its first immutable revision"
method: POST
path: "/handovers"
---

# Create a handover and its first immutable revision

`POST /handovers`

## Request

- Base URL: `https://handover.sh/api/v1`
- URL: `https://handover.sh/api/v1/handovers`
- Auth: HTTP bearer

## Request body

- CreateHandover
  - `note` string
  - `brief` ContinuationBrief: An immutable, structured snapshot of what a person or agent needs to resume the work.
    - `objective` string
    - `currentState` string
    - `decisions` string[]
    - `openQuestions` string[]
    - `nextSteps` ContinuationStep[]
      - `id` string, required
      - `text` string, required
      - `status` 'open' | 'done', required
  - `artifactMode` 'merge' | 'replace'
  - `artifacts` ArtifactInput[]
    - `name` string, required
    - `mediaType` string
    - `content` string, required
    - `encoding` 'utf8' | 'base64'
  - `title` string, required
  - `summary` string

## Response `201`

Created handover

- HandoverEnvelope
  - `data` Handover, required
    - `id` string, required
    - `title` string, required
    - `summary` string
    - `status` 'active' | 'archived' | 'trashed', required
    - `visibility` 'workspace' | 'restricted', required
    - `deletedAt` string, date-time, nullable, required
    - `purgeAfter` string, date-time, nullable, required
    - `currentRevisionId` string, required
    - `currentRevision` object, required
    - `revisions` object[], required

## Other responses

- `400`: Request error

---

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