---
title: "Create Worktree"
method: POST
path: "/projects/{project_id}/worktrees"
---

# Create Worktree

`POST /projects/{project_id}/worktrees`

## Request

- Base URL: `https://usemeridian.us` (the document declares no server; this is the origin it was published from)
- URL: `https://usemeridian.us/projects/{project_id}/worktrees`
- Auth: none declared

Register a git worktree for a session. Call after `git worktree add`.

eb2e44f8 — when the caller also supplies ``base_sha`` + ``base_branch``,
this additionally persists an IMMUTABLE base manifest for the worktree
(repo identity, base branch, base SHA, owning sprint item), returned
under the ``manifest`` key. That manifest is what
``meridian.worktree_merge_guard.validate_worktree_merge`` checks against
later, before a merge/completion is allowed to proceed. Omitting
base_sha/base_branch skips manifest creation entirely — backward
compatible with callers that only register session/branch/path; no
retroactive validation is imposed on worktrees that never opted in.

## Path parameters

- `project_id` string, required

## Request body

- WorktreeCreate: Body for POST /projects/{id}/worktrees.
  - `session_id` string, required: Session that owns this worktree.
  - `branch` string, required: Git branch name, e.g. worktree/abc12345.
  - `path` string, required: Filesystem path of the worktree.
  - `item_id` string, nullable: Sprint item this worktree was created for.
  - `pid` integer, nullable: eb2e44f8 — OS PID of the process that created this worktree. Used by the cleanup guard to confirm no live process is still using the directory before it is removed from disk.
  - `base_sha` string, nullable: eb2e44f8 — commit SHA the worktree was branched from. Supplying this together with base_branch persists an IMMUTABLE base manifest for the worktree, later checked before merge/completion is allowed to proceed. Omitting it skips manifest creation entirely (backward compatible).
  - `base_branch` string, nullable: eb2e44f8 — branch the worktree was branched from, e.g. 'dev'.
  - `repo_identity` string, nullable: eb2e44f8 — stable identity for the repo this worktree belongs to (e.g. a remote URL or repo name). Free-form; recorded on the base manifest for audit purposes only, never validated against disk. Defaults to project_id when omitted.

## Response `201`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/usemeridian/apis/meridian.md) · [All operations](https://skmtc.dev/usemeridian/apis/meridian/llms.txt) · [OpenAPI document](https://skmtc.dev/usemeridian/apis/meridian/revisions/f37a894bd374?raw)