Skip to content

SDK reference

Every method in the TypeScript and Python SDKs, the token scope it needs and what it does, read from the spec the SDKs are generated from.

Each method is listed by its full name on the client, as in sf.pulls.merge(). On a handle, leave out the ids it binds: sf.repo('acme/api').pulls.merge({ number: 7 }), or repo.pull(7).merge(). Installing and signing in are on SDKs for TypeScript and Python. The inputs and answers of each method are typed in the package, and match the REST route of the same name in the OpenAPI spec.

"Can be held for a person" marks a write an organization's agent permissions can hold; the method then returns the request and its approval address instead of the result.

caissons

TypeScriptPythonScopeWhat it does
caissons.affected()caissons.affected()repo:readName the test and build steps a caisson's changes affect, so a run covers only what could have broken.
caissons.astGrep()caissons.ast_grep()repo:readSearch a caisson's files, with its uncommitted edits applied, by code structure with an ast-grep pattern: $A captures one node, $$$A any number, and comments and strings never match.
caissons.astRewrite()caissons.ast_rewrite()repo:writeRewrite every match of an ast-grep pattern in a caisson with a template, all or nothing, under the path rules.
caissons.bash()caissons.bash()repo:writeRun a shell script in a sandbox over the caisson's working copy.
caissons.batch()caissons.batch()repo:writeApply a list of changes to a caisson's files all together or not at all: edits, whole-file writes, deletes, moves and restores.
caissons.commit()caissons.commit()repo:writeCommit a caisson's uncommitted changes to its branch.
caissons.diff()caissons.diff()repo:readShow what a caisson changes, file by file, as a diff against its base.
caissons.fork()caissons.fork()repo:writeFork a caisson: a new caisson on its own branch that starts from the caisson's current files, so two approaches can be tried at once.
caissons.get()caissons.get()repo:readShow a caisson with its diff, commits and session log.
caissons.glob()caissons.glob()repo:readList the files of a caisson, with its uncommitted edits applied, that match a glob.
caissons.grep()caissons.grep()repo:readSearch the files of a caisson, with its uncommitted edits applied, for a regular expression.
caissons.list()caissons.list()repo:readList an owner's caissons, newest first, across the repositories the caller may read.
caissons.locate()caissons.locate()repo:readFind a caisson by its id alone and learn which owner its other routes go under.
caissons.lsp()caissons.lsp()repo:readAsk the language server of a caisson's code, including its uncommitted edits, a question that needs types: definition, references, hover and diagnostics.
caissons.lspRename()caissons.lsp_rename()repo:writeRename the symbol at a position everywhere its type says it is used, all or nothing, under the path rules.
caissons.lspStop()caissons.lsp_stop()repo:readEnd the caller's language server sandboxes on a caisson now, instead of 30 minutes after the last question.
caissons.open()caissons.open()repo:writeOpen a caisson: a server-side worktree on a branch of a repository, limited to scope, that an agent reads and edits without a checkout.
caissons.patch()caissons.patch()repo:writeApply a unified diff to a caisson all together or not at all.
caissons.policy()caissons.policy()repo:read, org:readShow the rules writes through a caisson run under: path rules that hold a write for a person or refuse it, how many caissons may be live per repository, when an idle one stops, and the review a pull request waits for.
caissons.pull()caissons.pull()repo:writeOpen a pull request from a caisson's branch.
caissons.read()caissons.read()repo:readRead several files of a caisson in one call, with its uncommitted edits applied.
caissons.review()caissons.review()repo:readBuild the review packet for a caisson: the brief, the changed files, the routes they touch and the risks to check, with the git tree to pass to caissons.review_submit.
caissons.reviewResolve()caissons.review_resolve()repo:writeClear a review finding with a note.
caissons.reviewStatus()caissons.review_status()repo:readShow the review level a caisson's repository asks for, the reviews so far and what still blocks shipping.
caissons.reviewSubmit()caissons.review_submit()repo:writeRecord a review of the caisson's code as it stands: a verdict, a summary and the findings.
caissons.ship()caissons.ship()repo:writeCommit a caisson's pending changes and open its pull request in one call.
caissons.stop()caissons.stop()repo:writeStop a live caisson.
caissons.symbolRefs()caissons.symbol_refs()repo:readFind where a symbol is defined and every place that refers to it in a caisson's code.
caissons.symbols()caissons.symbols()repo:readFind the definitions of symbols (functions, types, constants) in a caisson's code by name, including the ones its uncommitted edits add.
caissons.test()caissons.test()sandboxRun a command in a throwaway sandbox that holds the caisson's code with its uncommitted edits, and answer how it ended.

