# Caissons API

Open a caisson, read and edit its files, run searches and scripts, commit, open a pull request and handle review, all over REST.

A caisson is a working copy that stays on the server. Writes become blobs that sit over the base commit until you commit them to the caisson's branch. For the concepts, scope, held writes and the CLI, read [Caissons](https://sailfork.com/docs/caissons). This page lists the routes.

Authenticate as described in [Authentication](https://sailfork.com/docs/api#authentication). Errors use the shape in [Errors](https://sailfork.com/docs/api#errors), and list routes page as in [Paging](https://sailfork.com/docs/api#paging).

## Access rules

Every route below is under `/api/orgs/{owner}/caissons`, where `{owner}` is the user or organization that owns the repository, except `GET /api/caissons/{id}`.

| Action | Needs |
| --- | --- |
| Reads (list, get, files, tree, glob, grep, symbols, diff, affected, review packet and status) | Read access to the repository, and the `repo:read` scope for a token. Signed-out callers can read caissons of a public repository. |
| Writes (open, write, batch, move, restore, commit, pull, fork, stop, bash, review, save) | Push access to the repository, and `repo:write`. |
| Language server (`lsp`, `lsp/rename`, `lsp/stop`) | The `sandbox` scope too, since a sandbox runs the server. |
| Answer a held write (`ask`) | A person in the browser. An access token gets 403. |

A private repository you cannot read answers 404 on every route. A token limited to other repositories gets 404 as well. A caisson that is merged or stopped refuses writes with 409.

## The caisson object

Most routes that change state return a caisson. These are the fields that matter.

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | string | The caisson id, such as `c-z4nwicj7`. Unique across owners. |
| `repo` | string | The repository name inside the owner. |
| `title` | string | 4 to 200 characters. |
| `branch` | string | The caisson's branch, `caisson/<id>` by default. |
| `base` | object | `{ branch, sha }`: what the caisson started from. |
| `state` | string | `editing`, `waiting`, `review`, `merged` or `stopped`. |
| `scope` | string[] | The paths it may write. |
| `openedBy` | object | `{ via: "key", key, owner }` for a token, or `{ via: "browser", person }`. |
| `pull` | object or null | `{ repo, number }` once a pull request is open. |
| `ask` | object or null | `{ path, why }` while a write is held. |
| `refused` | object or null | A person refused the held write to `path`, and nothing has been written since. |
| `stopped` | string or null | Why it stopped. |
| `forkedFrom` | string | The caisson this one was forked from, when it was. |
| `canWrite` | boolean | Whether you may write, stop and answer asks. |
| `files`, `commits`, `session` | arrays | Changes against `base.sha`, commits on the branch, and the session log. Left out of summaries. |

A summary is a caisson without `files`, `commits` and `session`.

## Open and list

### Open a caisson

```http
POST /api/orgs/{owner}/caissons
```

Opens a caisson on a repository. Needs `repo:write`.

| Body field | Type | Notes |
| --- | --- | --- |
| `repo` | string, required | The repository name inside `{owner}`. |
| `title` | string, required | 4 to 200 characters. |
| `scope` | string[] or string, required | 1 to 50 entries. Each is `""` (the whole repository), a file path, or a folder ending in `/`. |
| `branch` | string, optional | Defaults to `caisson/<id>`. |
| `base` | string, optional | A branch name (default: the default branch) or a full commit sha. |

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"repo":"ocean-landing","title":"Fix the tide math","scope":["src/tide/"]}' \
  https://sailfork.com/api/orgs/fenil/caissons
