# Repositories API

Create, read, change, protect and share repositories over REST, and read their commits, files, branches and diffs.

These routes cover a repository itself and its git data. Authentication, token scopes, the error shape and paging are in the [REST API overview](https://sailfork.com/docs/api); this page links to them instead of repeating them. Git clone and push use smart HTTP and SSH, not these routes: see [Git access](https://sailfork.com/docs/git-access).

Conventions on this page:

- `{owner}` is a person or an organization, `{repo}` the repository name. Names are case-insensitive.
- `{ref}` is one path segment: a branch, tag or commit. Write a slash in a branch name as `%2F`, for example `feat%2Fx`.
- Reads on a public repository work without a token. A private repository you cannot read answers 404.
- Reads need `repo:read` when you use a token. Where a route needs more, the table or text says so. See [token scopes](https://sailfork.com/docs/api#token-scopes).

## Repositories

### List your repositories

```http
GET /api/repos
```

Your own repositories and those of your organizations, newest first. Needs `repo:read`. The response is an array of repository objects (see below).

### Create a repository

```http
POST /api/repos
```

Needs `repo:admin`. The owner is you, or the organization named in `org` when you belong to it.

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string, required | 1 to 100 characters of letters, digits, `-`, `_` or `.`. Must not end in `.git`. |
| `visibility` | `"public"` or `"private"`, required | |
| `about` | string, optional | At most 350 characters. |
| `org` | string, optional | Handle of an organization you belong to. |
| `readme` | string, optional | At most 64 KiB. Becomes `README.md` in the first commit on `main`. |

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"ocean-landing","about":"Landing page","visibility":"public","readme":"# Ocean\n"}' \
  https://sailfork.com/api/repos
```

Answers 201 with the repository. It answers 409 when the owner already has that name, or the name is still held by a repository that moved away. It answers 404 when you are not a member of `org`, and 403 when the organization requires a second factor you have not set up. A bad name or field is 422.

### Get a repository

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

The repository with its branches, clone addresses and your access. The response carries an `ETag`; send it back as `If-None-Match` for a 304. A renamed account's old handle answers 301 with a `Location` to the current path.

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

```json
{
  "owner": "fenil",
  "name": "ocean-landing",
  "about": "Landing page",
  "visibility": "public",
  "defaultBranch": "main",
  "branches": ["main", "tide-fix"],
  "branchCount": 2,
  "branchesDigest": "6f1c0a",
  "cloneUrl": "https://git.sailfork.com/fenil/ocean-landing.git",
  "sshUrl": null,
  "head": "9b2c4e7d1a0f5c3e8b6a4d2f0c1e9a7b5d3f1e0c",
  "access": "admin",
  "storageBytes": 48213
}
```

| Field | Meaning |
| --- | --- |
| `branches` | The first 100 branch names, sorted. [List branches](#list-branches) pages through all of them. |
| `branchCount` | Every branch, contribution branches left out. |
| `branchesDigest` | Changes when a branch is added or removed, not when one moves. |
| `head` | Full sha of the default branch. `null` before the first push. |
| `sshUrl` | `null` when SSH is off. |
| `access` | Your effective access: `read`, `write` or `admin`. `read` when signed out. |
| `mirrorOf` | Present on a pull mirror: the remote it follows. The repository is read-only. |
| `itemsMirrored` | Present when that mirror also brings pull requests and issues, which are then read-only too (writes answer 403). |
| `blocked` | Present when the owner blocked you: you can read but not open or comment on issues and pull requests. |
| `contributions` | On a public repository, your own `contrib/<handle>/` branches, which `branches` leaves out. |

### Change a repository

```http
PATCH /api/repos/{owner}/{repo}
```

Needs `repo:admin` and admin access on the repository. Send exactly one of `about` (at most 350 characters), `visibility`, or `defaultBranch` (an existing branch). Answers with the repository. Anything else is 422.

### Delete and restore a repository

```http
DELETE /api/repos/{owner}/{repo}
DELETE /api/repos/{owner}/{repo}/deletion
```

Both need `repo:admin` and admin access.

The first schedules deletion 14 days out and hides the repository at once: reads, pushes and listings answer 404. It answers 200 with `{ "deletionAt": "2026-11-24T18:02:11Z" }`. Scheduling again keeps the first date. After the date an hourly job deletes the git data and the row.

The second restores a repository before that purge and answers 200 with `{ "restored": true }`, or `{ "restored": false }` when the repository was not scheduled for deletion. It is recorded in the organization audit log, or in the owner's security events for a personal repository.

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

Purges a repository scheduled for deletion now instead of at its date, with the same `repo:admin` and admin access: every stored object, then the row. It answers 200 with `{ "purged": true }` and cannot be undone. It answers 409 when the repository is not scheduled for deletion or is under a legal hold, and 503 when its data cannot be deleted at that moment (it is then left due, and the hourly job finishes it). It is recorded as `repo.deletion.purge`, like scheduling and restoring.

### Transfer a repository

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

Body: `{ "to": "acme" }`. `to` is an organization you belong to, or your own handle to move a repository out of an organization. Answers with the repository under its new owner. Pull requests, issues and threads follow it, and a transfer clears any pin.

You must be an admin of the repository, and the call needs a browser session: a token answers 403. It answers 409 when the new owner already has a repository with that name, 422 for a bad `to`, and 403 when the target organization requires a second factor you have not set up.

### Pin a repository

```http
GET    /api/repos/{owner}/{repo}/pin
PUT    /api/repos/{owner}/{repo}/pin
DELETE /api/repos/{owner}/{repo}/pin
```

A pinned repository shows on its owner's page, up to 6 per owner.

- `GET` returns `{ "pinned": true, "canPin": true }` to anyone who can see the repository, with `repo:read`. `canPin` is false when signed out.
- `PUT` pins and returns the same object. `DELETE` unpins and answers 204. Both are idempotent and need `repo:admin`. Only the owner of a personal repository, or an owner of the organization, may pin: others get 403. A seventh pin is 422.

### List a person's repositories

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

Needs `repo:read`, or no token for public data. The person's own repositories, not their organizations', newest push first. Private ones show only to the person. Repositories scheduled for deletion are left out. An organization handle is 404.

```json
[
  {
    "name": "ocean-landing",
    "about": "Landing page",
    "visibility": "public",
    "archived": false,
    "language": "Svelte",
    "crewShare": 0.4,
    "openPulls": 2,
    "openIssues": 5,
    "pushedAt": "2026-11-09T21:14:03Z"
  }
]
```

`openPulls` counts open and draft pull requests.

### Look up an owner

```http
GET /api/owners/{name}
```

One call that tells a person from an organization, for the first segment of a path. An old handle of a renamed account answers with the current one. It is 404 only when no user or organization has that name.

```json
{ "kind": "user", "handle": "fenil", "name": "Fenil Sonani" }
```

For an organization the answer is `{ "kind": "org", "handle": "acme", "org": { ... } }` with the organization's profile.

## Commits and tags

### List commits

```http
GET /api/repos/{owner}/{repo}/commits?ref=&path=&limit=&skip=
```

Commits, newest first.

| Parameter | Type | Notes |
| --- | --- | --- |
| `ref` | string, optional | Branch, tag or sha. Defaults to the default branch. |
| `path` | string, optional | Only commits touching this path, as `git log -- <path>` lists them: history-simplified, so a merge that equals one parent for the path follows only that parent and a branch it did not take is not listed, and a merge is listed when it differs from every parent. A file that was deleted and added again lists its earlier life too, a path that is gone at `ref` lists the commit that deleted it, and a file added by renaming another carries on under the old name (each commit's `path` says which name it had). Commits made on one second are in no fixed order among themselves. |
| `limit` | integer, optional | Page size. |
| `skip` | integer, optional | Drops that many newest commits, to page. |

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://sailfork.com/api/repos/fenil/ocean-landing/commits?ref=main&limit=1"
```

```json
[
  {
    "sha": "9b2c4e7d1a0f5c3e8b6a4d2f0c1e9a7b5d3f1e0c",
    "short": "9b2c4e7",
    "author": "Fenil Sonani",
    "email": "fenil@example.com",
    "at": "2026-11-09T21:14:03Z",
    "subject": "fix tide math",
    "added": 12,
    "removed": 3,
    "files": 2
  }
]
```

`added`, `removed` and `files` count the commit's diff against its first parent. With `path`, each commit also has `path`, the file's name in that commit, which differs from the requested one before a rename.

### Get a commit

```http
GET /api/repos/{owner}/{repo}/commit/{sha}
```

Returns `{ commit, body, files, parent, child }`. `body` is the message after the subject. `files` holds a diff per file: `path`, `from`, `status` (`added`, `deleted`, `modified` or `renamed`), `added`, `removed`, `binary`, `hunks` and `truncated`. Each hunk has a `header` and `lines`, and each line has `kind` (`add`, `del` or `ctx`), `text`, and `old` and `new` line numbers (or `null`). `parent` and `child` are neighboring commits or `null`.

### List pull requests that include a commit

```http
GET /api/repos/{owner}/{repo}/commit/{sha}/pulls
```

Returns `{ "items": [Pull] }`: pull requests whose commits include `sha`, newest first, at most 20. Open, draft and closed ones match by their branch's commits as they stand; a merged one by the range recorded at merge. Only the newest 100 pull requests are searched. The list is empty when none match, and 404 for an unknown commit.

### List tags

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

Tags, newest commit first, at most 100. `[]` before the first push. For published releases see the [Releases API](https://sailfork.com/docs/api-releases).

```json
[{ "name": "v1.2.0", "sha": "9b2c4e7d1a0f5c3e8b6a4d2f0c1e9a7b5d3f1e0c", "at": "2026-11-09T21:14:03Z" }]
```

`sha` is the commit the tag points at; annotated tags are peeled. `at` is that commit's time.

## Files

### Get a folder

```http
GET /api/repos/{owner}/{repo}/tree/{ref}
GET /api/repos/{owner}/{repo}/tree/{ref}/{path}
```

The entries of a folder, the root when `path` is left out. Returns `{ ref, sha, path, entries, commit }`. Each entry has `name`, `path`, `dir`, `size` (`null` for folders) and `commit`, the last commit that touched it. A `path` that is a file is 404.

A page holds at most 1,000 entries, folders first and then by name. When there are more, the reply has `next`: send it back as `?after=` to get the entries that follow, with `sha` from the first page as `{ref}` so every page is of one commit.

### Get a file

```http
GET /api/repos/{owner}/{repo}/blob/{ref}/{path}
```

Returns `{ ref, sha, path, size, binary, tooLarge, text, preview, history, version }`. `tooLarge` is true for a file over 10 MiB. `text` is `null` when the file is binary or too large. For a text file that is too large, `preview` holds its first 256 KiB, possibly cut mid-line; otherwise it is `null`. `history` is always `null` here; read [List commits](#list-commits) with `path` for it. `version` is the blob id: pass it as `expect` when you [commit a file](#commit-a-file).

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  https://sailfork.com/api/repos/fenil/ocean-landing/blob/main/README.md
```

### Get raw file bytes

```http
GET /api/repos/{owner}/{repo}/raw/{ref}/{path}?download=1
```

The file's bytes, of any size: a large file is streamed as it is read. A folder or missing path is 404.

- **Content type.** Images (png, apng, jpeg, gif, webp, avif, bmp, ico, svg) are served as themselves, `.pdf` as `application/pdf`, other text as `text/plain` and other binaries as `application/octet-stream`. Replies are `nosniff` with a sandboxed content security policy, so committed HTML or SVG never runs script.
- **Caching.** The `ETag` is the blob id; `If-None-Match` answers 304 without reading the blob. Reads of a full commit id are immutable.
- **Ranges.** Send one `Range: bytes=a-b`, `bytes=a-` or `bytes=-n` for a 206 with `Content-Range`. A range past the end is 416. Several ranges, or an `If-Range` other than the current `ETag`, return the whole file.
- **Download.** `download=1` sends `Content-Disposition: attachment`; otherwise it is inline.

### Blame a file

```http
GET /api/repos/{owner}/{repo}/blame/{ref}/{path}
```

Who last changed each line, as `git blame`. Returns `{ ref, sha, path, lines, commits, ranges }`. `commits` lists each blamed commit once, with `previous` and `previousPath` (blame that commit to go back; `previous` is `null` when the commit added the file). `ranges` cover lines 1 to `lines` in order: `{ start, lines, commit, from }`, where `commit` indexes `commits` and `from` is the first line in that commit's version.

It answers 422 for a binary file or one over 1 MiB, and 404 for a folder or missing path.

### List every file

```http
GET /api/repos/{owner}/{repo}/files/{ref}
```

Returns `{ ref, sha, files: [{ path, size }] }`: every file path at the ref, sorted, with sizes in bytes. Only the first 100,000 paths (the server's `SAILFORK_FILE_SIZES_MAX`) get a size; the rest, and any size the server could not read, are `null`.

### Commit a file

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

Commits one file change as you, like a push: the push hook, mirrors and CI all run. Needs `repo:write` and write access.

| Field | Type | Notes |
| --- | --- | --- |
| `branch` | string, required | The branch to commit to. |
| `path` | string, required | The file. |
| `content` | string or `null`, required | `null` deletes the file. |
| `expect` | string or `null`, required | The `version` of the file you started from. `null` says the file must not exist yet. |
| `message` | string, required | 1 to 65,536 bytes. |
| `newBranch` | string, optional | Commit onto this new branch instead of `branch`. |
| `base` | string, optional | With `newBranch`: the commit it starts from. |

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"branch":"main","path":"docs/tides.md","content":"# Tides\n","expect":null,"message":"add tides page"}' \
  https://sailfork.com/api/repos/fenil/ocean-landing/contents
```

```json
{ "sha": "c41d7f09e2b35a68f0d19c7e4b2a8d6f3e1c5b70", "branch": "main", "path": "docs/tides.md" }
```

| Status | Meaning |
| --- | --- |
| `201` | Committed. |
| `403` | The branch's rules refuse it, the new content would pass the plan's storage limit, or a [protected path](#protected-paths) covers the file on a direct commit. A new branch takes the change to a pull request instead. |
| `409` | `newBranch` exists, nothing changed, or the file on the branch is not `expect`. The last case carries `code: "file_changed"` with `sha` and `version`, and overwrites nothing. |
| `413` | Over 1 MiB. |
| `422` | A bad path, a link, a folder, a bad branch name or an empty message. |
| `451` | The repository is disabled. |

### Check whether you can commit directly

```http
GET /api/repos/{owner}/{repo}/contents/check?branch=&path=
```

Needs `repo:write`. Returns `{ "direct": false, "reason": "main requires a pull request" }`. `direct` is true when you may commit straight to `branch`; otherwise `reason` says why.

## Comparisons

### Compare two refs

```http
GET /api/repos/{owner}/{repo}/compare/{base}...{head}
```

Commits on `head` since the merge base (newest first, at most 250) and the diff from the merge base to `head`. Returns `{ ahead, behind, commits, files }`; `ahead` and `behind` stay exact past the cap.

| Query | Effect |
| --- | --- |
| `lines=N` | Every file with its totals, but hunks only for the leading files whose changed lines, counted in order, start within `N`. Later files with line changes have `hunks: []` and `pending: true`. The body adds `base` and `head`, the commits compared. |
| `from=I&count=C` | Files `I` to `I+C` of that list, with hunks: `{ from, files }`. `C` is 1 to 100, else 422. Use the full shas from `base` and `head` so every page reads the same diff after a branch moves; those answers are immutable. |

Sending `lines` together with `from` or `count` is 422. For the comparison of a pull request, see the [Pull requests API](https://sailfork.com/docs/api-pulls).

### Check for merge conflicts

```http
GET /api/repos/{owner}/{repo}/conflicts/{base}...{head}
```

Whether `head` merges into `base` file by file, without reading the diff. Returns `{ "behind": 3, "conflicts": ["src/tide.ts"] }`. `behind` counts base commits since the fork. `conflicts` lists, sorted, the files both sides changed to contents Sailfork cannot combine; those are the files that make a merge refuse.

## Branches

### List branches

```http
GET /api/repos/{owner}/{repo}/branches?q=&after=&limit=
GET /api/repos/{owner}/{repo}/branches?names=a:b
```

Branches in name order, contribution branches left out. Readable by anyone who can read the repository.

| Parameter | Notes |
| --- | --- |
| `q` | Keeps names containing it, in any case. |
| `after` | The previous page's `next`. |
| `limit` | Default 100, at most 10,000. |
| `names` | Colon-separated branch names (a branch name cannot hold `:`). Returns those that exist. At most 100, else 422. |

```json
{ "names": ["main", "tide-fix"], "next": null, "total": 2 }
```

`total` counts every match across pages.

### Compare branches to the default branch

```http
GET /api/repos/{owner}/{repo}/divergence?recent=&names=
```

Every branch, sorted by name, with its tip and how far it is ahead of and behind the default branch (which reads 0 and 0). It is read from stored counts, so no history is walked. The path is not under `/branches` because that prefix takes a branch name.

```json
[
  {
    "name": "tide-fix",
    "head": { "sha": "c41d7f09e2b35a68f0d19c7e4b2a8d6f3e1c5b70", "short": "c41d7f0", "author": "Fenil Sonani", "at": "2026-11-09T21:14:03Z", "subject": "fix tide math" },
    "ahead": 2,
    "behind": 0,
    "stale": false
  }
]
```

A background worker refreshes the counts after any ref change. Until it has, `stale` is true and `ahead` and `behind` are the last stored values, or `null` when the branch has none yet. While `stale`, do not treat a count as settled. `head` is always the current tip.

- `recent=N` (at most 100) answers only the N newest branches ahead of the default branch, newest first.
- `names=a:b` (at most 100 names) answers only those branches.

### Delete a branch

```http
DELETE /api/repos/{owner}/{repo}/branches/{name}
```

What `git push --delete` does. Needs `repo:write` and push access. Answers 204. The push hook then runs as for a push. Slashes in `name` may be written as is.

| Status | Meaning |
| --- | --- |
| `403` | The branch is protected, or the repository is a pull mirror. |
| `404` | No such branch. |
| `409` | It is the default branch (change that first), or the branch moved while being deleted. Look again and retry. |

## Protection and rules

All four resources use the same shape: `GET` needs `repo:read`, `PUT` needs `repo:admin` and admin access, and `PUT` replaces the whole stored value.

### Branch protections

```http
GET /api/repos/{owner}/{repo}/branch-protections
PUT /api/repos/{owner}/{repo}/branch-protections
```

Body and response: `{ "rules": [BranchRule], "privateContributions": false }`, at most 50 rules. Rules apply to pushes over HTTP and SSH and to branch deletion. A `PUT` replaces every rule; leave `privateContributions` out to keep it as it is.

With `privateContributions` on, outside contributors' `contrib/<handle>/` branches are readable by their contributor and the repository's admins alone. A pull request opened from one still shows its head, CI runs and events. Off, the default, anyone who can read the repository can fetch them.

| Field | Type | Notes |
| --- | --- | --- |
| `pattern` | string | A glob over the branch name. `*` stops at `/`. |
| `blockForcePush` | boolean | |
| `blockDeletion` | boolean | |
| `requirePullRequest` | boolean | Admins skip this one. |
| `requiredChecks` | string[], optional | CI checks that must pass on a pull request's head before it merges into a matching branch: a workflow name (its latest run on the head passed) or a job name or id (that job passed in its workflow's latest run). A refused merge says `merge rules not met: required check X ...`. At most 50 checks of 1 to 200 characters. |
| `requireOwners` | boolean, optional | A pull request into the branch needs the approvals the `OWNERS` files of its base ask for. See [Owners files](https://sailfork.com/docs/branches#owners-files). |
| `pushPeople`, `pushTeams` | string[], optional | When either is set, only these people and members of these teams (with write access) push to the branch. Admins are not exempt. |
| `mergePeople`, `mergeTeams` | string[], optional | The same for merging a pull request into the branch. |
| `content` | object, optional | What a push may contain: `secrets`, `signedCommits` and `verifiedEmail` (booleans), `blockedPaths` and `blockedExtensions` (string lists), and `maxFileBytes` (a number or null). |
| `readersPeople` | string[], optional | Handles that may read the branches the rule matches. A rule with readers makes them private: only those people, members of `readersTeams` and the repository's admins can see, fetch or search them, and pull requests, CI runs and events from them are hidden from everyone else. At most 100 entries. |
| `readersTeams` | string[], optional | Team slugs of the repository's org; members of a child team count. Not allowed on a personal repository or in org rulesets. |

```sh
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"rules":[{"pattern":"main","blockForcePush":true,"blockDeletion":true,"requirePullRequest":true,"requiredChecks":["ci"]}]}' \
  https://sailfork.com/api/repos/fenil/ocean-landing/branch-protections
```

### Protected paths

```http
GET /api/repos/{owner}/{repo}/protected-paths
PUT /api/repos/{owner}/{repo}/protected-paths
```

Body and response: `{ "paths": [ProtectedPath] }`, at most 100. Enforced when a pull request merges.

| Field | Type | Notes |
| --- | --- | --- |
| `glob` | string | The paths covered. |
| `teams` | string[] | Organization team slugs. |
| `people` | string[] | Handles. |
| `locked` | boolean | |

One approval from any listed team member or person is required.

### Release rules

```http
GET /api/repos/{owner}/{repo}/release-rules
PUT /api/repos/{owner}/{repo}/release-rules
```

Body: `{ forcePush, pushTeam, tagsCreatedBy, enforce }`, and `approvals`, which is kept and returned but not used. `tagsCreatedBy` is `"workflow"` or a team slug, and `pushTeam` is a team slug or empty. Nothing is checked until `enforce` is `true`. Then a push creates a tag only for members of `pushTeam` or `tagsCreatedBy` (anyone who can write when neither is set), and moves or deletes an existing tag only when `forcePush` is `true`. The response adds `enforced`, which repeats `enforce`. See [Tag protection](https://sailfork.com/docs/branches#tag-protection).

### Merge queue

```http
GET /api/repos/{owner}/{repo}/merge-queue
PUT /api/repos/{owner}/{repo}/merge-queue
```

Body: `{ on, batch, maxWaitMinutes, recheck, autoEnqueueAgents, maxInFlight }`. `batch` is 1 to 10, `maxWaitMinutes` 1 to 120 and `maxInFlight` 1 to 32 (4 when never set; leave it out to keep the stored value). With `on`, the default branch takes merges only from the queue. `maxWaitMinutes` and `autoEnqueueAgents` are kept and returned, and the queue does not use them yet. The response adds `"enforced": true`. See [Merge queue](https://sailfork.com/docs/branches#merge-queue).

### Merge rules

```http
GET    /api/repos/{owner}/{repo}/merge-rules
PUT    /api/repos/{owner}/{repo}/merge-rules
DELETE /api/repos/{owner}/{repo}/merge-rules
```

What a pull request needs before it merges into this repository. A repository inherits its organization's rules (see the [Organizations API](https://sailfork.com/docs/api-orgs)) until you set an override here.

- `GET` needs `repo:read`, or no token on a public repository. It returns `{ "rules": Rules, "source": "repo" }`. `source` is `repo` for an override, `org` when inherited and `default` when nothing is set.
- `PUT` needs `repo:admin` and admin access. It stores an override and returns the same shape. Unknown fields are 422.
- `DELETE` needs `repo:admin` and admin access. It removes the override and answers 204, or 404 when there is none.

| Field | Type | Notes |
| --- | --- | --- |
| `approvals` | integer | People other than the author whose latest review approves. 0 to 6, else 422. |
| `dismissStale` | boolean | A push to the branch after an approval voids it. |
| `upToDate` | boolean | The branch must contain the base branch's tip. |
| `threadsResolved` | boolean | Every comment thread on a line of code must be resolved. |
| `selfReview` | boolean | The author must approve their own pull request (a self-review, which never counts toward `approvals`). Optional, defaults to `false`. |

```sh
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"approvals":1,"dismissStale":true,"upToDate":false,"threadsResolved":true,"selfReview":false}' \
  https://sailfork.com/api/repos/fenil/ocean-landing/merge-rules
```

## Mirrors

A mirror keeps a repository in step with a remote. A push mirror sends branches and tags to the remote; a pull mirror follows a remote and makes the repository read-only. Mirrors are managed by repository admins. Every route here needs `repo:admin` plus admin access, except [List mirror accounts](#list-mirror-accounts), which needs `user`. The routes answer 503 when the server runs without mirrors.

A mirror object looks like this.

```json
{
  "id": "2c9f6a10-7b3e-4d58-a1c4-0e5d9b8f3a21",
  "direction": "push",
  "host": "github",
  "url": "https://github.com/fenil/ocean-landing.git",
  "label": "github.com/fenil/ocean-landing",
  "auth": { "kind": "app", "account": "fenil" },
  "send": { "choice": "all", "chosen": [], "prune": false },
  "paused": false,
  "there": { "main": "9b2c4e7d1a0f5c3e8b6a4d2f0c1e9a7b5d3f1e0c" },
  "heldRefs": [],
  "pausedReason": null,
  "pushes": [],
  "status": { "kind": "synced" },
  "stuckSince": null
}
```

| Field | Meaning |
| --- | --- |
| `direction` | `push` or `pull`. |
| `host` | `github`, `gitlab`, `bitbucket`, `codeberg` or `git` (any server). |
| `auth.kind` | `app`, `deploy-key`, `token` or `anonymous`. Secrets are never returned. |
| `send` | What a push mirror sends (see below). |
| `there` | Short ref name to the sha the other side holds. |
| `heldRefs` | Refs held back because they diverged or were rejected. Every other ref keeps mirroring. |
| `status.kind` | `syncing`, `synced`, `paused`, `disconnected`, `expired`, `diverged` (the two sides have different commits on `ref`) or `rejected` (the other side refused `ref`, with a `reason`). |
| `pausedReason` | Why the server paused it, `null` when a person did or it is not paused. |
| `stuckSince` | When the mirror entered a bad state it has been in for more than 4 hours. |

The mirror object also carries `aheadThere`, `pushes` (recent runs), `behind` (what a push mirror has not sent yet) and `replication`.

`send` is `{ choice, chosen, prune, include, exclude }`. `choice` is `all`, `default` or `chosen` (the names in `chosen`). `include` adds branch globs such as `refs/heads/release/*`, and `exclude` drops any matching branch or tag. `*` stays within one path segment and `**` crosses them. Tags go when the commit they name is on a branch that is sent.

### List mirror accounts

```http
GET /api/mirrors/connections
```

Needs the `user` scope. The remote accounts you have connected and can push to, each with `host`, `account`, `authorized`, `expired` (a timestamp or `null`) and `namespaces`. A namespace has `name`, `kind` and `repos`, each repository with `name`, `visibility` and `commits`.

### List mirrors

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

Returns an array of mirror objects.

### Preview a push mirror

```http
POST /api/repos/{owner}/{repo}/mirrors/preview
```

Body: `{ "send": RefSelection }`. What the first push would carry. It connects to nothing and sends nothing. Returns `{ refs, branches, tags, commits, objects, bytes, capped }`. Each ref has `name`, `kind`, `sha`, `subject` and `at`. `bytes` is the inflated size, and `capped` means the count stopped at its limit, so there is at least that much.

### Create a mirror

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

| Field | Type | Notes |
| --- | --- | --- |
| `host` | string, required | One of the hosts above. |
| `direction` | `"push"` or `"pull"`, optional | Default `push`. |
| `namespace`, `name` | string, optional | For GitHub through a connected account: the account and repository. Each is 1 to 100 letters, digits, `.`, `-` or `_`. |
| `url` | string, optional | The clone address. Required for any host but GitHub through a connected account. |
| `user`, `token` | string, optional | Credentials for a `url`. A push mirror needs both. A pull mirror needs both or neither (a public remote). The server must have `SAILFORK_SECRET_KEY` set to store a token. |
| `visibility` | `"public"` or `"private"`, optional | For a GitHub repository created for a push mirror. Defaults to this repository's visibility. |
| `send` | RefSelection, optional | Push mirrors only. |
| `replace` | boolean, optional | Allow overwriting what already exists. Needs `confirm`. |
| `confirm` | string, optional | This repository's name, typed to confirm `replace`. |

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"host":"github","direction":"push","namespace":"fenil","name":"ocean-landing"}' \
  https://sailfork.com/api/repos/fenil/ocean-landing/mirrors
```

Answers 201 with the mirror, which starts syncing at once. A push mirror to a GitHub repository that does not exist creates it.

| Status | Meaning |
| --- | --- |
| `409` | The remote or the repository already holds commits and you did not confirm the replacement (the message says what and asks for `replace` with `confirm`). Also: the repository already mirrors that remote, already pulls from another remote, or is still being moved from GitHub. |
| `422` | A bad field, an unreachable remote, a pull from a private GitHub repository into a public one, or a missing GitHub repository. |

Replacing is audited, and in an organization it appears in the audit log as `mirror.overwrite`.

### Change a mirror

```http
PATCH /api/repos/{owner}/{repo}/mirrors/{id}
```

Body: `{ "send"?: RefSelection, "paused"?: boolean }`. Changing `send` or resuming starts a run. A pull mirror takes no `send` (422). Returns the mirror.

### Delete a mirror

```http
DELETE /api/repos/{owner}/{repo}/mirrors/{id}
```

Answers 204. It stops mirroring; nothing is deleted on either side.

### Push now

```http
POST /api/repos/{owner}/{repo}/mirrors/{id}/push
```

Runs the mirror now. Answers 202 with the mirror. It is 409 when the mirror is paused or already syncing.

### Handle diverged refs

When the two sides hold different commits for a ref, the mirror holds that ref back and lists it in `heldRefs`.

```http
POST /api/repos/{owner}/{repo}/mirrors/{id}/overwrite
POST /api/repos/{owner}/{repo}/mirrors/{id}/import
GET  /api/repos/{owner}/{repo}/mirrors/{id}/overwritten
POST /api/repos/{owner}/{repo}/mirrors/{id}/overwritten/restore
```

- **Overwrite.** Body: `{ "confirm": "ocean-landing", "ref": "main" }`. `confirm` is the repository's name. `ref` names one diverged ref (short or full name); leave it out for every diverged ref. Each is forced only while the other side still holds the commit recorded when the divergence was found, and that commit is first kept so you can restore it. Answers 202 with the mirror. It answers 409 with the new state when the other side moved since (nothing is overwritten, and you confirm again), and 422 when `confirm` is wrong. It is audited.
- **Import.** Body: `{ "ref": "main" }`. Brings the other side's commits into a branch here named `<host>-diverged/<ref>`, from which you can open a pull request. Answers 201 with `{ "branch", "sha" }` (200 when the branch already holds that commit). It is 409 when the ref is not diverged, when the other side's commit is not known yet (sync first), or when the branch already has commits of its own.
- **List overwritten.** Returns what overwrites replaced, newest first: `[{ hidden, ref, sha, at }]`. `hidden` is the key to restore with.
- **Restore.** Body: `{ "hidden": "<hidden from the list>" }`. Makes the replaced commits a branch named `<host>-overwritten/<unix timestamp>/<ref>`, which you can merge or push back. Answers 201 with `{ "branch", "sha" }`, or 404 for an unknown `hidden`.

## Collaborators

Collaborators give a person read or write access to a personal repository. An organization's repositories use [organization roles](https://sailfork.com/docs/api-orgs) instead and answer 409 here.

### List collaborators

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

Needs `repo:admin` and admin access. Returns `{ "collaborators": [Collaborator], "invites": [RepoInvite] }`.

```json
{
  "collaborators": [
    { "handle": "marina", "name": "Marina Costa", "avatarUrl": null, "access": "write", "since": "2026-10-02T15:30:00Z" }
  ],
  "invites": [
    { "id": "5d0c1f6e-8a41-4b9e-9c37-2f6a1e0b7d44", "handle": "tomas", "name": "Tomas Reyes", "avatarUrl": null, "access": "read", "invitedBy": "Fenil Sonani", "sent": "2026-11-08T09:00:00Z" }
  ]
}
```

### Invite a collaborator

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

Body: `{ "handle": "marina", "access": "write" }`. `access` is `read` or `write` and defaults to `write`. Needs `repo:admin` and admin access. Answers 201 with the invitation. The person has to accept it. It answers 409 when they own the repository, already collaborate, are already invited, or are blocked, and 422 for an unknown handle.

### Change a collaborator's access

```http
PATCH /api/repos/{owner}/{repo}/collaborators/{handle}
```

Body: `{ "access": "read" }`. Needs `repo:admin` and admin access. Answers with the collaborator.

### Remove a collaborator

```http
DELETE /api/repos/{owner}/{repo}/collaborators/{handle}
```

Answers 204. Admins remove anyone; a collaborator may remove themselves to leave. The call needs `repo:admin` on a token either way.

### Revoke an invitation

```http
DELETE /api/repos/{owner}/{repo}/collaborators/invites/{id}
```

Needs `repo:admin` and admin access. Answers 204.

## Your repository invitations

These routes act on invitations sent to you. They need the `user` scope.

```http
GET  /api/me/repo-invites
POST /api/repo-invites/{id}/accept
POST /api/repo-invites/{id}/decline
```

The list returns an array of `{ id, owner, repo, access, invitedBy, sent }`. Accepting or declining answers 204.

## Organization invitation links

Previewing and accepting an organization's invitation links (`/api/invite-links/{token}`) is covered in the [Organizations API](https://sailfork.com/docs/api-orgs).

---

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