check_runs

TypeScriptPythonScopeWhat it does
check_runs.create()check_runs.create()repo:writeReport a check run on a commit.
check_runs.get()check_runs.get()repo:readShow one check run.
check_runs.list()check_runs.list()repo:readList the check runs on a commit: the latest of each name and reporter, or every one.
check_runs.update()check_runs.update()repo:writeChange a check run: its status and conclusion, text, annotations or buttons.

ci

TypeScriptPythonScopeWhat it does
ci.approvePull()ci.approve_pull()repo:writeApprove running the workflows on a pull request from a contributor who cannot run them without a writer's say.
ci.artifacts()ci.artifacts()repo:readList the artifacts a run uploaded.
ci.cancel()ci.cancel()repo:writeCancel a run that has not finished.
ci.dispatch()ci.dispatch()sandboxStart a workflow by hand on a branch or tag.
ci.failures()ci.failures()repo:readShow why a run failed: each failed step's last log lines, the errors located in them and the failed test cases.
ci.logs()ci.logs()repo:readShow the first page of every step's log in a run, or of one job's steps.
ci.rerun()ci.rerun()sandboxRun a finished run again as a new run: all of it, only its failed jobs, or the named jobs.
ci.run()ci.run()repo:readShow one CI run with its jobs and steps and, unless logs is false, every step's log.
ci.runs()ci.runs()repo:readList a repository's CI runs, newest first.
ci.stepLog()ci.step_log()repo:readShow one step's log from line after, for reading on as the step runs.

env

TypeScriptPythonScopeWhat it does
env.chain()env.chain()repo:readThe owner's env device chain after an epoch, the device requests the caller may see, and the people the head still encrypts to who have lost access.
env.chain.append()env.chain.append()repo:writeAppend an entry, signed by an admin device of the head, to the owner's env device chain, with every file it re-encrypts in the same transaction.
env.devices.cancel()env.devices.cancel()repo:writeWithdraw a device request: the requester's own, or any for an admin.
env.devices.request()env.devices.request()repo:writeAsk to add this device to the owner's env device chain; an admin device approves it after comparing the approval code both show.
env.list()env.list()repo:readThe repository's env files at their current versions: key names, signed manifests and, with content, the age ciphertext.
env.log()env.log()repo:readAn env file's versions, newest first: key names, epoch, author and message, never content.
env.version()env.version()repo:readOne version of one env file with its ciphertext, such as the base of a merge.
env.write()env.write()repo:writeStore new versions of env files, all or none: each a manifest signed by a device the chain head grants, built on the file's current version, and its age ciphertext.

event_subscriptions

TypeScriptPythonScopeWhat it does
event_subscriptions.advance()event_subscriptions.advance()repo:readMove a subscription's cursor forward to an event id the reader has finished with.
event_subscriptions.create()event_subscriptions.create()repo:readSave an event filter under a name.
event_subscriptions.delete()event_subscriptions.delete()repo:readDelete an event subscription and its cursor.
event_subscriptions.get()event_subscriptions.get()repo:readOne event subscription, with its cursor.
event_subscriptions.list()event_subscriptions.list()repo:readList the caller's event subscriptions by name.

events

TypeScriptPythonScopeWhat it does
events.list()events.list()repo:readA page of the events the caller may read, oldest first.

