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}.

ActionNeeds
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.

FieldTypeMeaning
idstringThe caisson id, such as c-z4nwicj7. Unique across owners.
repostringThe repository name inside the owner.
titlestring4 to 200 characters.
branchstringThe caisson's branch, caisson/<id> by default.
baseobject{ branch, sha }: what the caisson started from.
statestringediting, waiting, review, merged or stopped.
scopestring[]The paths it may write.
openedByobject{ via: "key", key, owner } for a token, or { via: "browser", person }.
pullobject or null{ repo, number } once a pull request is open.
askobject or null{ path, why } while a write is held.
refusedobject or nullA person refused the held write to path, and nothing has been written since.
stoppedstring or nullWhy it stopped.
forkedFromstringThe caisson this one was forked from, when it was.
canWritebooleanWhether you may write, stop and answer asks.
files, commits, sessionarraysChanges 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 fieldTypeNotes
repostring, requiredThe repository name inside {owner}.
titlestring, required4 to 200 characters.
scopestring[] or string, required1 to 50 entries. Each is "" (the whole repository), a file path, or a folder ending in /.
branchstring, optionalDefaults to caisson/<id>.
basestring, optionalA 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://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.

StatusMeaning
200Reused the live caisson already on the branch.
201Created.
409The repository already has its maximum of live caissons (see the policy).
422Bad body, or the branch is the default branch.

List caissons

GET /api/orgs/{owner}/caissons

Lists caissons of the owner, newest first.

QueryTypeNotes
repostringOnly this repository.
statestringOnly this state.
limitinteger1 to 200, default 30.
fullstring1 returns an array of whole caissons instead of a page of summaries.
cursorstringThe nextCursor of the previous page.
briefstringlive, 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://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.

QueryMeaning
linesSTART, START-END or START-, 1-based and inclusive. An END past the last line stops there; a START past it is 422.
head, tailThe first or last N lines. Use only one of lines, head and tail.
numberedtrue 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://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 fieldTypeNotes
pathsstring[], requiredUp to 100 files.
lines, head, tail, numberedoptionalThe 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://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.

StatusMeaning
200Applied.
202Held: the path matches an ask rule, the caisson moves to waiting, and the write lands only when a person approves.
403Outside the scope, or a never rule refuses it ({ error, rule }).
409The caisson is merged or stopped, or another write is already held.
412If-Match or If-None-Match failed: the path changed since you read it.
413Over 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 fieldTypeNotes
editsarray, requiredOne or more edits, below.
dryRunboolean, optionalWrites nothing and returns { path, oid, diff } with a unified diff ("" for none).

An edit is one of:

ShapeEffect
{ "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://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=
QueryNotes
patternRequired. * matches within a folder and ** across folders. A pattern with no / matches the file name in any folder.
pathLimit to a folder or file.
limit1 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.

QueryNotes
patternRequired. An empty or bad pattern is 422.
literaltrue searches plain text.
ignoreCasetrue ignores case.
modecontent (default), files or count.
glob, pathLimit by file glob or folder.
context, before, afterLines of context, at most 20 each. context sets both sides.
limitCounts 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://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 fieldTypeNotes
changesarray, requiredEach change is a path plus exactly one of the fields below.
dryRunboolean, optionalReturns what would change and writes nothing.
Change fieldMeaning
editsAn edit list, as for PATCH.
contentWrite the file with this text.
delete: trueDelete the file or folder.
moveToMove the file or folder to this path. Add overwrite: true to replace an existing destination.
restore: trueDrop 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://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 fieldTypeNotes
scriptstring, requiredAt most 64 KiB.
saveOnFailureboolean, optionalSave changes even when the exit code is not 0 or a limit stopped it.
dryRunboolean, optionalReport 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://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 fieldTypeNotes
patternstring, requiredThe ast-grep pattern.
languagestring, requiredrust, typescript, tsx, javascript, python or go.
path, globstring, optionalLimit by folder or file glob.
limitinteger, optional1 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 fieldTypeNotes
opstring, requiredstatus, definition, references, hover or diagnostics.
path, line, columnoptionaldefinition, references and hover need all three, with line and column from 1. diagnostics takes a path or a language.
languagestring, optionalrust, typescript, python or go.
limitinteger, optional1 to 2000, default 200.
waitinteger, optionalSeconds to wait for an answer, 0 to 50, default 10.
setup, vcpus, memoryMboptionalSandbox 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.

StatusMeaning
400The language has no server.
503no_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 }.

modeMeaning
selectiveOnly the listed steps need to run.
everythingRun everything. A lockfile, CI config, build root file, unowned file, non-source file or anything the graph cannot model selects this.
nothingNo test would run. This is never a pass.
unknownThe 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://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.

StatusMeaning
409The repository is at its live-caisson cap, or the fork family (stopped ones included) already has 24.
413The 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 fieldTypeNotes
headstring, requiredThe head of the packet you reviewed.
verdictstring, requiredapprove or changes.
summarystring, required@ is removed.
findingsarray, requiredEach 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.

StatusMeaning
409head is no longer the tree.
422An approve with a high or critical finding.
429After 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.

FieldTypeMeaning
pathsarrayRules { pattern, rule, why, fixed }. rule is ask (hold the write for a person) or never (refuse it). fixed rules are built in.
maxLiveintegerLive (editing, waiting, review) caissons allowed per repository.
idleMinutesintegerMinutes 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.
requireReviewstring, optionaloff (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://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.

Loading Sailfork