Pull requests API
List, open, review, comment on and merge pull requests, and read their diffs, checks and briefs, over the REST API.
Every route here lives under /api/repos/{owner}/{repo}. Reads need the repo:read scope, and a public repository can be read without a token. Writes need repo:write. A repository you cannot read answers 404 for every route. See authentication, token scopes and errors.
Pull request writes go through the same sync hub as the web app, so open browsers update live. A rejected write answers with the text a browser would see. The usual statuses are 403 not allowed, 404 no such pull request, 409 the request conflicts with the current state, and 422 invalid input.
Add X-Sailfork-Agent: <client name> to a request an agent makes, and the pull requests and comments it creates read agent: true.
For the person-facing flow, see Pull requests and Code review.
The pull request object
Pull is what create, get, patch, merge and list return.
| Field | Type | Notes |
|---|---|---|
number | number | Shared counter with issues. |
title, author | string | author is a handle, a bot name, or github:<login> for work moved from GitHub. |
state | string | open, draft, merged or closed. |
branch, head | string | The head branch. head is the same value under the name other tools expect. |
base | string | The branch it merges into. |
headSha | string or null | Branch tip, the merged tip once merged, null when the branch is gone. |
body | string[] | The description as lines. bodyText is the same text joined with \n. |
checks | string | none, passing, failing or running: the newest run of each workflow, and the newest check run of each name, on the head. |
review | string | none, requested, approved or changes. |
reviewer | string or null | Who was asked, or who last reviewed. |
agent, agentClient | boolean, string | Set when X-Sailfork-Agent named a client, or a caisson opened it. |
merge | object | Only once merged. baseSha, headSha, added, removed, files, plus mergeSha, mergedBy, method and branchDeleted on newer merges. |
locked | boolean | Present and true while only people with write access may comment or review. |
url | string | The pull request's page. |
at | string | When it was opened. |
List pull requests
GET /api/repos/{owner}/{repo}/pulls Newest first. Pass nextCursor back as cursor for the next page. See paging.
| Query | Type | Notes |
|---|---|---|
state | string | open (default, open only), draft, merged, closed or all. Anything else is 422. |
q | string | Case-insensitive substring of the title and body, or 12 or #12 for a number. |
author | string | A handle. |
head | string | Head branch name. |
base | string | Base branch name. |
cursor | string | Opaque, from nextCursor. |
limit | number | 1 to 100, default 30. |
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
"https://status.sailfork.com/api/repos/fenil/ocean-landing/pulls?state=open&limit=2" {
"items": [
{
"number": 14,
"title": "Fix the tide math",
"author": "fenil",
"agent": false,
"state": "open",
"checks": "passing",
"review": "requested",
"reviewer": "maya",
"at": "2026-11-08T17:22:41Z",
"branch": "tide-fix",
"head": "tide-fix",
"headSha": "9c1d0e47a2b3f6e85d0a7c4b19e2f3a6d8b05c71",
"base": "main",
"body": ["Rounds the tide table to the nearest minute."],
"url": "https://status.sailfork.com/fenil/ocean-landing/pulls/14"
}
],
"nextCursor": null
} List rows for a list view
GET /api/repos/{owner}/{repo}/pulls?brief=true Returns what a list row draws, plus the repository's counts by state, in one request. It takes state, q, cursor and limit. author, head and base are not applied here.
Differences from the plain list:
statedefaults toall, and also acceptsfinishedfor merged and closed together.- Every word of
qmust appear in the number, title, branch or author. - Items hold only
number,title,state,author,agent,at,branch,base,review,reviewer,checksandmerge. countsmaps each state to its number of pull requests, for the whole repository whatever the filter.
{
"items": [
{ "number": 14, "title": "Fix the tide math", "state": "open", "author": "fenil", "agent": false, "at": "2026-11-08T17:22:41Z", "branch": "tide-fix", "base": "main", "review": "requested", "reviewer": "maya", "checks": "passing" }
],
"nextCursor": null,
"counts": { "open": 3, "merged": 41, "closed": 6 }
} Get the sync rows
GET /api/repos/{owner}/{repo}/pulls/{n}/rows Returns the pull request and its threads as sync rows (Row[]), for a client that opens one older than its bootstrap carries. A bootstrap holds every open pull request and the newest 200 merged and 200 closed ones per repository. 404 when there is no such pull request.
Create a pull request
POST /api/repos/{owner}/{repo}/pulls Needs repo:write and write access to the repository. Returns 201 with the Pull.
| Body field | Type | Notes |
|---|---|---|
title | string | Required. |
branch | string | Required. The head branch. |
base | string | Required. Must differ from branch. |
body | string[] | Optional. The description as lines. |
draft | boolean | Optional. Open as a draft. |
reviewer | string | Optional. A handle that can read the repository. Not you. |
Someone without write access to a public repository can push to refs/heads/contrib/<handle>/<name> and open a pull request from that branch. Any other branch from them is 403.
| Status | When |
|---|---|
403 | No write access and the branch is not your own contrib/<handle>/ branch. |
409 | branch into base already has an open pull request. |
422 | A branch does not exist, branch equals base, the title is empty, or the reviewer cannot read the repository or is you. |
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"title":"Fix the tide math","branch":"tide-fix","base":"main","reviewer":"maya"}' \
https://status.sailfork.com/api/repos/fenil/ocean-landing/pulls Get a pull request
GET /api/repos/{owner}/{repo}/pulls/{n} Returns PullDetail: the Pull plus two fields.
| Field | Notes |
|---|---|
mergeable | { state, conflicts }. A dry-run merge of the head into the base. state is clean, conflict or unknown (merged, closed, branch gone). conflicts lists the files that do not merge, and is empty unless state is conflict. May be absent. |
threads | Every review thread, each with its comments and a pull number. |
The response carries an ETag. Send it back in If-None-Match to get 304. A number that belongs to an issue answers 404.
{
"number": 14,
"title": "Fix the tide math",
"state": "open",
"branch": "tide-fix",
"base": "main",
"mergeable": { "state": "clean", "conflicts": [] },
"threads": [
{
"id": "6f1b6c3e-2f4d-4a0e-9a53-0f5f1f0c7d11",
"pull": 14,
"path": "src/tides.ts",
"line": 42,
"side": "new",
"resolved": false,
"comments": [
{ "author": "maya", "agent": false, "at": "2026-11-09T09:02:11Z", "body": "Should this round up?" }
]
}
]
} Edit a pull request
PATCH /api/repos/{owner}/{repo}/pulls/{n} Needs repo:write, and either authorship of the pull request or push access. Returns the Pull. Send at least one field.
| Body field | Type | Who | Notes |
|---|---|---|---|
title | string | Author or writers | Not empty. |
body | string[] | Author or writers | Replaces the description. |
state | string | Author or writers | open, draft or closed. Moves open to draft, draft to open, either to closed, and closed back to open or draft. |
reviewer | string | Author or writers | A handle that can read the repository. Not the author. Sets review to requested. |
locked | boolean | Writers | While true, only people with write access can comment or review. |
base | string | Author or writers | Retargets an open or draft pull request onto that branch, and sets parent to the open pull request whose branch it is, if any (see Get the stack). |
| Status | When |
|---|---|
403 | Not the author and no push access, or a non-writer sets locked. |
409 | The pull request is merged and you send state or reviewer, or reopening or a new base would clash with another open pull request for the same branch and base. |
422 | No field was sent, the title is empty, the reviewer is invalid, or base is missing or is itself stacked on this pull request. |
Merge a pull request
POST /api/repos/{owner}/{repo}/pulls/{n}/merge Needs repo:write and write access. The body is optional. Returns the merged Pull, with merge filled in.
| Body field | Type | Notes |
|---|---|---|
method | string | merge, squash, rebase or fast-forward. Omitted, the base fast-forwards when it has not moved, and gets a merge commit otherwise. |
deleteBranch | boolean | false keeps the head branch. Omitted, the branch is deleted unless a branch protection keeps it. The default branch is never deleted. |
Merge methods:
mergewrites a merge commit.squashwrites one commit titled<title> (#N), with the pull request body.rebasereplays the commits. It works on linear branches only, with you as the committer.fast-forwardmoves the base to the head. It refuses when the base has moved.
Sailfork merges whole files: two sides that changed one file to different contents conflict, and the merge refuses.
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"method":"squash","deleteBranch":true}' \
https://status.sailfork.com/api/repos/fenil/ocean-landing/pulls/14/merge {
"number": 14,
"state": "merged",
"branch": "tide-fix",
"base": "main",
"merge": {
"baseSha": "4b7a1c90e2d35f6a8b0c1d2e3f4a5b6c7d8e9f01",
"headSha": "9c1d0e47a2b3f6e85d0a7c4b19e2f3a6d8b05c71",
"added": 12,
"removed": 3,
"files": 2,
"mergeSha": "e5f60718293a4b5c6d7e8f9012a3b4c5d6e7f809",
"mergedBy": "fenil",
"method": "squash",
"branchDeleted": true
}
} The merge enforces your merge rules: required approvals, up-to-date branches, resolved threads, protected paths and required checks. When a rule is not met the answer is 409 with merge rules not met: and every unmet rule, joined by semicolons.
| Status | When |
|---|---|
403 | No write access. |
404 | No such pull request. |
409 | Merged already and its branch has new commits, the pull request is a draft or closed, merge rules are not met, the branch is behind the base and conflicts, fast-forward cannot apply, the repository is a read-only mirror, or the pull request changed while merging (retry). |
422 | The body is not valid JSON for these fields. |
Merging a pull request that is already merged answers 200 with it, as long as its branch has not moved since the merge. A retried call is safe.
Reviews
Submit a review
POST /api/repos/{owner}/{repo}/pulls/{n}/reviews Returns 204.
| Body field | Type | Notes |
|---|---|---|
verdict | string | Required. approve, changes or comment. |
body | string | Optional. A body becomes a thread on the pull request with no file anchor. A comment review needs a body or comments. |
comments | array | Optional. Up to 100 line comments, each shaped like the body of Comment on a pull request. They land with the verdict in one transaction: if one is refused, none of them land and neither does the verdict. |
commit | string | Optional. The head commit you reviewed, 7 or more hex characters (a prefix is enough). The review is refused with 409 when the pull request has moved since, so a bot never comments on lines that changed under it. |
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"verdict":"changes","commit":"4f2a9c1","body":"Two things before this lands.","comments":[
{"thread":null,"path":"src/tides.ts","line":42,"body":"Should this round up?"},
{"thread":null,"path":"src/tides.ts","line":57,"startLine":50,"body":"This block can go."}]}' \
https://status.sailfork.com/api/repos/fenil/ocean-landing/pulls/14/reviews People in the web app build a review the same way: comments they add with Start a review are saved as pending, on every device they use and seen by nobody else, and are sent together when they submit.
comment needs only read access. approve and changes need repo:write and push access, and set review and reviewer on the pull request.
| Status | When |
|---|---|
403 | You are the author and send approve or changes, you lack push access for those, or the pull request is locked and you cannot write. |
409 | approve or changes on a merged pull request, or commit is not the pull request's head. |
422 | comment with neither a body nor comments, more than 100 comments, or a comment the comments route would refuse. |
Dismiss a request for changes
POST /api/repos/{owner}/{repo}/pulls/{n}/dismiss Needs push access. Returns 204 and sets review back to requested.
| Status | When |
|---|---|
409 | The pull request is merged or closed, or its review is not changes. |
422 | You asked for those changes yourself: review again instead. |
Comments and threads
A thread is a run of comments anchored to a file and line. Each comment is addressed by its thread id, its index in comments (from 0), and its at timestamp. The edit, delete and hide routes need at to match the comment at that index, so a comment that moved or changed answers 409 that comment changed or moved since you read it.
Comment on a pull request
POST /api/repos/{owner}/{repo}/pulls/{n}/comments Needs repo:write. Returns 201 with the thread and a pull number. A locked pull request is 403 for anyone without write access.
| Body field | Type | Notes |
|---|---|---|
thread | string or null | Required. null opens a new thread, a thread id adds a reply. |
body | string | Required. Not empty. |
path | string | New thread: the file the comment is on. A reply takes the thread's anchor. |
line | number | New thread: the last line of the range, or the only one. |
startLine | number | Optional. The first line of a range ending at line. Needs path, and 1 <= startLine < line, else 422. |
side | string | old counts base-version lines, new (default) the head version. |
startColumn, endColumn | number | Optional, together. A comment on words instead of whole lines: where the selection starts on the first line and ends on line, counted in UTF-16 code units from the start of the line (what a browser selection counts). On one line endColumn must be after startColumn. The page highlights those characters and quotes them on the thread. |
proof | object | Optional. What you ran to show the point. See Proof. |
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"thread":null,"path":"src/tides.ts","line":42,"body":"Should this round up?"}' \
https://status.sailfork.com/api/repos/fenil/ocean-landing/pulls/14/comments {
"id": "6f1b6c3e-2f4d-4a0e-9a53-0f5f1f0c7d11",
"path": "src/tides.ts",
"line": 42,
"side": "new",
"resolved": false,
"comments": [
{ "author": "fenil", "agent": false, "at": "2026-11-09T09:02:11Z", "body": "Should this round up?" }
]
} Proof
A finding is easier to trust when it shows the command that proves it. Attach proof to a comment, in this route or in a review's comments, citing one of:
| Cite | Fields | Comes back |
|---|---|---|
| A sandbox exec | exec: the id from the X-Sailfork-Exec header of a finished exec you ran | Verified when the sandbox was made from this pull request's head commit. The command, exit code and the last 8 KiB of output (secrets masked) come from Sailfork's own record. |
| A CI job | run (the run number) and job (the job key) | Verified when that run was for the head commit. The exit code is 0 for a passed job and 1 for a failed one, and the page links the job's log. |
| A claim | command, with optional exitCode, output and commit | Shown as Claimed: Sailfork has no record of it. |
The comment's proof then reads { command, exitCode, output, commit, source, verified }. Nobody can set verified themselves: a value sent over the sync socket is dropped.
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"thread":null,"path":"src/tides.ts","line":42,"body":"This rounds down: the test fails.","proof":{"exec":"84f3cc0b-c28d-44d6-b83d-af170858404b"}}' \
https://status.sailfork.com/api/repos/fenil/ocean-landing/pulls/14/comments | Status | When |
|---|---|
422 | No cite, more than one, an exec that is not yours, or a run and job this repository does not have. |
409 | The exec or job has not finished yet. |
Resolve a thread
POST /api/repos/{owner}/{repo}/pulls/{n}/threads/{id}/resolve Needs push access. Body { "resolved": true } or false. Returns the thread.
Edit a comment
PATCH /api/repos/{owner}/{repo}/pulls/{n}/threads/{id}/comments/{index} Body { "at": "<comment timestamp>", "body": "new text" }. Only the comment's author can edit it, else 403. Returns the thread, and the comment gains an edited timestamp.
Delete a comment
DELETE /api/repos/{owner}/{repo}/pulls/{n}/threads/{id}/comments/{index}?at=<timestamp> The author or anyone with push access can delete. Returns 204. Deleting the last comment of a thread removes the thread. Anyone else gets 403.
Hide a comment
PUT /api/repos/{owner}/{repo}/pulls/{n}/threads/{id}/comments/{index}/hidden Needs push access. Body { "at": "<comment timestamp>", "reason": "spam" }, with reason one of spam, abuse, offTopic, outdated or resolved. null unhides. Returns 204. The body stays readable and the comment folds away.
Presence
Everyone on a pull request page sees who else is there: the file each person is reading, the line they picked, and whether they are writing a comment on it. Browsers send this over the sync socket. An integration or agent that holds no socket announces itself here, so it shows up on the page beside the people, under its client name.
Presence is never stored. A spot lasts ttl seconds unless renewed, and a viewer drops it after that.
Announce where you are
PUT /api/repos/{owner}/{repo}/pulls/{n}/presence Needs repo:read and a signed-in caller. Returns 204. One spot per token and X-Sailfork-Session, labeled with the X-Sailfork-Agent client, or the token's name when it declares none.
| Body field | Type | Notes |
|---|---|---|
path | string | Optional. The file you are on, at most 1024 bytes. |
line | number | Optional. A line on it, 1 or more. |
side | string | old or new (default). |
composing | boolean | true while you are writing a comment there. |
ttl | number | Seconds the spot holds: default 60, from 5 to 300. Renew before it runs out to stay. |
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" -H "X-Sailfork-Agent: review-bot" -H "Content-Type: application/json" \
-d '{"path":"src/tides.ts","line":42,"composing":true,"ttl":120}' \
https://status.sailfork.com/api/repos/fenil/ocean-landing/pulls/14/presence Leave
DELETE /api/repos/{owner}/{repo}/pulls/{n}/presence Takes your spot down at once. Returns 204.
Keep a pull request current
Update the branch
POST /api/repos/{owner}/{repo}/pulls/{n}/update-branch Brings the base into the head branch. Needs push access to the repository: authorship is not enough, because it moves a branch. Returns { headSha, updated }, with updated: false when the branch already had the base.
| Status | When |
|---|---|
403 | No push access. |
409 | The pull request is merged or closed, the base cannot merge in cleanly, or the branch moved meanwhile (retry). |
Approve CI for an outside contribution
POST /api/repos/{owner}/{repo}/pulls/{n}/ci/approve Needs write access. Workflows for a pull request from an outside contributor never start on their own. This starts them. They run read-only and without the repository's secrets. Returns 204.
Get the stack
GET /api/repos/{owner}/{repo}/pulls/{n}/stack The whole stack pull request n belongs to, as StackEntry[]: the root is found by following parent up while that pull request exists, at most 32 steps, then the tree is listed depth first, root first, children by number. A pull request with no parent and no children answers just itself. Read access as Get a pull request, and 404 in the same cases.
| Field | Meaning |
|---|---|
number, title, author | The pull request. |
state | open, draft, merged or closed. |
checks | none, passing, failing, running or cancelled. |
review | none, requested, approved or changes. |
branch, base | Its head and base branches. |
parent | The pull request it is stacked on; null for the root, and when the parent no longer exists. |
depth | 0 for the root. |
To stack an open pull request on another, PATCH it with base set to the other's branch (see Edit a pull request).
Checks
GET /api/repos/{owner}/{repo}/pulls/{n}/checks Returns the CI jobs of the newest run of each workflow on the pull request's head commit, one row per job, then the newest check run of each name and reporter on that commit. Runs started by the pull request and by a push of that commit both count. A merged or closed pull request answers for its last head commit. When the branch is gone and no merge was recorded, headSha is null and there are no checks. 404 for an unknown pull request.
| Field | Notes |
|---|---|
number, headSha | The pull request and the commit the checks belong to. |
state | fail when any check failed or was cancelled, else pending when any is pending, else pass when any passed, else none. |
pass, fail, pending | Counts. |
checks | One row per job: source (ci), run, workflow, job, name, state (pass, fail, pending, skipped, cancelled), startedAt, finishedAt, seconds, failedSteps (0-based index and name). A check run's row has source app, run 0, an empty job, its app's name as workflow, and the whole run in checkRun. |
configured | May be present. |
{
"number": 14,
"headSha": "9c1d0e47a2b3f6e85d0a7c4b19e2f3a6d8b05c71",
"state": "fail",
"pass": 1,
"fail": 1,
"pending": 0,
"checks": [
{ "run": 212, "workflow": "ci.yml", "job": "test", "name": "test", "state": "fail", "startedAt": "2026-11-08T17:23:02Z", "finishedAt": "2026-11-08T17:24:10Z", "seconds": 68, "failedSteps": [{ "index": 3, "name": "Run tests" }] },
{ "run": 212, "workflow": "ci.yml", "job": "lint", "name": "lint", "state": "pass", "startedAt": "2026-11-08T17:23:02Z", "finishedAt": "2026-11-08T17:23:40Z", "seconds": 38, "failedSteps": [] }
]
} To read a failing step's log, use the run and index with the routes in the CI API.
Briefs for agents
GET /api/repos/{owner}/{repo}/brief/{n} One request with what an agent needs to start on issue or pull request #n. Needs repo:read; signed out works on public repositories, but a bad credential is 401. comments=N or comments=all sets how many of the newest comments come back (default 10).
For a pull request, pull holds the diff stat, the unresolved line threads with the code around each line, CI counts with each failed check's failing step and its last 20 log lines, the open caissons on the head branch, and the issues it closes. The same route answers for an issue number with issue instead. A part that cannot be read is named in gaps, and the rest still answers. It is 404 when #n is neither.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
"https://status.sailfork.com/api/repos/fenil/ocean-landing/brief/14?comments=3" {
"kind": "pull",
"number": 14,
"title": "Fix the tide math",
"state": "open",
"author": "fenil",
"url": "https://status.sailfork.com/fenil/ocean-landing/pulls/14",
"body": "Rounds the tide table to the nearest minute.",
"labels": [],
"assignee": null,
"lease": null,
"comments": [],
"commentsTotal": 0,
"pull": {
"head": "tide-fix",
"base": "main",
"headSha": "9c1d0e47a2b3f6e85d0a7c4b19e2f3a6d8b05c71",
"review": "requested",
"reviewer": "maya",
"diff": { "files": 2, "added": 12, "removed": 3, "items": [{ "path": "src/tides.ts", "status": "modified", "added": 10, "removed": 3 }] },
"threads": [],
"checks": { "state": "fail", "pass": 1, "fail": 1, "pending": 0, "failed": [] },
"mergeable": { "state": "clean", "conflicts": [] },
"caissons": [],
"closes": []
},
"gaps": []
} Diffs and signals
These reads need repo:read.
Compare a pull request
GET /api/repos/{owner}/{repo}/pulls/{n}/compare Returns the same Compare as the repository compare route, plus stats (added, removed, files) and merged. A merged pull request is served from the range recorded when it merged. lines=N trims the hunks to the leading files whose changed lines start within N, and adds the base and head commits compared. Later files have hunks: [] and pending: true. stats stays whole. 404 no pull request #n when there is none.
Compare by branch
GET /api/repos/{owner}/{repo}/pulls/compare?branch=<head branch> The same body for the pull request whose head is that branch: the open or draft one, else the newest closed or merged one. Takes lines too.
| Status | When |
|---|---|
404 | no pull request from branch <branch>. |
422 | branch is missing. |
Pull request signals
GET /api/repos/{owner}/{repo}/pulls/signals Returns one entry for every open and draft pull request whose branch and base still exist.
| Field | Notes |
|---|---|
number | The pull request. |
added, removed, files | Diff stats. |
behind | Base commits since the fork. |
conflicts | Files both sides changed to different contents, the files that make a merge refuse. Sorted. |
paths | Every path the head changes since the fork. Sorted. Enough to know what a pull request touches without its diff. |
[
{ "number": 14, "added": 12, "removed": 3, "files": 2, "behind": 0, "conflicts": [], "paths": ["src/tides.ts", "src/tides.test.ts"] }
] Pull requests touching a path
GET /api/repos/{owner}/{repo}/pulls/touching?path=src/tides.ts Returns { items: Pull[] }, newest first, for the pull requests that change path.
| Query | Type | Notes |
|---|---|---|
path | string | Required. A file, or a folder when it ends in /. Missing is 422. |
state | string | open (default, open and draft), merged or all. Anything else is 422. |
limit | number | 1 to 100, default 30. |
Open pull requests are matched on the paths their head changes since the fork, merged ones on the range recorded at merge. A merged pull request with no recorded range is left out. Only the newest 100 pull requests of the chosen state are searched.