github

TypeScriptPythonScopeWhat it does
github.installUrl()github.install_url()userThe URL that installs the Sailfork GitHub App on a GitHub account.
github.installationRepos()github.installation_repos()userList the repositories of one installation that the caller can see.
github.installations()github.installations()userList the GitHub App installations the caller can reach with their connected GitHub account.

held

TypeScriptPythonScopeWhat it does
held.get()held.get()any tokenRead one held agent request: the person whose token asked, or anyone who may decide it.
held.mine()held.mine()userList the agent requests held for the caller to decide, in every org they belong to or write in.
held.org()held.org()org:readList an org's held agent requests.

inbox

TypeScriptPythonScopeWhat it does
inbox.list()inbox.list()userWhat reached you while you were away, newest first: checks that finished on your pull requests, a write held for a person that still waits, a caisson that stopped while idle, issue news.
inbox.read()inbox.read()userMark inbox entries read once you handled them: pass entry ids, or tab (and owner) for every unread entry of it, or neither for every unread entry.

issues

TypeScriptPythonScopeWhat it does
issues.answer()issues.answer()repo:writeAnswer a question on an issue, replacing an earlier answer: choices are option labels (one for single, any for multi), text the free-text answer of a text question or an other answer.
issues.ask()issues.ask()repo:writeAsk a person a question on an issue and read the answer back later from the issue's context (asks).
issues.claim()issues.claim()repo:writeDelegate an issue to yourself or your agent for a lease, or renew the lease.
issues.close()issues.close()repo:writeClose an issue with a reason, after posting an optional comment.
issues.comment()issues.comment()repo:writeComment on an issue, or post a progress update as whoever holds its lease.
issues.commentDelete()issues.comment_delete()repo:writeDelete a comment on an issue: your own, or anyone's with write access to the repository.
issues.commentEdit()issues.comment_edit()repo:writeReplace the text of a comment on an issue.
issues.commentHide()issues.comment_hide()repo:writeHide a comment on an issue behind a reason, or show it again when no reason is sent.
issues.commentReact()issues.comment_react()repo:readAdd your reaction to a comment on an issue.
issues.commentUnreact()issues.comment_unreact()repo:readTake your reaction back from a comment on an issue.
issues.context()issues.context()repo:writeWrite the working context of an issue for whoever picks it up next: a field that is present replaces that field (an empty list or string clears it), an absent one stays; clear removes the whole context.
issues.create()issues.create()repo:writeFile an issue.
issues.createBatch()issues.create_batch()repo:writeFile up to 50 issues in one call, with parents and blockers between them named by ref.
issues.get()issues.get()repo:readShow an issue with its sub-issues, what it blocks, comments and timeline.
issues.list()issues.list()repo:readList the repository's issues, open ones by default.
issues.mine()issues.mine()repo:readIssues by title words, repository name or number across every repository you belong to, open first.
issues.next()issues.next()repo:readGet the most important ready issue: unblocked, not an epic, with no live lease, and unassigned or assigned to you.
issues.react()issues.react()repo:readAdd your reaction to an issue.
issues.related()issues.related()repo:readAsk what earlier issues and pull requests in this repository decided, tried and verified about some files or a topic, before you change them: a short ranked list with the decisions, the dead ends, what proved it and links.
issues.release()issues.release()repo:writeHand a delegated issue back, optionally leaving a handoff note.
issues.similar()issues.similar()repo:readCheck for issues the title reads like, open ones closest first, to look through before filing a duplicate.
issues.start()issues.start()repo:writeClaim an issue and open a caisson on its branch, or return the live caisson already working on it.
issues.subscribe()issues.subscribe()repo:readFollow an issue to be notified of its activity, or stop following it.
issues.unask()issues.unask()repo:writeTake a question back from an issue, answered or not, once its answer is used or it no longer matters.
issues.unreact()issues.unreact()repo:readTake your reaction back from an issue.
issues.update()issues.update()repo:writeChange any field of an issue.