```

```json
{
  "id": "c-z4nwicj7",
  "repo": "ocean-landing",
  "title": "Fix the tide math",
  "branch": "caisson/c-z4nwicj7",
  "base": { "branch": "main", "sha": "9f2c1ab5e0d3c47f8a61b2d9e5f0a7c4d3b2a190" },
  "state": "editing",
  "scope": ["src/tide/"],
  "pull": null,
  "ask": null,
  "canWrite": true
}
```

A branch that already exists is continued, and `attached` says what was reused. The route answers 200 with the live caisson already on that branch (its title and scope unchanged), or 201 with a new caisson whose `base.sha` is the branch's tip. A caisson that continues a branch never deletes it when it stops. A new caisson answers 201.

| Status | Meaning |
| --- | --- |
| `200` | Reused the live caisson already on the branch. |
| `201` | Created. |
| `409` | The repository already has its maximum of live caissons (see [the policy](#policy)). |
| `422` | Bad body, or the branch is the default branch. |

### List caissons

```http
GET /api/orgs/{owner}/caissons
```

Lists caissons of the owner, newest first.

| Query | Type | Notes |
| --- | --- | --- |
| `repo` | string | Only this repository. |
| `state` | string | Only this state. |
| `limit` | integer | 1 to 200, default 30. |
| `full` | string | `1` returns an array of whole caissons instead of a page of summaries. |
| `cursor` | string | The `nextCursor` of the previous page. |
| `brief` | string | `live`, `finished` or `all`. See below. |

The response is `{ items, nextCursor }` of summaries, 30 a page unless `limit` says otherwise. `full=1` returns the array of whole caissons instead (each with its diff, commits and session log), at most 200; one caisson's route has the same without the list.

`brief` returns what a list screen draws: summaries with `changes` (path, status, added, removed, `addedBytes`) and `reads` (the distinct paths a live caisson read), but no hunks, commits or session log. `live` is every live caisson (`editing`, `waiting`, `review`), `finished` is one page of the others, and `all` is both with live first. Brief responses carry an `ETag` and answer 304 while nothing changed. An unknown `brief` value is 422.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://sailfork.com/api/orgs/fenil/caissons?brief=live&repo=ocean-landing"
```

### Get a caisson

```http
GET /api/orgs/{owner}/caissons/{id}
```

Returns the caisson with its files, commits and session log. The response carries an `ETag`.

```http
GET /api/caissons/{id}
```

Returns the caisson by id alone, as a summary plus `owner`, the handle its other routes go under. Same read rules; 404 when unknown or not readable.

## Files

### Read a file

```http
GET /api/orgs/{owner}/caissons/{id}/files/{path}
```

Returns the file's bytes (`application/octet-stream`) as the working copy has them: the caisson's version, else the base tree's. The `ETag` is `"<blob oid>"`. Reads are recorded in the session log, except for merged and stopped caissons. 404 when the file is absent or deleted in the caisson.

| Query | Meaning |
| --- | --- |
| `lines` | `START`, `START-END` or `START-`, 1-based and inclusive. An `END` past the last line stops there; a `START` past it is 422. |
| `head`, `tail` | The first or last N lines. Use only one of `lines`, `head` and `tail`. |
| `numbered` | `true` prefixes each line like `cat -n`: the number right-aligned in six columns, then a tab. |

Every read sends `Sailfork-Lines: start-end/total`.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://sailfork.com/api/orgs/fenil/caissons/c-z4nwicj7/files/src/tide/math.rs?lines=10-12&numbered=true"
```

### Read many files

```http
POST /api/orgs/{owner}/caissons/{id}/read
```

| Body field | Type | Notes |
| --- | --- | --- |
| `paths` | string[], required | Up to 100 files. |
| `lines`, `head`, `tail`, `numbered` | optional | The same as for one file, applied to each. |

Returns `{ "files": [...] }`. Each entry is `{ path, oid, lines, text }`, where `lines` is `start-end/total`, or `{ path, error }` for a file that cannot be read (absent, binary, or a range past its end). The call still answers 200.

### Write a file

```http
PUT /api/orgs/{owner}/caissons/{id}/files/{path}
```

The body is the raw file bytes, at most 64 MiB. Needs `repo:write`.

```sh
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" --data-binary @math.rs \
  https://sailfork.com/api/orgs/fenil/caissons/c-z4nwicj7/files/src/tide/math.rs
