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; this page links to them instead of repeating them. Git clone and push use smart HTTP and SSH, not these routes: see 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 examplefeat%2Fx.- Reads on a public repository work without a token. A private repository you cannot read answers 404.
- Reads need
repo:readwhen you use a token. Where a route needs more, the table or text says so. See token scopes.
Repositories
List your repositories
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
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. |
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
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.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://sailfork.com/api/repos/fenil/ocean-landing {
"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 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
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
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.
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
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
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.
GETreturns{ "pinned": true, "canPin": true }to anyone who can see the repository, withrepo:read.canPinis false when signed out.PUTpins and returns the same object.DELETEunpins and answers 204. Both are idempotent and needrepo: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
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.
[
{
"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
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.
{ "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
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. |
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
"https://sailfork.com/api/repos/fenil/ocean-landing/commits?ref=main&limit=1" [
{
"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
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
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
GET /api/repos/{owner}/{repo}/tags Tags, newest commit first, at most 100. [] before the first push. For published releases see the Releases API.
[{ "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
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
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 with path for it. version is the blob id: pass it as expect when you commit a file.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
https://sailfork.com/api/repos/fenil/ocean-landing/blob/main/README.md Get raw file bytes
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,
.pdfasapplication/pdf, other text astext/plainand other binaries asapplication/octet-stream. Replies arenosniffwith a sandboxed content security policy, so committed HTML or SVG never runs script. - Caching. The
ETagis the blob id;If-None-Matchanswers 304 without reading the blob. Reads of a full commit id are immutable. - Ranges. Send one
Range: bytes=a-b,bytes=a-orbytes=-nfor a 206 withContent-Range. A range past the end is 416. Several ranges, or anIf-Rangeother than the currentETag, return the whole file. - Download.
download=1sendsContent-Disposition: attachment; otherwise it is inline.
Blame a file
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
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
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. |
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 { "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 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
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
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.
Check for merge conflicts
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
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. |
{ "names": ["main", "tide-fix"], "next": null, "total": 2 } total counts every match across pages.
Compare branches to the default branch
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.
[
{
"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
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
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. |
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. |
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
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
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.
Merge queue
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.
Merge rules
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) until you set an override here.
GETneedsrepo:read, or no token on a public repository. It returns{ "rules": Rules, "source": "repo" }.sourceisrepofor an override,orgwhen inherited anddefaultwhen nothing is set.PUTneedsrepo:adminand admin access. It stores an override and returns the same shape. Unknown fields are 422.DELETEneedsrepo:adminand 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. |
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, which needs user. The routes answer 503 when the server runs without mirrors.
A mirror object looks like this.
{
"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
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
GET /api/repos/{owner}/{repo}/mirrors Returns an array of mirror objects.
Preview a push mirror
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
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. |
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
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
DELETE /api/repos/{owner}/{repo}/mirrors/{id} Answers 204. It stops mirroring; nothing is deleted on either side.
Push now
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.
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" }.confirmis the repository's name.refnames 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 whenconfirmis 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 }].hiddenis 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 unknownhidden.
Collaborators
Collaborators give a person read or write access to a personal repository. An organization's repositories use organization roles instead and answer 409 here.
List collaborators
GET /api/repos/{owner}/{repo}/collaborators Needs repo:admin and admin access. Returns { "collaborators": [Collaborator], "invites": [RepoInvite] }.
{
"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
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
PATCH /api/repos/{owner}/{repo}/collaborators/{handle} Body: { "access": "read" }. Needs repo:admin and admin access. Answers with the collaborator.
Remove a collaborator
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
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.
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.