HTTP API

The CLI and the MCP tools are clients of this API. Anything they do, you can do with plain HTTP.

Basics

• Base URL: https://api.heyquilt.com. Bodies and answers are JSON.
• Send Authorization: Bearer <token>. The token is a person's sign-in (the one quilt login keeps in ~/.quilt/account.json) or an agent's qa_ access key. Hosted agents send Authorization: QuiltPass <pass>.
• <q> is a quilt's slug or id. <s> is a square's id or its short handle, such as sq:77aa01bc. <rev> is any revision.
• A write that names expect_head is refused with head_moved if the square moved. Without it, the server uses the square's current head.
• Commits, merges, rebases, cherry-picks, resolves, folds and splits can be retried safely: the same call on the same square, with the same expect_head and body, within 24 hours gets the first answer again.

$ curl -s "https://api.heyquilt.com/v1/quilts/my-app/log?limit=1" \
    -H "Authorization: Bearer $QUILT_TOKEN"

Routes

Request bodies

Commit

Each change puts a file or deletes one. Put the bytes inline as base64 content, or name a blob you uploaded first with /have and /packs. mode is file (the default), exec or symlink. Paths under .quilt/ are refused.

POST /v1/quilts/my-app/squares/sq:77aa01bc/commit
{
  "expect_head": "0c1d2e3f4a5b…",
  "message": "Rate limit the sign-in route",
  "changes": [
    { "path": "src/limits.js", "op": "put", "content": "ZXhwb3J0IGNvbnN0IExJTUlUID0gMTAK" },
    { "path": "src/old-limits.js", "op": "delete" }
  ]
}

Putting a conflicted file without its conflict tag line settles that conflict.

Merge into a line

POST /v1/quilts/my-app/lines/main/merge
{ "square": "sq:77aa01bc", "message": "Rate limit sign-in", "dry_run": false }

A merge answers { ok: true, merged: { line, patch_no, commit, seq }, retries, combined, fast, warnings, square }. A refused one answers 422 with refused, the square's new head and terms: each conflicted path, its kind and its sides. on_conflict: "leave" keeps the square as it was.

Resolve

choose is ours, theirs, base, suggestion, delete, a side number, or { "blob": "<id>" } for content you uploaded.

Answers

Every write answers with the server's record. A square, as GET /squares/<s> returns it:

{
  "id": "019a2b7e-5c40-7d21-8e3f-0d3e77aa01bc",
  "short": "sq:77aa01bc",
  "title": "Rate limit sign-in",
  "state": "open",
  "line": "main",
  "base": "4d5bb0f2aacd…",
  "head": "0c1d2e3f4a5b…",
  "holder": "agent:5c1e…",
  "opened_by": "agent:5c1e…",
  "writers": [],
  "behind_by": 1,
  "conflicted_paths": 0,
  "opened_at": 1761398000000,
  "updated_at": 1761399500000,
  "merged_under_you": [
    { "patch_no": 784, "commit": "5f4e3d2c1b0a…", "author": "person:7f3e…", "message": "Fix sign-in", "paths": ["src/auth.js"] }
  ],
  "would_conflict": [
    { "path": "src/auth.js", "kind": "content", "patch_no": 784, "author": "person:7f3e…" }
  ]
}

Times are milliseconds since 1970. behind_by counts the patches on the line since the square's base. A merged square adds merged; a folded one adds folded_into.

A commit, as POST /squares/<s>/commit returns it:

{
  "ok": true,
  "seq": 5121,
  "square": { "id": "019a2b7e-…", "short": "sq:77aa01bc", "state": "open", "head": "1e2f3a4b5c6d…", "…": "…" },
  "result": {
    "id": "1e2f3a4b5c6d…",
    "short": "1e2f3a4b5c6d",
    "seq": 5121,
    "square_id": "019a2b7e-…",
    "square": "sq:77aa01bc",
    "parents": ["0c1d2e3f4a5b…"],
    "author": { "member_id": "agent:5c1e…", "kind": "agent", "name": "builder", "tool": "claude" },
    "on_behalf_of": "person:7f3e…",
    "message": "Rate limit the sign-in route",
    "authored_at": 1761399600000,
    "at": 1761399600000,
    "conflicted": 0,
    "stack": {},
    "changes": [
      { "path": "src/limits.js", "op": "put", "blob": "8a7b6c5d…", "mode": "file", "size": 412 },
      { "path": "src/old-limits.js", "op": "delete" }
    ]
  }
}

A commit on a line also has patch: { line, patch_no }. In /log each commit has files (a count) in place of changes.

Errors

A refusal is { ok: false, error, code } with an HTTP status, plus fields that help, such as head or retry_after. The codes you will meet most:

Limits

• Each line takes at most 200 merges an hour, and each quilt 200 an hour across its lines. A red check halves a line's window, down to 5.
• A JSON body can be up to 96 MiB; a pack up to 65 MiB.