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. This page lists the routes.
Authenticate as described in Authentication. Errors use the shape in Errors, and list routes page as in 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
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. |
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://status.sailfork.com/api/orgs/fenil/caissons {
"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). |
422 | Bad body, or the branch is the default branch. |
List caissons
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.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
"https://status.sailfork.com/api/orgs/fenil/caissons?brief=live&repo=ocean-landing" Get a caisson
GET /api/orgs/{owner}/caissons/{id} Returns the caisson with its files, commits and session log. The response carries an ETag.
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
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.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
"https://status.sailfork.com/api/orgs/fenil/caissons/c-z4nwicj7/files/src/tide/math.rs?lines=10-12&numbered=true" Read many files
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
PUT /api/orgs/{owner}/caissons/{id}/files/{path} The body is the raw file bytes, at most 64 MiB. Needs repo:write.
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" --data-binary @math.rs \
https://status.sailfork.com/api/orgs/fenil/caissons/c-z4nwicj7/files/src/tide/math.rs { "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
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
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. |
curl -X PATCH -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"edits":[{"old":"tide_h","new":"tide_height","all":true}]}' \
https://status.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
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
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
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.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
"https://status.sailfork.com/api/orgs/fenil/caissons/c-z4nwicj7/grep?pattern=tide_h&literal=true&glob=*.rs" {
"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:
{
"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
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.
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://status.sailfork.com/api/orgs/fenil/caissons/c-z4nwicj7/batch Move a path
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
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
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.
Run code and syntax tools
Run a script
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.
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://status.sailfork.com/api/orgs/fenil/caissons/c-z4nwicj7/bash {
"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
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
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
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
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
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 for the repository versions.
Find symbols
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
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
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
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
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).
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"message":"Fix the tide math"}' \
https://status.sailfork.com/api/orgs/fenil/caissons/c-z4nwicj7/commit { "sha": "5e1d0c8a4b7f2936a0c1d58e9b34f7a6c2d1e0b9", "subject": "Fix the tide math", "author": "fenil", "agent": true, "at": "2026-11-10T18:04:12Z" } Open a pull request
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).
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 for the pull request itself.
Fork a caisson
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
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
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
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
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
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
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. |
Get the policy
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.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://status.sailfork.com/api/orgs/acme/caissons/policy {
"paths": [{ "pattern": "db/migrations/**", "rule": "ask", "why": "Migrations need a person.", "fixed": false }],
"maxLive": 10,
"idleMinutes": 60,
"requireReview": "off"
} Set the policy
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
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.