# Account API

Read and change your own account over REST, including access tokens, SSH keys, webhooks, notifications, the event feed, undo, blocks and CLI and MCP sign-in.

These routes belong to the signed-in person: their profile, credentials, inbox and security settings. Authentication, scopes, errors and paging work as described in [the REST API overview](https://sailfork.com/docs/api). Links: [authentication](https://sailfork.com/docs/api#authentication), [token scopes](https://sailfork.com/docs/api#token-scopes), [errors](https://sailfork.com/docs/api#errors), [paging](https://sailfork.com/docs/api#paging).

Most routes here need the `user` scope. A few need `repo:read` or `repo:admin`, and the table or text for each route says which. A route marked **browser session** refuses tokens with 403 `this action needs a browser session, not a token`. It is meant for the site, so a script cannot change a password-class setting with a stolen token.

## Your account

### Get yourself

```http
GET /api/me
```

Returns the signed-in account. Any valid credential works, whatever its scopes. Without one it is 401, which is how the site tells whether you are signed in.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://sailfork.com/api/me
```

```json
{
  "id": "6c1f6a0e-2f0b-4c0a-9d0e-2b6a3a1c7e11",
  "name": "Fenil Sonani",
  "handle": "fenil",
  "email": "fenil@example.com",
  "sshBase": "ssh://git@sailfork.com:22",
  "gitBase": "https://sailfork.com",
  "avatarUrl": null,
  "onboardedAt": "2026-11-09T18:04:11Z"
}
```

| Field | Meaning |
| --- | --- |
| `sshBase` | `ssh://git@host:port` for SSH clone URLs, `null` when the server has SSH off. |
| `gitBase` | The origin of HTTPS clone URLs. |
| `onboardedAt` | When you finished or skipped the welcome steps. `null` right after sign-up. |
| `admin`, `safetyOperator` | Present and `true` only for site operators. |
| `termsStale` | Present and `true` while you have not accepted the current terms. Tokens and CI are never blocked by it. |

### Change your profile

```http
PATCH /api/me
```

Needs `user`. Every field is optional and only the ones you send change.

| Field | Type | Rule |
| --- | --- | --- |
| `name` | string | 1 to 100 characters. |
| `bio` | string | At most 160 characters. |
| `location` | string | At most 100 characters. |
| `website` | string | A domain such as `example.com` or an http or https URL, at most 200 characters. An empty string clears it. |
| `timeZone` | string | A time zone name such as `America/Los_Angeles`. |
| `workStart`, `workEnd` | integer | Hours from 0 to 24, with the start before the end. |
| `showTide` | boolean | Whether visitors see your activity grid. |

```sh
curl -X PATCH -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"bio":"Maps, tides and git.","timeZone":"America/Los_Angeles"}' \
  https://sailfork.com/api/me
```

The response is `{ id, name, handle, email, avatarUrl }`. A bad field is 422 and the message names it. Unknown fields are 422 too.

### Welcome steps and terms

| Route | What it does |
| --- | --- |
| `POST /api/me/onboarding` | Marks the welcome steps finished or skipped. Needs `user`. Answers 204. The first time is kept. |
| `POST /api/me/terms` | Records that you accepted the current terms. **Browser session.** Body `{ "version": "..." }`. Answers 204, or 422 when `version` is not the current terms version. |

Agent tracking is documented with [the issues API](https://sailfork.com/docs/api-issues).

### Handle

```http
GET /api/handles/{handle}/available
POST /api/me/handle
```

`GET` works signed out. It answers `{ "handle": "tide", "available": false, "reason": "taken" }`. `reason` is `taken` or `invalid` and is absent when the handle is free. Your own old handles count as free for you.

`POST` needs `user`, takes `{ "handle": "tide" }` and answers `{ "handle": "tide", "previous": "fenil" }`. The handle is 1 to 39 characters: letters, digits and hyphens, not starting or ending with a hyphen. A bad or reserved one is 422, and one already taken is 409. The old handle stays reserved and redirects to the new one, and existing clone URLs keep working.

### Picture

```http
POST /api/me/avatar
DELETE /api/me/avatar
GET /api/avatars/{user}/{file}
```

`POST` needs `user`. The body is the raw image with `Content-Type: image/png`, `image/jpeg` or `image/webp`, at most 5 MiB. Sailfork stores it as square 256 and 64 pixel WebP and answers `{ "avatarUrl": "/api/avatars/6c1f.../256-3f9a....webp" }`. Another content type is 415, an unreadable image is 422, and 503 means avatar storage is not set up on the server.

`DELETE` needs `user` and answers 204. `GET /api/avatars/{user}/{file}` serves the stored image as `image/webp` to anyone. Use the `avatarUrl` you were given, since `{file}` carries a content hash.

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: image/png" \
  --data-binary @me.png https://sailfork.com/api/me/avatar
```

### Export and delete your account

| Route | What it does |
| --- | --- |
| `POST /api/me/export` | **Browser session.** Builds an export of your data and answers `{ "url", "expiresAt", "emailed" }`. The link works for 24 hours, and is also mailed when the server has mail. |
| `GET /api/me/export/{token}` | Downloads the export as a JSON attachment. The link is the credential, so no sign-in is needed. 404 once it expires. |
| `POST /api/me/deletion` | **Browser session.** Schedules the account for deletion in 14 days and answers `{ "deletionAt": "..." }`. 409 while you are the only owner of an organization. |
| `DELETE /api/me/deletion` | **Browser session.** Cancels a scheduled deletion. Answers 204. |

## Profiles

### Get a profile

```http
GET /api/users/{handle}
```

The public profile of a person: bio, pinned repositories, recent activity and the activity grid. It works signed out. A token without `repo:read` is treated as signed out. Activity in private repositories shows to its owner only. An unknown handle is 404.

| Query | Type | Meaning |
| --- | --- | --- |
| `year` | integer | Show the grid that ends in this year. From 2000 to the current year, else 422. |

```sh
curl https://sailfork.com/api/users/fenil
```

```json
{
  "name": "Fenil Sonani",
  "handle": "fenil",
  "bio": "Maps, tides and git.",
  "location": "San Francisco",
  "website": "example.com",
  "github": "fenilsonani",
  "joined": "2026-03-02",
  "files": { "repo": "fenil/profile", "dir": "", "readme": "# Hi", "llms": null },
  "weekOf": "2026-11-08",
  "timeZone": "America/Los_Angeles",
  "tide": { "human": [[0, 2, 0]], "crew": [[0, 0, 1]] },
  "years": [2026, 2025],
  "history": null,
  "showTide": true,
  "avatarUrl": null,
  "crew": [],
  "activity": [
    {
      "at": "2026-11-09T21:40:00Z",
      "actor": { "name": "fenil", "agent": false },
      "kind": "pull",
      "action": "merged",
      "target": "fenil/ocean-landing #41",
      "approvedBy": null
    }
  ],
  "pinned": [
    {
      "name": "fenil/ocean-landing",
      "about": "The landing page.",
      "visibility": "public",
      "language": "Svelte",
      "crewShare": 0.4,
      "pushedAt": "2026-11-09T21:40:00Z"
    }
  ]
}
```

The example trims `tide` to a few cells. In the real response each grid has 7 rows (Sunday first) of 52 weekly columns, oldest week first, each cell 0 to 9. `human` counts people and `crew` counts agents.

`files` is the README and `llms.txt` the profile shows above everything else. They come from the person's repository named `profile`, so there is no route to write them: push to that repository. Each is cut at 256 KiB. `history` is imported GitHub contribution history, `null` when there is none.

### List a person's repositories

See [the repositories API](https://sailfork.com/docs/api-repositories) for `GET /api/users/{handle}/repos`.

## Access tokens

Tokens are how scripts, CI and agents call the API. The `user` scope is needed for all three routes below. [Token scopes](https://sailfork.com/docs/api#token-scopes) lists what each scope allows.

### List tokens

```http
GET /api/tokens
```

Your tokens, newest first. The secret is never returned again.

```json
[
  {
    "id": "0f8a1d1e-5c43-4f4a-9a8e-3a2f1f0a9b10",
    "name": "ci-deploy",
    "scopes": ["repo:read", "repo:write"],
    "repos": ["fenil/ocean-landing"],
    "expires": "2027-06-30T23:59:59Z",
    "lastUsed": "2026-11-09T21:40:00Z",
    "usedBy": "claude-code"
  }
]
```

A token made by an OAuth grant to an MCP client also carries `clientId`, `clientName`, `oauthScope` and `refreshExpires`. Deleting it revokes the grant.

### Create a token

```http
POST /api/tokens
```

| Field | Type | Meaning |
| --- | --- | --- |
| `name` | string, required | 1 to 100 characters. |
| `scopes` | string[], required | At most 32 scope names. An unknown name is 422. An empty list asks for every scope. |
| `expires` | string or null | A date such as `2027-06-30` (end of that day, UTC) or an RFC 3339 timestamp. Past or malformed is 422. Omit or send `null` for no expiry. |
| `repos` | string[] | 1 to 100 `owner/name` values you can read. The token then reaches only those repositories and is 403 everywhere else. |

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"ci-deploy","scopes":["repo:read"],"expires":"2027-06-30","repos":["fenil/ocean-landing"]}' \
  https://sailfork.com/api/tokens
```

```json
{
  "token": {
    "id": "0f8a1d1e-5c43-4f4a-9a8e-3a2f1f0a9b10",
    "name": "ci-deploy",
    "scopes": ["repo:read"],
    "repos": ["fenil/ocean-landing"],
    "expires": "2027-06-30T23:59:59Z",
    "lastUsed": null,
    "usedBy": null
  },
  "secret": "sf_..."
}
```

Answers 201. The `secret` is in this response only.

A token can mint another token only inside its own scopes, and the new one cannot outlive it. Asking for more, or for the empty list, needs a **browser session** (403 otherwise).

### Revoke a token

```http
DELETE /api/tokens/{id}
```

Answers 204. A token that is not yours, or does not exist, is 404.

Your agent tokens are listed by [the issues API](https://sailfork.com/docs/api-issues).

## SSH keys

All four routes need `user`.

### List keys

```http
GET /api/keys
```

Your keys, newest first.

```json
[
  {
    "id": "4d6b3c70-7a39-4b8c-8c0b-91d5f4a9d2aa",
    "title": "laptop",
    "kind": "auth",
    "fingerprint": "SHA256:o3Ez5y1yQ2g1l8m0wq0G2Wz3p0xk4m3Hn1rXw0lq9aA",
    "added": "2026-10-01T16:22:09Z",
    "lastUsed": null,
    "verified": true
  }
]
```

`verified` is `true` when you proved you hold the private key.

### Get the proof message

```http
GET /api/keys/proof
```

Returns what to sign to prove a key is yours, and the command that signs it.

```json
{
  "namespace": "sailfork-key",
  "message": "sailfork ssh key for account 6c1f6a0e-2f0b-4c0a-9d0e-2b6a3a1c7e11",
  "command": "printf %s 'sailfork ssh key for account 6c1f6a0e-2f0b-4c0a-9d0e-2b6a3a1c7e11' | ssh-keygen -Y sign -n sailfork-key -f ~/.ssh/id_ed25519"
}
```

### Add a key

```http
POST /api/keys
```

| Field | Type | Meaning |
| --- | --- | --- |
| `title` | string, required | 1 to 100 characters. |
| `kind` | string, required | `auth` to sign in over SSH, or `signing` to verify commit signatures. |
| `key` | string, required | The OpenSSH public key line. Types: `ssh-ed25519`, `ssh-rsa` (at least 2048 bits), `ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`, `sk-ssh-ed25519@openssh.com`, `sk-ecdsa-sha2-nistp256@openssh.com`. |
| `signature` | string | The armored SSHSIG over the proof message, made with this key. |

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d "{\"title\":\"laptop\",\"kind\":\"auth\",\"key\":\"$(cat ~/.ssh/id_ed25519.pub)\"}" \
  https://sailfork.com/api/keys
```

Answers 201 with the key. An invalid key, type or signature is 422.

Registering a public key proves nothing, so a key without a `signature` is saved with `verified: false`. A proven key replaces an unproven registration of the same key on any account. That is how you win back a key someone else registered first. A key that is already registered gets 409, and the message tells you to prove it. A key already proven by another holder is 409 too.

### Remove a key

```http
DELETE /api/keys/{id}
```

Answers 204, or 404 for a key that is not yours.

## Webhooks

A webhook posts a JSON body to your URL when something happens in a repository. These routes need the `repo:admin` scope and admin access to the repository. A caller who can see the repository but is not an admin gets 403. One who cannot see it gets 404.

### List webhooks

```http
GET /api/repos/{owner}/{repo}/hooks
```

Answers `{ "hooks": [...] }`, oldest first, each with its last delivery.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://sailfork.com/api/repos/fenil/ocean-landing/hooks
```

```json
{
  "hooks": [
    {
      "id": "b7a52e3c-1c2f-4f54-8f6a-0b9d0c1a2e55",
      "url": "https://ci.example.com/sailfork",
      "events": ["push", "pull_request"],
      "active": true,
      "createdAt": "2026-11-01T17:00:00Z",
      "updatedAt": "2026-11-01T17:00:00Z",
      "lastDelivery": { "event": "push", "state": "delivered", "statusCode": 200, "at": "2026-11-09T21:40:02Z" }
    }
  ]
}
```

### Create a webhook

```http
POST /api/repos/{owner}/{repo}/hooks
```

| Field | Type | Meaning |
| --- | --- | --- |
| `url` | string, required | An http or https URL of at most 2048 bytes, without a username or password, pointing at a public address. Localhost, private, loopback and link-local targets are 422, and they are refused again at delivery. |
| `events` | string[] | Any of `push`, `pull_request`, `ci_run`. Defaults to all three. An empty list or an unknown event is 422. |

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://ci.example.com/sailfork","events":["push","pull_request"]}' \
  https://sailfork.com/api/repos/fenil/ocean-landing/hooks
```

Answers 201 with the webhook and a `secret` that starts with `whsec_`. The secret is in this response only, and it is stored sealed. A `ping` delivery is queued at once. A repository has at most 20 webhooks (422 past that). 503 means the server has no `SAILFORK_SECRET_KEY` to seal secrets with.

### Get, change or delete a webhook

```http
GET    /api/repos/{owner}/{repo}/hooks/{id}
PATCH  /api/repos/{owner}/{repo}/hooks/{id}
DELETE /api/repos/{owner}/{repo}/hooks/{id}
```

`GET` returns the webhook, or 404 for an unknown id. `PATCH` takes any of `url`, `events` and `active`, with the same checks as create, and returns the webhook. A disabled webhook queues nothing, and its pending deliveries fail as `the webhook is disabled`. `DELETE` answers 204 and removes its deliveries with it. In an organization's repository, create, change and delete are recorded in the organization's audit log.

### List deliveries

```http
GET /api/repos/{owner}/{repo}/hooks/{id}/deliveries?limit=
```

Answers `{ "deliveries": [...] }`, newest first. `limit` is 1 to 100 and defaults to 30. Deliveries are kept for 30 days.

```json
{
  "deliveries": [
    {
      "id": "e3b0c442-98fc-4c14-9afb-f4c8996fb924",
      "event": "push",
      "state": "delivered",
      "attempts": 1,
      "statusCode": 200,
      "responseExcerpt": "ok",
      "error": null,
      "durationMs": 84,
      "createdAt": "2026-11-09T21:40:02Z",
      "lastAttemptAt": "2026-11-09T21:40:02Z",
      "nextAttemptAt": null
    }
  ]
}
```

`state` is `pending`, `delivered` or `failed`. `nextAttemptAt` is set only while pending.

### Redeliver

```http
POST /api/repos/{owner}/{repo}/hooks/{id}/deliveries/{delivery}/redeliver
```

Queues a copy of that delivery's body as a new delivery with a new id. Answers 202 with the new delivery. An unknown delivery is 404.

### What a delivery looks like

Each delivery is a POST of a JSON body with these headers.

| Header | Value |
| --- | --- |
| `X-Sailfork-Event` | `push`, `pull_request`, `ci_run` or `ping`. |
| `X-Sailfork-Delivery` | The delivery id. |
| `X-Sailfork-Signature-256` | `sha256=` and the hex HMAC-SHA256 of the raw body under the webhook's secret, the same scheme GitHub uses. |

Any 2xx answer counts as delivered. Anything else, a refused connection, or no answer within 10 seconds is retried 10 seconds, 1 minute, 5 minutes and 30 minutes later, for 5 attempts in all, and then the delivery is `failed`. Redirects are not followed. A delivery is queued in the same transaction as the change, so it survives a restart.

Every body has `event`, `repository` (`full_name`, `html_url`, `private`, `default_branch`) and `sender` (`login`). The rest depends on the event.

| Event | Extra fields |
| --- | --- |
| `push` | `ref`, `before`, `after` (40 zeros for none), `created`, `deleted`, `summary`. |
| `pull_request` | `action` (`opened`, `closed`, `merged`, `reopened`), `number`, and `pull_request` with `number`, `title`, `body`, `state`, `draft`, `merged`, `html_url`, `user.login`, `head.ref`, `base.ref`. |
| `ci_run` | `action` (`completed`), `conclusion` (`pass`, `fail`, `cancelled`), and `run` with `run`, `workflow`, `state`, `branch`, `sha`, `trigger`, `pull_request` (a number or `null`), `html_url`. |
| `ping` | `hook_id`, `zen`. |

To check a signature, compute the HMAC of the raw request body with your secret and compare it to the header in constant time.

## Notifications

The inbox has two tabs. **For you** holds what needs you: assigned and mentioned issues, held writes, failed checks. **Following** holds news you only hear about, such as comments and agent updates. Both routes need `user`. [Notifications](https://sailfork.com/docs/notifications) explains the inbox from the site's side.

### List notifications

```http
GET /api/me/notifications
```

| Query | Type | Meaning |
| --- | --- | --- |
| `tab` | string | `for-you` or `following`. Anything else is 422. |
| `owner` | string | One workspace: an organization's handle or your own. Omit for all. |
| `items` | boolean | `false` answers with the counts only. |

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" "https://sailfork.com/api/me/notifications?tab=for-you"
```

```json
{
  "items": [
    {
      "id": "7c1f0c52-2e8d-4a6b-b1c4-6f0e9d7a3b21",
      "ids": ["7c1f0c52-2e8d-4a6b-b1c4-6f0e9d7a3b21"],
      "kind": "issue",
      "state": "assigned",
      "tab": "for-you",
      "title": "fenil/ocean-landing #42 was assigned to you",
      "body": "Fix the tide math",
      "link": "/fenil/ocean-landing/issues/42",
      "at": "2026-11-09T21:40:00Z",
      "read": false,
      "workspace": "fenil"
    }
  ],
  "unread": 1,
  "counts": { "forYou": 1, "following": 0 },
  "workspaces": [{ "handle": "fenil", "forYou": 1, "following": 0 }]
}
```

Each tab returns its newest 50 entries. Updates from one agent on one issue fold into a single entry, so `ids` can hold several notification ids, and marking the entry read marks all of them. `counts` and `unread` follow the `owner` you asked for, and `workspaces` always lists every workspace with unread entries. `link` is a path in the app.

### Mark notifications read

```http
POST /api/me/notifications/read
```

Send any of `ids` (notification ids), `tab` and `owner`. They narrow each other. Send `{}` to mark every unread notification read. Answers 204. A bad `tab` is 422.

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"tab":"following","owner":"acme"}' https://sailfork.com/api/me/notifications/read
```

## Event feed

The event feed is how an agent follows what happens in repositories: comments, reviews, merges, issue and pull request changes, pushes, CI runs and caisson states. Events are kept for 30 days.

### Read events

```http
GET /api/events
```

Needs `repo:read` with a token. Signed out works only with `repo` or `org`, on public repositories. Without `repo` and `org`, a signed-in caller gets the repositories they own or reach through an organization.

| Query | Type | Meaning |
| --- | --- | --- |
| `repo` | string | `owner/name`. 404 for an unknown repository or a private one you cannot read, 403 for a repository outside a limited token. |
| `org` | string | An owner handle, person or organization. 404 when unknown. |
| `types` | string | Comma separated: `comment`, `review`, `merge`, `pull`, `issue`, `push`, `ci`, `caisson`, and `mention` for events that mention you. Anything else is 422. |
| `after` | string | The `cursor` of an earlier page. It wins over `since`. A bad value is 422. |
| `since` | RFC 3339 | Start at this time. |
| `limit` | integer | 1 to 200, default 50. Out-of-range values are clamped. |

Events come oldest first. With neither `after` nor `since`, the page starts at the beginning of retention.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://sailfork.com/api/events?repo=fenil/ocean-landing&types=pull,review&limit=2"
```

```json
{
  "events": [
    {
      "id": 18204,
      "type": "pull",
      "action": "pull.merge",
      "repo": "fenil/ocean-landing",
      "number": 41,
      "pull": true,
      "actor": "fenil",
      "agent": null,
      "at": "2026-11-09T21:40:00Z",
      "mentions": [],
      "data": { "sha": "9f3c1a2b7d4e5f60718293a4b5c6d7e8f9a0b1c2" }
    }
  ],
  "cursor": "18204",
  "more": false
}
```

`cursor` is the id of the last event returned, else the `after` you passed, else the head. Pass it back as `after` for the next page. `more` is `true` when another page waits. `action` is a finer verb such as `issue.comment`, `pull.review`, `thread.resolve`, `pull.merge`, `run.fail` or `caisson.<state>`. `data` holds the details: body, verdict, state, ref, before, after, sha, workflow, branch and so on.

### Follow events live

```http
GET /api/events/stream
```

The same events and filters as a server-sent event stream. Each message has `id: <event id>`, `event: <type>` and `data: <the event as JSON>`. A comment line goes out every 15 seconds to keep the connection open.

The stream starts after `Last-Event-ID` if the client sends it, else after `after`, else at `since`. With none of them it starts at the head and sends only new events. A reconnecting `EventSource` therefore resumes where it stopped.

With `repo` and `state=ci`, the first message is `event: state`. Its data is `{ "runs": [...], "environments": [...] }`, what `GET /api/repos/{owner}/{repo}/runs?view=summary` and `GET /api/repos/{owner}/{repo}/environments` answer, so a client that follows CI needs neither request to start.

```sh
curl -N -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://sailfork.com/api/events/stream?org=acme&types=ci,mention"
```

## Actions and undo

Sailfork remembers what you did through the API that it can take back, for 7 days. You can undo an action within 24 hours of making it, once. The CLI command is `sailfork undo`.

### List actions

```http
GET /api/me/actions?limit=&repo=
```

Any valid credential works. `limit` is 1 to 100 and defaults to 20. `repo` is `owner/name` and keeps actions on that repository. A repository-limited token sees only actions on its repositories.

```json
{
  "actions": [
    {
      "id": "5a9d3c64-0f2b-4a41-8c75-0a3e6d2b9f10",
      "kind": "issue.comment",
      "repo": "fenil/ocean-landing",
      "text": "Commented on #42",
      "at": "2026-11-09T21:35:00Z",
      "undoable": true
    }
  ]
}
```

`undoable` is `false` when `undoneAt` is set or the action is older than 24 hours, and then `reason` says why.

### Undo an action

```http
POST /api/me/actions/{id}/undo
```

Send `{ "dryRun": true }` to see what undoing would do without doing it. The body is optional.

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"dryRun":true}' https://sailfork.com/api/me/actions/5a9d3c64-0f2b-4a41-8c75-0a3e6d2b9f10/undo
```

```json
{
  "action": { "id": "5a9d3c64-0f2b-4a41-8c75-0a3e6d2b9f10", "kind": "issue.comment", "text": "Commented on #42", "at": "2026-11-09T21:35:00Z", "undoable": true, "repo": "fenil/ocean-landing" },
  "undone": false,
  "dryRun": true,
  "text": "Would delete your comment on fenil/ocean-landing #42"
}
```

| Status | Meaning |
| --- | --- |
| 200 | Done, or a dry run. Undoing an action that is already undone answers 200 with the first result. |
| 404 | Not your action, or one a limited token cannot reach. |
| 409 | Older than 24 hours, or it cannot be reversed any more. The message says why. For a merge that moved on, it gives the git commands for a revert pull request. |
| 422 | A body field other than `dryRun`. |

The kinds you can undo are `issue.comment`, `pull.comment` (deleted), `issue.update` and `pull.update` (previous values restored), `pull.merge` (main moved back, branch recreated, pull request reopened), `caisson.rm` (file written back), `branch.delete` (recreated at its old commit) and `token.create` (revoked). The write the undo makes needs the same scope as the original: `repo:write` for most, `user` for tokens.

## Emails

An account has one primary address and any number of others. Listing and resending need `user`. Adding, removing and changing the primary address are **browser session** routes.

| Route | What it does |
| --- | --- |
| `GET /api/me/emails` | Your addresses, primary first, as `[{ "id", "address", "primary", "verified" }]`. |
| `POST /api/me/emails` | **Browser session.** Add an address with `{ "address": "me@example.com" }`. Answers 201 and mails a link that works for 24 hours. 422 for an invalid address. 409 when it is already yours or in use. 503 or 502 when mail is not configured or could not send. The address is still added. |
| `DELETE /api/me/emails/{id}` | **Browser session.** Remove an address. 204. 422 for the primary address, so make another primary first. |
| `POST /api/me/emails/{id}/primary` | **Browser session.** Make a verified address primary. Answers the updated list. 422 for an unverified address. |
| `POST /api/me/emails/{id}/resend` | Send a new verification link. 204. 409 when already verified. 429 with `Retry-After` when one went out less than a minute ago. |

An unknown id is 404 for every route that takes one.

## Blocks

Blocking a person keeps them out of all your personal repositories. They can still read public code, but they cannot open issues or pull requests, comment, or be invited. Blocking also ends their collaborations and invitations on your repositories. All three routes need `user`. Organizations block people with their own routes, see [the organizations API](https://sailfork.com/docs/api-orgs).

| Route | What it does |
| --- | --- |
| `GET /api/me/blocks` | The people you blocked, newest first, as `[{ "handle", "name", "avatarUrl", "blockedBy", "at" }]`. |
| `PUT /api/me/blocks/{handle}` | Block a person. Answers the updated list. 422 for yourself or an unknown handle. Blocking someone already blocked changes nothing. |
| `DELETE /api/me/blocks/{handle}` | Unblock. 204. 404 when they were not blocked. |

```sh
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" https://sailfork.com/api/me/blocks/spammer
```

## Security

### Security log

```http
GET /api/settings/security-log?before=&limit=
```

Needs `user`. Your sign-ins, SSH key and token creation and use, and second-factor changes, newest first.

| Query | Type | Meaning |
| --- | --- | --- |
| `limit` | integer | 1 to 200, default 50. |
| `before` | integer | The `next` of the previous page, in microseconds. A bad value is 422. |

```json
{
  "events": [
    { "at": "2026-11-09T21:00:00Z", "kind": "sign-in", "actor": "Fenil Sonani", "text": "Signed in on Safari on macOS" }
  ],
  "next": 1794258000000000
}
```

`kind` is `sign-in`, `key` or `passkey`. `next` is `null` on the last page.

### Audit log of your repositories

```http
GET /api/me/audit?before=&limit=
```

Needs `user`. Moderation and access changes on your personal repositories, and the people you blocked, newest first. `limit` is 1 to 200, default 50. `before` is the `next` of the previous page, an opaque string. Organizations have their own audit log, see [the organizations API](https://sailfork.com/docs/api-orgs).

```json
{
  "events": [
    {
      "id": "2f1c8d56-7a3e-4f0b-9d1a-5c6b7e8f9a01",
      "at": "2026-11-08T10:12:00Z",
      "kind": "moderation",
      "actor": "Fenil Sonani",
      "agent": false,
      "text": "Blocked spammer",
      "action": "user.block",
      "target": "spammer",
      "meta": {}
    }
  ],
  "next": null
}
```

### Account snapshot

```http
GET /api/settings/account
```

Needs `user`. Everything the settings page shows in one response: profile fields, `emails`, `passkeys`, whether an `authenticator` is on, `sessions`, `keys`, `tokens`, notification settings, `deletionAt` and a short `securityLog`. Each session is `{ id, device, where, lastSeen, current }`, and `current` marks the one making the request. Use this to find a session id for the routes below.

### Sessions

Both routes are **browser session** routes and answer 204.

| Route | What it does |
| --- | --- |
| `DELETE /api/sessions/{id}` | Sign out one of your own sessions. 404 for an unknown id or another person's session. |
| `DELETE /api/sessions?others=true` | Sign out every session except the current one. 422 without `others=true`. |

### Passkeys

Passkeys are WebAuthn credentials, so adding one needs a browser. Listing needs `user`. The rest are **browser session** routes. Names are 1 to 64 characters.

| Route | What it does |
| --- | --- |
| `GET /api/me/passkeys` | Your passkeys as `[{ "id", "name", "added", "lastUsed" }]`. |
| `POST /api/me/passkeys/register/start` | Starts a registration. Answers `{ "challenge", "options" }`, where `options` goes to `navigator.credentials.create`. |
| `POST /api/me/passkeys/register/finish` | Finishes it with `{ "challenge", "name"?, "credential" }`. Answers 201 `{ "passkey", "recoveryCodes"? }`. `recoveryCodes` is present when this is your first second factor, and it is shown once. 409 for a passkey already registered. |
| `PATCH /api/me/passkeys/{id}` | Rename with `{ "name" }`. Answers the passkey. |
| `DELETE /api/me/passkeys/{id}` | Remove a passkey. 204. 409 when an organization of yours requires two-factor authentication and this is your last second factor. |

### Authenticator app and recovery codes

These are **browser session** routes. Sign-in with a second factor is not part of this reference.

| Route | What it does |
| --- | --- |
| `POST /api/me/totp/setup` | Starts setup. Answers `{ "secret", "otpauthUrl", "qrSvg" }`. 409 when the app is already on. |
| `POST /api/me/totp/enable` | Turns it on with `{ "code": "123456" }` from the app. Answers `{ "recoveryCodes": [...] }`, shown once. 422 for a wrong code or when setup was not started. 409 when already on. |
| `DELETE /api/me/totp` | Turns it off. Send exactly one of `{ "code" }` or `{ "recoveryCode" }`. 204. 422 for a wrong code. 409 when the app is off, or an organization of yours requires two-factor authentication and this is your last second factor. |
| `POST /api/me/recovery-codes` | Replaces your recovery codes and answers `{ "recoveryCodes": [...] }`. 409 until you have a passkey or the authenticator app. |

## Preferences

Both routes need `user`. The `PUT` replaces the whole object, so read it first and change what you need.

### Notification settings

```http
GET /api/settings/notifications
PUT /api/settings/notifications
```

```json
{
  "notifications": { "approval": true, "review": true, "checks": true, "mention": true },
  "quietHours": { "on": false, "from": "20:00", "to": "08:00" },
  "email": {
    "classes": {
      "decision": "now",
      "people": "now",
      "failure": "digest",
      "progress": "off",
      "security": "now",
      "billing": "now"
    },
    "digestHour": 9,
    "people": true,
    "agents": {}
  },
  "issues": { "forYou": "email", "following": "inbox", "agents": "inbox", "autoFollow": true }
}
```

| Field | Meaning |
| --- | --- |
| `notifications` | Which kinds reach the inbox. |
| `quietHours` | When `on`, mail waits until `to`. Times are `HH:MM` in your time zone. |
| `email.classes` | When each class of mail goes: `now`, `digest` or `off`. `security` and `billing` must stay `now`. |
| `email.digestHour` | The hour of the daily digest, 0 to 23. |
| `email.people` | Mail from people, as opposed to agents. |
| `email.agents` | Per agent name, `false` blocks its mail. At most 50 names of 1 to 64 characters. |
| `issues` | Where issue news goes: `off`, `inbox`, `email` or `digest`. Only `forYou` can be `digest`. `autoFollow` follows an issue when you comment on it. |

The body must match this shape. A missing or unknown field, a bad time, or a rule above that is broken is 422.

### Caisson rules

Your personal caisson rules are in [the caissons API](https://sailfork.com/docs/api-caissons).

## Usage and billing

Your personal account has the same reads as an organization. The shapes are in [the organizations API](https://sailfork.com/docs/api-orgs). Starting a payment goes through the billing page, not the API.

| Route | What it does |
| --- | --- |
| `GET /api/settings/usage?month=YYYY-MM` | Needs `user`. Your usage for the month, in the shape of [the organization usage](https://sailfork.com/docs/api-orgs). `month` defaults to the current UTC month, and a bad value is 422. |
| `GET /api/settings/billing` | Needs `user`. Your plan, billing cycle, storage, invoices and `payments`, in the shape of [the organization billing](https://sailfork.com/docs/api-orgs). It has `receiptsTo`, the address that gets receipts, instead of `billingEmails`, and no `seats`. |
| `PUT /api/settings/billing/plan` | **Browser session.** Body `{ "plan": "free" }`, `"pro"` or `"max"`. Anything else is 422. Answers `{ plan, pendingPlan, pendingPlanAt }`. A downgrade stays pending until the paid cycle ends. A move that needs a payment is 409. |
| `PUT /api/settings/billing/receipts` | Needs `user`. Body `{ "email": "me@example.com" }`, one of your verified or primary addresses, else 422. Answers `{ "receiptsTo": "me@example.com" }`. |

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" "https://sailfork.com/api/settings/usage?month=2026-11"
```

## CLI sign-in

`sailfork auth login` uses these routes to get a token named `CLI on <name>`. You only call them if you build your own CLI. [The CLI guide](https://sailfork.com/docs/cli) covers the command. Both flows end in a token that expires in 90 days once confirmed. Either token request can carry `replaces`, the id of an older token this login supersedes. The server deletes only that token, and only when it is yours.

| Route | What it does |
| --- | --- |
| `POST /api/cli/device` | No auth. Starts the device flow with `{ "name", "scopes"? }`. `name` is 1 to 64 characters. `scopes` are scope names, and all of them when omitted. An unknown scope is 422. Answers `deviceCode`, `userCode` (like `BDFG-HJKL`), `verificationUri`, `verificationUriComplete`, `interval` (seconds between polls) and `expiresIn` (seconds). |
| `GET /api/cli/device?code=XXXX-XXXX` | **Browser session.** What the pending login asks for: `{ "name", "scopes" }`. 404 when unknown or expired. |
| `POST /api/cli/authorize` | **Browser session.** Approves a login. `{ "kind": "device", "userCode" }` answers the pending login. `{ "kind": "browser", "challenge", "name", "scopes"? }` answers `{ "code" }` that lives 10 minutes. `challenge` is the base64url SHA-256 of your verifier, 43 characters. 404 for an unknown or expired code. |
| `POST /api/cli/token` | No auth. Exchanges `{ "deviceCode" }` or `{ "code", "verifier" }` for `{ "token", "tokenId", "handle", "scopes" }`. Single use. With `"confirm": true` the token expires in 10 minutes unless confirmed. |
| `POST /api/cli/token/confirm` | Authenticated with the unconfirmed token itself. Makes it live for 90 days and revokes `replaces` if sent. Answers `{ "confirmed": true }`. |

`POST /api/cli/token` answers 400 `{ "error": "<code>" }` until the grant succeeds. The codes are `authorization_pending` (keep polling), `slow_down` (poll less often), `expired_token` and `invalid_grant`. The device start and the token exchange are rate limited per client address, and past the limit they answer 429.

```sh
curl -X POST -H "Content-Type: application/json" \
  -d '{"name":"my-laptop","scopes":["repo:read","repo:write"]}' https://sailfork.com/api/cli/device
```

## Remote MCP and OAuth

The remote MCP server gives an assistant the same tools as `sailfork mcp`, with each call made as you. [The MCP guide](https://sailfork.com/docs/mcp) explains how to connect a client. This section lists the endpoints for client authors.

The server speaks Streamable HTTP MCP. Each path takes `POST`, `GET` and `DELETE`.

| Path | Tools |
| --- | --- |
| `/mcp` | Every tool. |
| `/mcp/readonly` | Read-only tools. |
| `/mcp/x/{toolsets}` | Only these toolsets, comma separated: `caissons`, `issues`, `pulls`, `ci`, `repos`, `drydock`, `context`. 404 for an unknown one. |
| `/mcp/x/{toolsets}/readonly` | The read-only tools of those toolsets. |

Send `Authorization: Bearer` with an OAuth access token issued for that endpoint (or one above it) or a personal access token. An OAuth token works on `/mcp` only and is 401 `invalid_token` anywhere else.

| Status | When |
| --- | --- |
| 401 | The credential is missing or bad. `WWW-Authenticate` points to the protected-resource metadata and names the scopes `mcp:read mcp:write`. |
| 403 | A tool that changes data was called with an `mcp:read` token (`insufficient_scope`), or the `Origin` is foreign. |
| 413 | A body over 8 MiB. |
| 429 | Over 600 requests a minute for one token. Wait for `Retry-After`. |

### OAuth endpoints

Clients find these through the metadata routes. PKCE with `S256` is required.

| Route | What it does |
| --- | --- |
| `GET /.well-known/oauth-protected-resource` and `/.well-known/oauth-protected-resource/{path}` | RFC 9728 metadata: `resource`, `authorization_servers`, `scopes_supported`. The path form names one MCP endpoint. |
| `GET /.well-known/oauth-authorization-server` | RFC 8414 metadata. Supports client ID metadata documents. |
| `POST /api/oauth/register` | RFC 7591 dynamic client registration. No auth. Answers 201 with the client. 20 a minute per address. |
| `GET /api/oauth/authorize?<request>` | **Browser session.** Previews the consent screen: the client, redirect, access and your account. A bad request is 400 `{ "error", "error_description", "redirect"? }`. |
| `POST /api/oauth/authorize` | **Browser session.** Approves or denies with `{ ...request, "approve": true, "access"?: "read" \| "write", "repos"?: ["owner/name"] }`. Answers `{ "redirect": "..." }`. `access: "read"` grants less than asked. `repos` limits the grant like it does on `POST /api/tokens`. Rate limited. |
| `POST /api/oauth/token` | Form encoded. `grant_type=authorization_code` with `code`, `redirect_uri`, `code_verifier`, `client_id`, `resource`, or `grant_type=refresh_token` with `refresh_token`, `client_id`, `resource`, `scope`. Answers `access_token`, `token_type`, `expires_in` (3600), `refresh_token` and `scope`. Each refresh replaces both tokens. Presenting a replaced refresh token revokes the grant. Errors are RFC 6749 JSON. |
| `POST /api/oauth/revoke` | Form encoded `token` and `client_id`. RFC 7009. Either token ends the grant. Answers 200. |

A grant shows up in `GET /api/tokens` with the client's name. Deleting that token revokes it.

## Sync socket

```http
GET /api/sync
```

This WebSocket feeds the Sailfork web app, which keeps its data in the browser and applies changes optimistically. It is app-internal. The row shapes follow the site's own models and can change, so do not build on it. Use the REST routes in this reference instead. The protocol is described here so you can tell what the site is doing.

The connection authenticates with the browser session. A signed-out visitor connects as a guest, receives public repositories, and has every transaction rejected. Messages are JSON text frames of at most 1 MiB.

1. The client sends `{ "type": "hello", "lastSyncId": 0, "viewer": "..." }` with the last sync id it has, 0 on first load, and the viewer its rows were loaded for.
2. The server answers `bootstrap` (`syncId`, `rows`, `viewer`) when the client starts fresh, its id is too old, or it was loaded for another viewer. Otherwise it answers `delta` with every change since.
3. The server pushes `delta` (`changes`) for each later change, in order, to every connected client allowed to see it.
4. The client sends `{ "type": "tx", "id": "...", "mutations": [...] }` for its own changes. The server answers `ack` (`txId`, `syncId`) or `reject` (`txId`, `error`), and the client reverts the change on a reject.

A mutation has a `kind`, such as `issue.create`, `issue.update`, `issue.comment`, `pull.create`, `pull.merge` or `thread.reply`, and each kind has its own permission rule.

---

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