```

```json
{ "path": "src/tide/math.rs", "oid": "3b18e512dba79e4c8300dd08aeb37f8e728b8dad", "size": 1204, "held": false }
```

Writes to one path are last write wins. Send `If-Match: "<oid>"` (the `ETag` of the version you read) to make the write a compare-and-swap, or `If-None-Match: *` to create only.

| Status | Meaning |
| --- | --- |
| `200` | Applied. |
| `202` | Held: the path matches an `ask` rule, the caisson moves to `waiting`, and the write lands only when a person approves. |
| `403` | Outside the scope, or a `never` rule refuses it (`{ error, rule }`). |
| `409` | The caisson is merged or stopped, or another write is already held. |
| `412` | `If-Match` or `If-None-Match` failed: the path changed since you read it. |
| `413` | Over 64 MiB. |

### Delete a file

```http
DELETE /api/orgs/{owner}/caissons/{id}/files/{path}
```

Deletes the file in the caisson. Returns the same `{ path, oid, size, held }` object with `oid` null, and the same statuses as a write.

### Edit a file

```http
PATCH /api/orgs/{owner}/caissons/{id}/files/{path}
```

Applies edits in order on the server and writes the result as a PUT does.

| Body field | Type | Notes |
| --- | --- | --- |
| `edits` | array, required | One or more edits, below. |
| `dryRun` | boolean, optional | Writes nothing and returns `{ path, oid, diff }` with a unified diff (`""` for none). |

An edit is one of:

| Shape | Effect |
| --- | --- |
| `{ "old": "...", "new": "...", "all"?: true }` | Replace exact text. Exactly one match unless `all` is true. |
| `{ "regex": "...", "new": "...", "all"?: true }` | Replace a regex match. `$1` and `${name}` work in `new`, and `^` and `$` match at line ends. |
| `{ "insertAfter": 12, "text": "..." }` | Insert lines after line 12 (`0` is the top). A newline is added when `text` lacks one. |

```sh
curl -X PATCH -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"edits":[{"old":"tide_h","new":"tide_height","all":true}]}' \
  https://sailfork.com/api/orgs/fenil/caissons/c-z4nwicj7/files/src/tide/math.rs
```

Statuses are those of a write, plus: 409 when a replacement matches nothing, matches more than once without `all`, or `insertAfter` is past the end (the message names the edit, counting from 1); 422 for no edits, a bad edit or regex, or a file that is not UTF-8; 412 when the file changed while applying.

### List the tree

```http
GET /api/orgs/{owner}/caissons/{id}/tree
GET /api/orgs/{owner}/caissons/{id}/tree/{path}
```

Lists one folder of the working copy (base merged with the caisson's changes), the root when there is no path. Returns `{ path, entries }`. Each entry is `{ name, path, dir, size, oid, changed }`. `size` is bytes for files the caisson wrote and null for unchanged files and folders, `oid` is null for folders, and `changed` is `added`, `modified` or null. Folders come first, then names.

### Find files by glob

```http
GET /api/orgs/{owner}/caissons/{id}/glob?pattern=
```

| Query | Notes |
| --- | --- |
| `pattern` | Required. `*` matches within a folder and `**` across folders. A pattern with no `/` matches the file name in any folder. |
| `path` | Limit to a folder or file. |
| `limit` | 1 to 2000, default 200. |

Returns `{ paths, truncated }`. A bad glob is 422.

### Search file contents

```http
GET /api/orgs/{owner}/caissons/{id}/grep?pattern=
```

Searches working-copy files line by line with a Rust `regex`.

| Query | Notes |
| --- | --- |
| `pattern` | Required. An empty or bad pattern is 422. |
| `literal` | `true` searches plain text. |
| `ignoreCase` | `true` ignores case. |
| `mode` | `content` (default), `files` or `count`. |
| `glob`, `path` | Limit by file glob or folder. |
| `context`, `before`, `after` | Lines of context, at most 20 each. `context` sets both sides. |
| `limit` | Counts matches, files or counts by mode. 1 to 2000, default 200. |

Returns `{ mode, matches, files, counts, searched, skipped, truncated }`, where only the field for the chosen mode is set. A match is `{ path, line, text, before, after }`. Binary files and files over 16 MiB are listed in `skipped`.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://sailfork.com/api/orgs/fenil/caissons/c-z4nwicj7/grep?pattern=tide_h&literal=true&glob=*.rs"
```

