REST API
JSON over HTTPS under /api, with access tokens, scopes, errors, paging and the routes people use most.
The API lives at https://status.sailfork.com/api. The CLI, the MCP server and this site all use it, so everything the site does is a documented call.
First request
Create a token, then call any route with it.
export SAILFORK_TOKEN=<your token>
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://status.sailfork.com/api/me A pull request is one POST.
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"title":"Fix the tide math","branch":"tide-fix","base":"main"}' \
https://status.sailfork.com/api/repos/<owner>/<repo>/pulls No token handy? sailfork api /api/me calls any route with the login of the CLI. Without a token, public repositories can be read.
Authentication
- Access token. Send
Authorization: Bearer <token>. Create one in Settings under Keys and tokens, withsailfork token create, or withPOST /api/tokens. The secret is shown once. - Git over HTTPS. Git uses Basic auth: your handle as the username and an access token as the password.
sailfork auth setup-gitstores it so git never asks. - Browser session. The site itself calls the same routes with the
sf_sessioncookie. Scripts should use a token. - Agents. Add
X-Sailfork-Agent: <tool name>to requests an agent makes. Pull requests and comments it creates are then marked as agent work.
Token scopes
Give a token only what it needs. These are the scopes the token form offers.
| Scope | Allows |
|---|---|
repo:read | Clone, fetch and read issues, pull requests and CI runs |
repo:write | Push, open and merge pull requests, edit issues, rerun CI |
repo:admin | Create and delete repositories, change branch protection and CI secrets |
user | Read and update your profile, SSH keys and tokens |
org:read | See your organizations, members and teams |
org:admin | Create organizations; manage members, teams, rules, domains, CI providers and Drydock hosts |
sandbox | Start sandboxes and run commands on your organizations' Drydock hosts |
- A broader scope includes the narrower ones in its family:
repo:writeincludesrepo:read,repo:adminincludes both, andorg:adminincludesorg:read. POST /api/tokenstakes{ name, scopes, expires, repos? }.expiresis optional: a timestamp, aYYYY-MM-DDdate ornullfor no expiry. Passreposas a list ofowner/nameto limit the token to those repositories; it then answers 403 everywhere else.- A missing, invalid or expired token is 401 with
WWW-Authenticate: Bearer realm="sailfork". A valid token without the scope is 403.
Errors
Errors are JSON, { "error": "what went wrong" }, with the status that says why.
| Status | Meaning |
|---|---|
401 | No credential, or one that does not check out. |
403 | Signed in, but not allowed: the token lacks the scope, is limited to other repositories, or a rule refuses the change. |
404 | No such thing. A private repository you cannot read also answers 404, so its existence is not revealed. |
409 | The request conflicts with the current state: already merged, another open pull request for the branch, a merge rule refusing. |
422 | A field is invalid. The message says which. |
429 | Rate limited. Wait for the Retry-After header, when there is one, then retry. |
Paging
- Lists of pull requests, issues and caissons answer
{ "items": [...], "nextCursor": "..." }, newest first. PassnextCursorback ascursorto get the next page; it isnullon the last page.limitis 1 to 100 for pull requests and issues (default 30) and 1 to 200 for caissons. - Commit history pages with
limitandskip. The activity feed (GET /api/events) returns{ events, cursor, more }; passcursorback asafter. - A cursor is opaque. Use it only with the filters that produced it; any other value is 422.
Caching, retries and timing
- Repository, pull request, issue and caisson reads send an
ETag. Send it back asIf-None-Matchto get a 304 with no body while nothing changed. - Issue writes accept
Idempotency-Key: <1 to 200 characters>. A retry with the same key and body returns the first response and changes nothing; the same key with a different body is 409. Keys last a day. - Every response carries a
Server-Timingheader with the database, storage and total time, plus the time spent waiting for a database connection (pool), queued before a repository read ran (gate), and the server CPU the request used (cpu).
Rate limits
Routes that are costly or open to anyone count requests in one-minute windows, per caller (an access token, or an IP address when signed out). Past the limit the route answers 429 with a Retry-After header in seconds and { "error": "too many requests, try again shortly" }. Limits differ by route and are not sent back in headers, so back off when you see a 429 instead of counting calls. Rate limits lists every limited route and its number.
Live sync
/api/sync is a WebSocket that keeps the Sailfork site's local copy of repositories, pull requests and issues current. It authenticates with the sf_session cookie and its messages are the site's own, so it is not meant for scripts. Poll the REST routes, or follow GET /api/events/stream for a feed of changes (see Account API).
Repositories
The repository view, history and files. {ref} is one path segment: write a slash in a branch name as %2F. See the Repositories API for every route, including branches, protection, collaborators and file commits, and the Releases API for releases and assets. Search API covers code search.
GET /api/repos: Your repositories and your organizations’, newest first.POST /api/repos: Create one:{ name, about, visibility, org?, readme? }.orgmakes an organization the owner.GET /api/repos/{owner}/{repo}: The repository, its branches, clone URLs and your access.PATCH /api/repos/{owner}/{repo}: Changeabout,visibilityordefaultBranch. Admins only; send one field.DELETE /api/repos/{owner}/{repo}: Schedule deletion in 14 days. The repository is hidden at once;DELETE .../deletionrestores it.GET /api/repos/{owner}/{repo}/commits?ref=&path=&limit=&skip=: Commits, newest first.GET /api/repos/{owner}/{repo}/tree/{ref}/{path}: A folder’s entries with the last commit that touched each.GET /api/repos/{owner}/{repo}/blob/{ref}/{path}: A file’s contents and history.GET /api/repos/{owner}/{repo}/raw/{ref}/{path}: The file’s bytes. SupportsRangeandETag.GET /api/search?q=&repo=owner/name&path=&lang=&limit=: Search code across the repositories you can read.
Pull requests
Reading needs repo:read, changing needs repo:write. A merge that the merge rules refuse is 409. See the Pull requests API for reviews, threads, merge options and compare routes.
GET /api/repos/{owner}/{repo}/pulls?state=&q=&author=&head=&base=&cursor=&limit=: A page of pull requests.stateisopen(default),draft,merged,closedorall.POST /api/repos/{owner}/{repo}/pulls: Open one:{ title, branch, base, body?, draft?, reviewer? }.branchis the head branch.GET /api/repos/{owner}/{repo}/pulls/{n}: The pull request with its commits, files, reviews and threads.PATCH /api/repos/{owner}/{repo}/pulls/{n}: Changetitle,body,state(open,draftorclosed) orreviewer. The author, or anyone who may push.POST /api/repos/{owner}/{repo}/pulls/{n}/merge: Merge it. 409 when the merge rules refuse.POST /api/repos/{owner}/{repo}/pulls/{n}/reviews: Review it:{ verdict: "approve" | "changes" | "comment", body? }.POST /api/repos/{owner}/{repo}/pulls/{n}/comments: Comment on a line, or reply to a thread.GET /api/repos/{owner}/{repo}/pulls/{n}/checks: The CI jobs of the newest run of each workflow on its head commit, and the check runs reported there.POST /api/repos/{owner}/{repo}/check-runs: Report a check run on a commit from an app or a CI provider; see check runs.GET /api/repos/{owner}/{repo}/brief/{n}?comments=: An issue or pull request with its comments, diff summary, threads and CI failures in one request, made for agents.
Issues
Reads need no sign-in on a public repository. Writes need repo:write. See the Issues API for labels, milestones, attachments, notes and agent leases.
GET /api/repos/{owner}/{repo}/issues?status=&state=&label=&assignee=&q=&cursor=&limit=: A page of issues.statusis one or more oftriage,ready,in_progress,in_review,done,canceled,duplicate.POST /api/repos/{owner}/{repo}/issues: Create one:titleand, optionally, labels, body and the other fields.GET /api/repos/{owner}/{repo}/issues/{n}: The issue with its sub-issues.PATCH /api/repos/{owner}/{repo}/issues/{n}: Change the title, body, state, status, labels, assignees, priority, milestone and more.POST /api/repos/{owner}/{repo}/issues/{n}/comments: Comment:{ body }. From an agent token it is a progress update.GET /api/repos/{owner}/{repo}/issues/next?status=&label=&claim=&minutes=: The next issue to work on. Withclaim=trueit is leased to your token. 204 when none is ready.POST /api/repos/{owner}/{repo}/issues/{n}/claim: Lease an issue forminutes. 409 when another token holds it.POST /api/repos/{owner}/{repo}/issues/{n}/release: Give the lease back, with an optionalnote.
Caissons
A caisson is one agent’s own working branch of a repository, stored on Sailfork. These routes need push access to the repository. {owner} is the repository’s owner, a person or an organization. See the Caissons API for editing, search, review and policy routes.
POST /api/orgs/{owner}/caissons: Open one:{ repo, title, scope, branch?, base? }.scopelists the paths it may write;""means the whole repository.GET /api/orgs/{owner}/caissons?repo=&state=&limit=&cursor=: A page of caissons, newest first.GET /api/orgs/{owner}/caissons/{id}: One caisson: its state, base, changed files and session log.GET /api/orgs/{owner}/caissons/{id}/tree/{path}: A folder: the base commit merged with the caisson’s edits.GET /api/orgs/{owner}/caissons/{id}/files/{path}: A file’s bytes.PUT /api/orgs/{owner}/caissons/{id}/files/{path}: Write a file. The body is the raw bytes, at most 64 MiB.DELETE /api/orgs/{owner}/caissons/{id}/files/{path}: Delete a file.POST /api/orgs/{owner}/caissons/{id}/batch: Apply many changes at once, or preview them withdryRun.GET /api/orgs/{owner}/caissons/{id}/grep?pattern=&glob=&path=: Search the caisson’s files.POST /api/orgs/{owner}/caissons/{id}/commit: Commit the edits to the caisson’s branch:{ message }.POST /api/orgs/{owner}/caissons/{id}/pull: Open the pull request:{ title?, body? }.POST /api/orgs/{owner}/caissons/{id}/stop: Stop it, and optionally delete its branch.
CI runs
Reading needs repo:read. Rerunning, cancelling and dispatching need repo:write. See the CI API for logs, artifacts, secrets, environments and caches.
GET /api/repos/{owner}/{repo}/runs: Recent runs, newest first, at most 200.GET /api/repos/{owner}/{repo}/runs/{id}: One run with every step’s log.GET /api/repos/{owner}/{repo}/runs/{id}/logs?job=: The step logs of a run, or of one job.POST /api/repos/{owner}/{repo}/runs/{id}/rerun: Rerun every job, or send{ failedOnly: true }or{ jobs: [...] }.POST /api/repos/{owner}/{repo}/runs/{id}/cancel: Cancel a run that has not finished. 409 when it has.POST /api/repos/{owner}/{repo}/ci/workflows/{file}/dispatches: Start a workflow that hason: workflow_dispatch:{ ref?, inputs? }.
Tokens and webhooks
Webhooks are for repository admins. Deliveries are signed the way GitHub’s are: X-Sailfork-Signature-256: sha256=<HMAC-SHA256 of the raw body>. See the Account API for tokens, SSH keys, webhooks, notifications and the event feed.
GET /api/tokens: Your tokens, newest first.POST /api/tokens: Create a token. The secret is in this response only.DELETE /api/tokens/{id}: Revoke a token.GET /api/repos/{owner}/{repo}/hooks: The repository’s webhooks with their last delivery.POST /api/repos/{owner}/{repo}/hooks: Create one:{ url, events? }.eventsarepush,pull_requestandci_run. Thewhsec_secret is shown once.
Resource pages
Each page lists every route of a resource with parameters, scopes, responses and examples.
| Page | Covers |
|---|---|
| Repositories | Repositories, files, commits, branches, protection, collaborators |
| Releases | Releases, assets and downloads |
| Search | Code search, explore, symbols, people lookup, server status |
| Pull requests | Pull requests, reviews, threads, merge, compare |
| Issues | Issues, labels, milestones, notes, attachments, agent work |
| Caissons | Online worktrees: files, edits, commit, pull request, review |
| CI | Runs, logs, artifacts, secrets, environments, caches, workflows |
| Sandboxes | Drydock hosts, sandboxes, previews, settings, secrets |
| Organizations | Organizations, members, teams, invitations, domains, usage |
| Account | Profile, tokens, SSH keys, webhooks, notifications, events |