Drafts

A draft is a git branch with its own worktree. An agent can write a batch of changes there, you review the diff, and then merge it into main in one fast-forward or throw it away. Main stays untouched until the merge. Drafts are off by default. Turn them on in .kiwi/config.toml:

.kiwi/config.toml

[drafts]
enabled = true
max_active = 10   # default 10

When drafts are off, every endpoint on this page returns 501. All paths are relative to http://localhost:3333/api/kiwi. See Draft spaces for the workflow.

Create a draft

Branches from the current HEAD and returns the new draft. POST /drafts

string

Who owns the draft. Falls back to X-Actor, then api.

curl -X POST 'http://localhost:3333/api/kiwi/drafts' \
  -H "Content-Type: application/json" \
  -d '{"actor": "agent:planner"}'

string

Eight-character hex ID used in every other draft route.

string

Git branch, draft/{id}.

string

Owner.

string

Creation time (RFC 3339).

201 Created

{
  "id": "3fa9c21e",
  "branch": "draft/3fa9c21e",
  "actor": "agent:planner",
  "created_at": "2026-10-19T09:30:00Z"
}

Returns 409 when max_active drafts already exist or the repository has no commits yet.

List drafts

Returns all active drafts as an array of the same objects. GET /drafts

curl 'http://localhost:3333/api/kiwi/drafts'

Response

[
  {"id": "3fa9c21e", "branch": "draft/3fa9c21e", "actor": "agent:planner", "created_at": "2026-10-19T09:30:00Z"}
]

Get a draft

Returns one draft. GET /drafts/:id

string

required

Draft ID.

curl 'http://localhost:3333/api/kiwi/drafts/3fa9c21e'

Returns the draft object, or 404 if the ID is unknown.

Read a file in a draft

Returns a file’s content as it is in the draft, with an ETag header. GET /drafts/:id/file

string

required

Draft ID.

string

required

File path.

curl -i 'http://localhost:3333/api/kiwi/drafts/3fa9c21e/file?path=concepts/auth.md'

The body is text/markdown. Returns 404 if the draft or file does not exist.

Write a file in a draft

Creates or replaces a file on the draft branch. The body is the full file content. PUT /drafts/:id/file

string

required

Draft ID.

string

required

File path.

string

default:"draft-api"

Commit author on the draft branch.

curl -X PUT 'http://localhost:3333/api/kiwi/drafts/3fa9c21e/file?path=concepts/auth.md' \
  -H "X-Actor: agent:planner" \
  --data-binary @auth.md

Response

{"path": "concepts/auth.md", "etag": "c3d4e5f6..."}

Draft writes do not check If-Match. The merge is a plain git fast-forward, so review the diff before you merge.

Delete a file in a draft

Deletes a file on the draft branch. DELETE /drafts/:id/file

string

required

Draft ID.

string

required

File path.

string

default:"draft-api"

Commit author.

curl -X DELETE 'http://localhost:3333/api/kiwi/drafts/3fa9c21e/file?path=concepts/old.md'

Returns 204 with no body.

Get a draft’s tree

Returns the draft’s folder hierarchy, in the same shape as GET /tree. GET /drafts/:id/tree

string

required

Draft ID.

string

default:"/"

Folder to start from.

curl 'http://localhost:3333/api/kiwi/drafts/3fa9c21e/tree'

Diff a draft

Returns everything the draft changed since it branched from main, as a unified diff. GET /drafts/:id/diff

string

required

Draft ID.

curl 'http://localhost:3333/api/kiwi/drafts/3fa9c21e/diff'

Response

{"diff": "diff --git a/concepts/auth.md b/concepts/auth.md\n--- a/concepts/auth.md\n+++ b/concepts/auth.md\n@@ -1,3 +1,3 @@\n..."}

Merge a draft

Fast-forwards main to the draft branch, then removes the draft. Uncommitted files in the draft worktree are committed first. POST /drafts/:id/merge

string

required

Draft ID.

curl -X POST 'http://localhost:3333/api/kiwi/drafts/3fa9c21e/merge'

Response

{"status": "merged"}

Returns 409 when main has moved since the draft was created, because only fast-forward merges are allowed. Recreate the draft from the new HEAD, or apply the changes to main directly.

Discard a draft

Deletes the draft’s branch and worktree. Main is unchanged. DELETE /drafts/:id

string

required

Draft ID.

curl -X DELETE 'http://localhost:3333/api/kiwi/drafts/3fa9c21e'

Returns 204 with no body, or 404 if the ID is unknown.

Draft spaces

When to stage changes in a draft.

MCP tools

The kiwi_draft_* tools do the same from an agent.

REST API

CLI

Create a draft

List drafts

Get a draft

Read a file in a draft

Write a file in a draft

Delete a file in a draft

Get a draft’s tree

Diff a draft

Merge a draft

Discard a draft

Draft spaces

MCP tools

​Create a draft

​List drafts

​Get a draft

​Read a file in a draft

​Write a file in a draft

​Delete a file in a draft

​Get a draft’s tree

​Diff a draft

​Merge a draft

​Discard a draft

​Related

Draft spaces

MCP tools

Create a draft

List drafts

Get a draft

Read a file in a draft

Write a file in a draft

Delete a file in a draft

Get a draft’s tree

Diff a draft

Merge a draft

Discard a draft

Related