```json
{
  "mode": "content",
  "matches": [
    { "path": "src/tide/math.rs", "line": 14, "text": "let h = tide_h(t);", "before": [], "after": [] }
  ],
  "searched": 42,
  "skipped": [],
  "truncated": false
}
```

## Batch changes

These routes apply changes in order and land them together in one transaction, or not at all. Every touched path is checked against the scope and the path rules first: 403 `{ error, rule }` for a `never` rule, and 409 for a path under an `ask` rule, which must be written alone so it can be held. A 409 for a failed change names it, counting from 1. A 412 means a touched file changed while the batch was prepared. A retry that changes nothing answers 200 with no changes. Agent changes are metered once per changed path. All of them need `repo:write`.

They all return a batch result:

```json
{
  "dryRun": false,
  "changes": [
    { "path": "src/tide/math.rs", "action": "edited", "oid": "3b18e512dba79e4c8300dd08aeb37f8e728b8dad", "size": 1204, "diff": "--- a/src/tide/math.rs\n+++ b/src/tide/math.rs\n..." }
  ]
}
```

`changes` is sorted by path. `action` is `edited`, `written`, `deleted`, `moved`, `restored` or `withdrawn`; `from` is set for `moved`, and `oid` is null once deleted.

### Apply a batch

```http
POST /api/orgs/{owner}/caissons/{id}/batch
```

| Body field | Type | Notes |
| --- | --- | --- |
| `changes` | array, required | Each change is a `path` plus exactly one of the fields below. |
| `dryRun` | boolean, optional | Returns what would change and writes nothing. |

| Change field | Meaning |
| --- | --- |
| `edits` | An edit list, as for PATCH. |
| `content` | Write the file with this text. |
| `delete: true` | Delete the file or folder. |
| `moveTo` | Move the file or folder to this path. Add `overwrite: true` to replace an existing destination. |
| `restore: true` | Drop the uncommitted changes under the path (a file, a folder, or `""` for everything). |

Restoring the path of a held write, alone in its call, withdraws it: the caisson leaves `waiting` and the action is `withdrawn`. It is 422 when other changes ride along. A person still approves or refuses the write through the browser.

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"changes":[{"path":"src/tide/math.rs","edits":[{"old":"tide_h","new":"tide_height","all":true}]},{"path":"src/tide/old.rs","delete":true}]}' \
  https://sailfork.com/api/orgs/fenil/caissons/c-z4nwicj7/batch
