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, with sailfork token create, or with POST /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-git stores it so git never asks.
  • Browser session. The site itself calls the same routes with the sf_session cookie. 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.

ScopeAllows
repo:readClone, fetch and read issues, pull requests and CI runs
repo:writePush, open and merge pull requests, edit issues, rerun CI
repo:adminCreate and delete repositories, change branch protection and CI secrets
userRead and update your profile, SSH keys and tokens
org:readSee your organizations, members and teams
org:adminCreate organizations; manage members, teams, rules, domains, CI providers and Drydock hosts
sandboxStart sandboxes and run commands on your organizations' Drydock hosts
  • A broader scope includes the narrower ones in its family: repo:write includes repo:read, repo:admin includes both, and org:admin includes org:read.
  • POST /api/tokens takes { name, scopes, expires, repos? }. expires is optional: a timestamp, a YYYY-MM-DD date or null for no expiry. Pass repos as a list of owner/name to 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.

StatusMeaning
401No credential, or one that does not check out.
403Signed in, but not allowed: the token lacks the scope, is limited to other repositories, or a rule refuses the change.
404No such thing. A private repository you cannot read also answers 404, so its existence is not revealed.
409The request conflicts with the current state: already merged, another open pull request for the branch, a merge rule refusing.
422A field is invalid. The message says which.
429Rate 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. Pass nextCursor back as cursor to get the next page; it is null on the last page. limit is 1 to 100 for pull requests and issues (default 30) and 1 to 200 for caissons.
  • Commit history pages with limit and skip. The activity feed (GET /api/events) returns { events, cursor, more }; pass cursor back as after.
  • 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 as If-None-Match to 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-Timing header 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? }. org makes an organization the owner.
  • GET /api/repos/{owner}/{repo}: The repository, its branches, clone URLs and your access.
  • PATCH /api/repos/{owner}/{repo}: Change about, visibility or defaultBranch. Admins only; send one field.
  • DELETE /api/repos/{owner}/{repo}: Schedule deletion in 14 days. The repository is hidden at once; DELETE .../deletion restores 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. Supports Range and ETag.
  • 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. state is open (default), draft, merged, closed or all.
  • POST /api/repos/{owner}/{repo}/pulls: Open one: { title, branch, base, body?, draft?, reviewer? }. branch is 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}: Change title, body, state (open, draft or closed) or reviewer. 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. status is one or more of triage, ready, in_progress, in_review, done, canceled, duplicate.
  • POST /api/repos/{owner}/{repo}/issues: Create one: title and, 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. With claim=true it is leased to your token. 204 when none is ready.
  • POST /api/repos/{owner}/{repo}/issues/{n}/claim: Lease an issue for minutes. 409 when another token holds it.
  • POST /api/repos/{owner}/{repo}/issues/{n}/release: Give the lease back, with an optional note.

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? }. scope lists 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 with dryRun.
  • 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 has on: 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? }. events are push, pull_request and ci_run. The whsec_ secret is shown once.

Resource pages

Each page lists every route of a resource with parameters, scopes, responses and examples.

PageCovers
RepositoriesRepositories, files, commits, branches, protection, collaborators
ReleasesReleases, assets and downloads
SearchCode search, explore, symbols, people lookup, server status
Pull requestsPull requests, reviews, threads, merge, compare
IssuesIssues, labels, milestones, notes, attachments, agent work
CaissonsOnline worktrees: files, edits, commit, pull request, review
CIRuns, logs, artifacts, secrets, environments, caches, workflows
SandboxesDrydock hosts, sandboxes, previews, settings, secrets
OrganizationsOrganizations, members, teams, invitations, domains, usage
AccountProfile, tokens, SSH keys, webhooks, notifications, events

Loading Sailfork