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

```sh
export SAILFORK_TOKEN=<your token>
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://status.sailfork.com/api/me
```

A pull request is one POST.

```sh
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.

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

| 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. 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](https://status.sailfork.com/docs/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](https://status.sailfork.com/docs/api-account)).

## 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](https://status.sailfork.com/docs/api-repositories) for every route, including branches, protection, collaborators and file commits, and the [Releases API](https://status.sailfork.com/docs/api-releases) for releases and assets. [Search API](https://status.sailfork.com/docs/api-search) 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](https://status.sailfork.com/docs/api-pulls) 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](https://status.sailfork.com/docs/apps#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](https://status.sailfork.com/docs/api-issues) 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](https://status.sailfork.com/docs/api-caissons) 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](https://status.sailfork.com/docs/api-ci) 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](https://status.sailfork.com/docs/api-account) 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.

| Page | Covers |
| --- | --- |
| [Repositories](https://status.sailfork.com/docs/api-repositories) | Repositories, files, commits, branches, protection, collaborators |
| [Releases](https://status.sailfork.com/docs/api-releases) | Releases, assets and downloads |
| [Search](https://status.sailfork.com/docs/api-search) | Code search, explore, symbols, people lookup, server status |
| [Pull requests](https://status.sailfork.com/docs/api-pulls) | Pull requests, reviews, threads, merge, compare |
| [Issues](https://status.sailfork.com/docs/api-issues) | Issues, labels, milestones, notes, attachments, agent work |
| [Caissons](https://status.sailfork.com/docs/api-caissons) | Online worktrees: files, edits, commit, pull request, review |
| [CI](https://status.sailfork.com/docs/api-ci) | Runs, logs, artifacts, secrets, environments, caches, workflows |
| [Sandboxes](https://status.sailfork.com/docs/api-sandboxes) | Drydock hosts, sandboxes, previews, settings, secrets |
| [Organizations](https://status.sailfork.com/docs/api-orgs) | Organizations, members, teams, invitations, domains, usage |
| [Account](https://status.sailfork.com/docs/api-account) | Profile, tokens, SSH keys, webhooks, notifications, events |

---

Every docs page: https://status.sailfork.com/llms.txt