```

### Move a path

```http
POST /api/orgs/{owner}/caissons/{id}/move
```

Body `{ from, to, overwrite?, dryRun? }`. Moves a file or a folder, whose files keep their place under `to`. 409 when a destination file exists and `overwrite` is not set. Same checks as a batch.

### Restore paths

```http
POST /api/orgs/{owner}/caissons/{id}/restore
```

Body `{ paths, dryRun? }`, where `paths` is a string array. Drops the uncommitted changes under each path, a file, a folder, or `""` for the whole caisson, back to the branch head. 409 when a path has none. Same checks as a batch.

### Save a sandbox's changes

```http
POST /api/orgs/{owner}/caissons/{id}/save-sandbox
```

Body `{ sandbox, dryRun? }`. Saves what commands changed in `/work` of a sandbox that started from this caisson, through a batch. New files that `.gitignore` covers, new files over 64 MiB, new files under common build folders and new symlinks are not saved. The result lists only the first two kinds in `skipped`. File modes are kept. 409 when the caisson changed after the code went into the sandbox. Needs `repo:write` and, per the contract, `sandbox`. See [Sandboxes API](https://sailfork.com/docs/api-sandboxes).

## Run code and syntax tools

### Run a script

```http
POST /api/orgs/{owner}/caissons/{id}/bash
```

Runs a simulated bash over the working copy at `/work`, with no Drydock host. Each script runs in its own confined process: no real programs, no network, no host files or environment. Needs `repo:write`.

| Body field | Type | Notes |
| --- | --- | --- |
| `script` | string, required | At most 64 KiB. |
| `saveOnFailure` | boolean, optional | Save changes even when the exit code is not 0 or a limit stopped it. |
| `dryRun` | boolean, optional | Report what would be saved. |

Writes stay in memory until the script ends, then go through a batch: all or nothing, with the same path rules. One change to a path that needs approval is held. A script killed by a signal or at the time limit never saves.

Limits: 30 seconds, 100,000 commands, 4 MiB per output stream, 256 MiB of memory, and 1 GiB read.

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"script":"sed -i s/tide_h/tide_height/g src/tide/math.rs && git diff --stat"}' \
  https://sailfork.com/api/orgs/fenil/caissons/c-z4nwicj7/bash
```

```json
{
  "exitCode": 0,
  "stdout": "",
  "stderr": "",
  "stdoutTruncated": false,
  "stderrTruncated": false,
  "limit": null,
  "dryRun": false,
  "saved": true,
  "changes": [{ "path": "src/tide/math.rs", "action": "edited", "oid": "3b18e512dba79e4c8300dd08aeb37f8e728b8dad", "size": 1204, "diff": "..." }],
  "skipped": []
}
```

The route answers 200 once the script has run, even when it failed or its changes were refused. Look at `exitCode` (124 for a limit, 128 plus the signal for a dead process, with `limit` naming the limit), `saved`, `notSaved` (why changes were not saved), `rule` (the rule that refused them) and `held` (a single change waiting for a person). `skipped` lists symlinks the script made. 429 when too many scripts run on the server or for that owner.

### Search by syntax

```http
POST /api/orgs/{owner}/caissons/{id}/ast-grep
```

Searches working-copy files of one language with an ast-grep pattern. `$A` captures one node, `$$$A` captures any number, and `$_` matches without capturing. Comments and strings never match. Needs read access.

| Body field | Type | Notes |
| --- | --- | --- |
| `pattern` | string, required | The ast-grep pattern. |
| `language` | string, required | `rust`, `typescript`, `tsx`, `javascript`, `python` or `go`. |
| `path`, `glob` | string, optional | Limit by folder or file glob. |
| `limit` | integer, optional | 1 to 2000, default 200. |

Returns `{ matches, skipped, truncated }`. A match is `{ path, line, endLine, text, captures }`, with `captures` keyed by metavariable name without the `$`. Files over 4 MiB or not UTF-8 are in `skipped`. `truncated` is true when the limit, 512 MiB of reading or 20 seconds stopped the search. A bad pattern or unsupported language is 422.

### Rewrite by syntax

```http
POST /api/orgs/{owner}/caissons/{id}/ast-grep/rewrite
```

Takes the same body as the search, without `limit`, plus `rewrite` (string, required) and `apply` (boolean). It replaces every outermost match, so a match inside another needs a second run. It is a dry run unless `apply` is true. Returns a batch result and follows the batch rules (403 for a refused path, 409 for one needing approval). 422 when the search hit its read or time limit, since the rewrite would be partial. Needs `repo:write`.

## Language server

The language server answers type-aware questions in a sandbox of yours. The first question starts it, and it ends 30 minutes after the last. All three routes need `repo:read` and `sandbox`. The caisson's latest code is delivered first.

