Drafts

Create, edit, merge, or discard git-backed draft workspaces under /api/kiwi/drafts.

All paths below are under http://localhost:3333/api/kiwi unless you use multi-space URLs or the X-Kiwi-Space header.

Drafts return 501 Not Implemented when the server was started without a draft manager.

Create draft

POST /drafts

Optional JSON body:

{ "actor": "agent:planner" }

If actor is empty, the server uses X-Actor, then falls back to api.

Response 201: { "id", "branch", "actor", "created_at" }

List drafts

GET /drafts

Returns a JSON array of draft summaries (same fields as create).

Get draft

GET /drafts/:id

Diff draft against main

GET /drafts/:id/diff

Returns { "diff": "<unified diff text>" }.

Merge or discard

POST /drafts/:id/merge

Returns { "status": "merged" }. Conflicts return 409.

DELETE /drafts/:id

Returns 204 on success.

Files inside a draft

Method	Path	Notes
GET	/drafts/:id/file?path=...	Raw markdown body; ETag header set.
PUT	/drafts/:id/file?path=...	Body is markdown; uses X-Actor (default draft-api). Returns { "path", "etag" }.
DELETE	/drafts/:id/file?path=...	Deletes file inside the draft branch. 204.
GET	/drafts/:id/tree?path=	Same tree shape as GET /tree; omit path for root.

MCP parity

Use the kiwi_draft_* tools from MCP for the same operations from Claude, Cursor, or other MCP clients.