keys

TypeScriptPythonScopeWhat it does
keys.add()keys.add()userAdd an SSH key.
keys.list()keys.list()userList the caller's SSH keys, newest first.
keys.proof()keys.proof()userThe message to sign, and the command that signs it, to prove a key is yours.
keys.remove()keys.remove()userRemove one of the caller's SSH keys.

labels

TypeScriptPythonScopeWhat it does
labels.create()labels.create()repo:writeCreate a label.
labels.delete()labels.delete()repo:writeDelete a label and remove it from every issue that carries it.
labels.list()labels.list()repo:readList the repository's labels and the label names its issues carry, most used first.
labels.update()labels.update()repo:writeRename a label or change its description.

me

TypeScriptPythonScopeWhat it does
me.agentTracking()me.agent_tracking()userWhether the account's agent work is tracked.
me.onboarded()me.onboarded()userMark the welcome steps finished or skipped.
me.update()me.update()userChange the caller's profile.

merge_queue

TypeScriptPythonScopeWhat it does
merge_queue.status()merge_queue.status()repo:readShow whether the merge queue is on, the pull requests waiting (next first), the batches being tested and what left the queue lately with why.

milestones

TypeScriptPythonScopeWhat it does
milestones.create()milestones.create()repo:writeCreate a milestone.
milestones.delete()milestones.delete()repo:writeDelete a milestone and clear it from every issue in it.
milestones.list()milestones.list()repo:readList the repository's milestones and the titles its issues are in, most used first.
milestones.update()milestones.update()repo:writeRetitle a milestone, change its description or due date, or close or reopen it.

notes

TypeScriptPythonScopeWhat it does
notes.create()notes.create()repo:writeLeave one fact about the repository for every later worker, so nobody has to rediscover it: a command flag tests need, a naming rule, a trap you hit.
notes.delete()notes.delete()repo:writeDelete a note.
notes.list()notes.list()repo:readList the repository's notes.
notes.update()notes.update()repo:writeReplace a note's text; the note then names you as its editor.

pulls

TypeScriptPythonScopeWhat it does
pulls.autoMerge()pulls.auto_merge()repo:readShow a pull request's auto-merge: whether it is on, whether it waits in the merge queue and why it has not merged yet.
pulls.autoMergeDisable()pulls.auto_merge_disable()repo:writeTurn auto-merge off for a pull request, and take it out of the merge queue.
pulls.autoMergeEnable()pulls.auto_merge_enable()repo:mergeTurn auto-merge on: the pull request merges, as the caller, once its checks pass and the merge rules allow it, while its branch is still at expectedHead. Can be held for a person.
pulls.branchDiff()pulls.branch_diff()repo:readShow the diff of the pull request from a branch: the open one, else the newest closed or merged one.
pulls.checks()pulls.checks()repo:readShow what a pull request's checks add up to: the CI jobs of the newest run of each workflow on its head, then the latest check run of each name and reporter.
pulls.comment()pulls.comment()repo:writeComment on a pull request: reply in a thread, or start one on a line of the diff.
pulls.conflicts()pulls.conflicts()repo:readThe files that keep a pull request's branch from taking its base, at both branches' current tips, each text file with conflict markers around every conflict.
pulls.create()pulls.create()repo:writeOpen a pull request from a branch into a base branch.
pulls.deleteComment()pulls.delete_comment()repo:writeDelete a comment on a pull request.
pulls.diff()pulls.diff()repo:readShow what a pull request changes: the commits it adds and its diff against the merge base, with totals.
pulls.dismiss()pulls.dismiss()repo:writeDismiss the reviews that approved or asked for changes on a pull request.
pulls.editComment()pulls.edit_comment()repo:writeEdit a comment on a pull request.
pulls.forCommit()pulls.for_commit()repo:readList the pull requests whose commits include a commit, among the newest few hundred of any state.
pulls.get()pulls.get()repo:readShow a pull request with its threads, whether it merges cleanly and the merge rules it does not meet yet.
pulls.hideComment()pulls.hide_comment()repo:writeHide a comment on a pull request behind a reason, or show it again when no reason is sent.
pulls.list()pulls.list()repo:readList a repository's pull requests, newest first.
pulls.merge()pulls.merge()repo:mergeMerge a pull request. Can be held for a person.
pulls.resolveConflicts()pulls.resolve_conflicts()repo:writeBring the base into a pull request's branch as one merge commit by the caller, with every conflict resolved.
pulls.resolveThread()pulls.resolve_thread()repo:writeResolve a review thread, or reopen it.
pulls.review()pulls.review()repo:writeApprove a pull request, ask for changes or comment, with line comments that land with it or not at all.
pulls.stack()pulls.stack()repo:readShow the whole tree of pull requests a pull request belongs to, root first, depth first.
pulls.touching()pulls.touching()repo:readList the pull requests that change a file, or a folder when path ends in /, newest first.
pulls.update()pulls.update()repo:writeEdit a pull request: its title, description, state (close, reopen, mark ready or back to draft), reviewer, base or lock.
pulls.updateBranch()pulls.update_branch()repo:writeMerge the base branch into a pull request's branch on the server, for a merge refused as behind.