### Ask the language server

```http
POST /api/orgs/{owner}/caissons/{id}/lsp
```

| Body field | Type | Notes |
| --- | --- | --- |
| `op` | string, required | `status`, `definition`, `references`, `hover` or `diagnostics`. |
| `path`, `line`, `column` | optional | `definition`, `references` and `hover` need all three, with line and column from 1. `diagnostics` takes a `path` or a `language`. |
| `language` | string, optional | `rust`, `typescript`, `python` or `go`. |
| `limit` | integer, optional | 1 to 2000, default 200. |
| `wait` | integer, optional | Seconds to wait for an answer, 0 to 50, default 10. |
| `setup`, `vcpus`, `memoryMb` | optional | Sandbox setup command and size. |

Returns `{ language, sandbox, state, progress, locations, hover, diagnostics, truncated }`, where only the field for the op is set. While `state` is `queued`, `starting`, `installing`, `setup` or `indexing` the server cannot answer yet. Ask again, and `progress` says how far along it is. When `state` is `ready`, the answer is in the response.

| Status | Meaning |
| --- | --- |
| `400` | The language has no server. |
| `503` | `no_host` when no Drydock host is available, or the language server failed. |

### Rename a symbol

```http
POST /api/orgs/{owner}/caissons/{id}/lsp/rename
```

Body `{ path, line, column, newName, dryRun?, language?, wait?, setup? }`. Asks the language server what to change and writes it through a batch: all or nothing, the same path rules, and a preview with `dryRun`. While the server cannot answer yet it returns the `lsp` shape instead. 409 when the caisson moved in the meantime. 400 when the rename would create, move or delete a file.

### Stop the language server

```http
POST /api/orgs/{owner}/caissons/{id}/lsp/stop
```

Body `{ language? }`. Ends your language server sandboxes on this caisson now. Returns `{ "stopped": ["rust"] }`.

## Symbols

Both routes read at the caisson's head with its uncommitted files laid over the index. A hit from an uncommitted file has `uncommitted: true`, and a write held for approval is not included. `ref` is the caisson's branch. They answer 422 past 2000 uncommitted files or 16 MiB of them. See [Search API](https://sailfork.com/docs/api-search) for the repository versions.

### Find symbols

```http
GET /api/orgs/{owner}/caissons/{id}/symbols?q=&kind=&path=&limit=
```

Returns `{ query, ref, symbols, truncated, indexing, tookMs }`. `indexing` is true while the index is still being built.

### Find references

```http
GET /api/orgs/{owner}/caissons/{id}/symbols/refs?name=&path=&limit=
```

Returns `{ name, ref, definitions, references, truncated, indexing, tookMs }`. A reference is `{ path, line, text }`.

## Diff and affected tests

### Get the diff

```http
GET /api/orgs/{owner}/caissons/{id}/diff
```

Returns an array of files, `{ path, status, from, hunks }`, with the caisson's commits and uncommitted changes against `base.sha`. `status` is `added`, `modified`, `renamed` or `deleted`. A hunk is `{ header, lines }`, and a line is `{ kind, old, new, text }` with `kind` of `add`, `del` or `ctx`.

### Get the affected tests

```http
GET /api/orgs/{owner}/caissons/{id}/affected
```

Says which tests the caisson's changes reach. Returns `{ mode, reason, changed, steps, skipped, unowned, script, summary }`.

| `mode` | Meaning |
| --- | --- |
| `selective` | Only the listed steps need to run. |
| `everything` | Run everything. A lockfile, CI config, build root file, unowned file, non-source file or anything the graph cannot model selects this. |
| `nothing` | No test would run. This is never a pass. |
| `unknown` | The repository has no Cargo or `package.json` graph. |

Each step is `{ kind, dir, targets, command }` with `kind` of `cargo` or `js`. `script` runs the steps in a shell.

## Commit, pull request, fork and stop

### Commit

```http
POST /api/orgs/{owner}/caissons/{id}/commit
```

Body `{ message }`. Builds the tree from the branch head plus the caisson's changes, writes the commit, moves the branch with a compare-and-swap and clears the changes. Returns the commit as `{ sha, subject, author, agent, at }`. 409 when there is nothing to commit, or the branch moved in the meantime (the changes are kept, so commit again to build on the new head).

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"message":"Fix the tide math"}' \
  https://sailfork.com/api/orgs/fenil/caissons/c-z4nwicj7/commit
```

```json
{ "sha": "5e1d0c8a4b7f2936a0c1d58e9b34f7a6c2d1e0b9", "subject": "Fix the tide math", "author": "fenil", "agent": true, "at": "2026-11-10T18:04:12Z" }
```

### Open a pull request

```http
POST /api/orgs/{owner}/caissons/{id}/pull
```

Opens a pull request from the branch into `base.branch`. Body, all optional: `title`, `body`, and `stopForks` (boolean). Returns the caisson in state `review` with `pull` set. It moves to `merged` when that pull request merges. 409 when nothing is committed, one is already open, or the review policy blocks it (see [Review](#review)).

`stopForks: true` also stops the other live caissons forked from the same origin that you opened and that have no pull request and no held write. Their branches are kept. `stoppedForks` lists the ids it stopped, and `skippedForks` lists the live ones left running. See [Pull requests API](https://sailfork.com/docs/api-pulls) for the pull request itself.

### Fork a caisson

```http
POST /api/orgs/{owner}/caissons/{id}/fork
```

Body `{ title? }`. Makes a new caisson on its own branch `caisson/<id>`, from the source's commit and with a copy of its uncommitted changes, the same scope and base, and `forkedFrom` set. The source may be stopped, merged, or itself a fork. You open it under your own push access. Returns 201, and `forked` says what was carried.

Changes under a path rule and a write held for a person are not carried.

| Status | Meaning |
| --- | --- |
| `409` | The repository is at its live-caisson cap, or the fork family (stopped ones included) already has 24. |
| `413` | The uncommitted changes to copy inline exceed 16 MiB. Commit first. |

### Stop a caisson

```http
POST /api/orgs/{owner}/caissons/{id}/stop
```

Body `{ reason?, deleteBranch? }`. Returns the caisson in state `stopped`. The branch is deleted when it has no commits beyond the base, and kept otherwise. `deleteBranch: true` deletes it unless a pull request was opened from it, and `false` keeps it even when empty. A branch the caisson attached to, one with a pull request and one a branch guard protects are kept either way. The response carries `branchDeleted`, true only when the branch was deleted, and `stopped` says the same.

### Answer a held write

```http
POST /api/orgs/{owner}/caissons/{id}/ask
```

Body `{ approve }`, a boolean. Approves or refuses the write held for a person, and returns the caisson. Only a person in the browser can answer. A call with an access token gets 403, so an agent cannot approve its own write. 409 when nothing is held.

## Review

Review is a packet for your own reviewer. The server has no model. The packet's `head` is the git tree id of the caisson's whole state (branch tip plus uncommitted changes), so a review names the exact code. Committing the reviewed changes keeps it, and any other edit changes it.

### Get the review packet

```http
GET /api/orgs/{owner}/caissons/{id}/review
```

Open to readers, signed out ones too on a public repository. Returns `{ caisson, repo, title, branch, base, pull, head, headSha, level, required, brief, changes, routes, risks, files }`. `level` is the policy's `requireReview`, and `risks` are areas the changes touch, each `{ id, prompt, evidence }` with `id` of `auth`, `tenant`, `migration`, `delete`, `spawn` or `input`. 409 when the caisson changes nothing.

### Submit a review

```http
POST /api/orgs/{owner}/caissons/{id}/review
```

Needs push access and `repo:write`.

| Body field | Type | Notes |
| --- | --- | --- |
| `head` | string, required | The `head` of the packet you reviewed. |
| `verdict` | string, required | `approve` or `changes`. |
| `summary` | string, required | `@` is removed. |
| `findings` | array, required | Each is `{ file, line, severity, scenario }`, with `severity` of `low`, `medium`, `high` or `critical`. `@` is removed from `scenario`. |

Returns the review: `{ id, head, headSha, reviewer, agent, via, selfReview, verdict, summary, findings, at, posted, postError }`. `selfReview` is true when the reviewer opened the caisson.

The review is posted on the pull request as one review comment listing the new findings, plus a thread on each of the first five high or critical ones. That happens at once when the pull request exists, and otherwise when it is opened. A failed post stays in `postError` and is retried by the next submit, resolve, pull request opening or status read by a writer.

| Status | Meaning |
| --- | --- |
| `409` | `head` is no longer the tree. |
| `422` | An `approve` with a high or critical finding. |
| `429` | After 10 reviews of one tree or 30 of one caisson. |

### Resolve a finding

```http
POST /api/orgs/{owner}/caissons/{id}/review/resolve
```

Body `{ finding, note }`, where `finding` is the finding's `id`. Needs push access. Clears a high or critical finding and returns it with `resolved: { by, note, selfResolved, at }`. 409 when there is no open finding with that id.

Under the `agent` level the opener's own clearing counts and is labeled self-resolved on the pull request. Under `independent` it does not, and another account's resolution replaces it.

### Get the review status

```http
GET /api/orgs/{owner}/caissons/{id}/review/status
```

Returns `{ level, head, reviews, blocked }` for the tree as it stands. `blocked` says why the caisson is not cleared under the owner's `requireReview`, or is null. It is blocked when there is no review (by another account under `independent`), or a high or critical finding nobody cleared. A clean re-review does not clear a finding.

`POST .../pull` answers 409 with that text, judged on the tree of the branch tip, so uncommitted changes cannot stand in for commits. A merge of a pull request from a caisson branch is refused unless its head tree has a review that meets the policy, however the pull request was opened.

## Policy

The policy sets the path rules, the live-caisson cap and the idle timeout.

| Field | Type | Meaning |
| --- | --- | --- |
| `paths` | array | Rules `{ pattern, rule, why, fixed }`. `rule` is `ask` (hold the write for a person) or `never` (refuse it). `fixed` rules are built in. |
| `maxLive` | integer | Live (`editing`, `waiting`, `review`) caissons allowed per repository. |
| `idleMinutes` | integer | Minutes without a write before an editing caisson stops, unless a sandbox of its code is queued or running. Its opener is told, with how many uncommitted changes were left and how to carry them on. A caisson waiting for a person to answer a held write is not stopped at this time: its approvers are reminded once at half of it, and it stops after 12 times it. |
| `requireReview` | string, optional | `off` (default), `agent` or `independent`. See [Review](#review). |

### Get the policy

```http
GET /api/orgs/{owner}/caissons/policy
```

Org members, or the person who owns `{owner}`, with `repo:read` or `org:read`. Anyone, signed out too, when `{owner}` has a public repository. Others get 404.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://sailfork.com/api/orgs/acme/caissons/policy
```

```json
{
  "paths": [{ "pattern": "db/migrations/**", "rule": "ask", "why": "Migrations need a person.", "fixed": false }],
  "maxLive": 10,
  "idleMinutes": 60,
  "requireReview": "off"
}
```

### Set the policy

```http
PUT /api/orgs/{owner}/caissons/policy
```

Body is the whole policy. Needs an organization owner, in the browser: a call with an access token gets 403. 422 when a fixed rule is removed or changed.

### Set the policy for your own repositories

```http
GET /api/settings/caissons
PUT /api/settings/caissons
```

Reads or replaces the policy that applies to repositories you own as a person, with the same body as above. Needs the `user` scope.

---

Every docs page: https://sailfork.com/llms.txt