repos

TypeScriptPythonScopeWhat it does
repos.commit()repos.commit()repo:readShow a commit: its message, author, parent and child, and its changes as a diff of the first files in path order.
repos.commits()repos.commits()repo:readList the commits of a branch, tag or commit, newest first, or the history of one path with path.
repos.compare()repos.compare()repo:readCompare two branches, tags or commits: the commits head adds since their merge base and its diff.
repos.create()repos.create()repo:adminCreate a repository for the caller, or in an org they belong to.
repos.get()repos.get()repo:readShow a repository: description, visibility, default branch, branches, clone URLs and the caller's access (read, write or admin).
repos.list()repos.list()repo:readList the repositories the caller can reach, newest first: their own, the ones they collaborate on and their orgs'.
repos.update()repos.update()repo:adminChange a repository's description, visibility, default branch, Drydock queue weight, CI cap and host pin, clone defaults or topics.

sandboxes

TypeScriptPythonScopeWhat it does
sandboxes.create()sandboxes.create()sandboxStart a sandbox: an isolated Linux container on one of the organization's Drydock hosts, for untrusted code, builds, tests or scripts.
sandboxes.delete()sandboxes.delete()sandboxDestroy a sandbox now, kept files and checkpoints included.
sandboxes.exec()sandboxes.exec()sandboxRun a command in a running sandbox and answer when it ends, with its output and exit code.
sandboxes.get()sandboxes.get()sandboxShow one sandbox.
sandboxes.list()sandboxes.list()sandboxList an owner's sandboxes, newest first.
sandboxes.stop()sandboxes.stop()sandboxStop a sandbox now.
TypeScriptPythonScopeWhat it does
search.code()search.code()repo:readSearch file contents at branch heads without opening a caisson: matching lines with line numbers, grouped by file, plus repositories by name and files by path.

symbols

TypeScriptPythonScopeWhat it does
symbols.find()symbols.find()repo:readWhere functions, types and classes are defined, by name: path:line, kind and the line.
symbols.refs()symbols.refs()repo:readAn identifier's definitions and every line that references it (not comments or strings), as path:line.

tokens

TypeScriptPythonScopeWhat it does
tokens.create()tokens.create()userCreate an access token.
tokens.list()tokens.list()userList the caller's access tokens, newest first, including the OAuth grants MCP clients hold.
tokens.revoke()tokens.revoke()userRevoke one of the caller's access tokens.

waits

TypeScriptPythonScopeWhat it does
waits.wait()waits.wait()any tokenHold the request until a pull request's checks, merge, review, conflict or push, a CI run, a caisson, an issue or a held action reaches the state asked for, or the window (at most 55 seconds) ends.

Loading Sailfork