# 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](https://status.sailfork.com/docs/api#authentication), [token scopes](https://status.sailfork.com/docs/api#token-scopes) and [errors](https://status.sailfork.com/docs/api#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](https://status.sailfork.com/docs/pull-requests) and [Code review](https://status.sailfork.com/docs/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

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

Newest first. Pass `nextCursor` back as `cursor` for the next page. See [paging](https://status.sailfork.com/docs/api#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. |

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://status.sailfork.com/api/repos/fenil/ocean-landing/pulls?state=open&limit=2"
```

```json
{
  "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

```http
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:

- `state` defaults to `all`, and also accepts `finished` for merged and closed together.
- Every word of `q` must appear in the number, title, branch or author.
- Items hold only `number`, `title`, `state`, `author`, `agent`, `at`, `branch`, `base`, `review`, `reviewer`, `checks` and `merge`.
- `counts` maps each state to its number of pull requests, for the whole repository whatever the filter.

```json
{
  "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

```http
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

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

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Fix the tide math","branch":"tide-fix","base":"main","reviewer":"maya"}' \
  https://status.sailfork.com/api/repos/fenil/ocean-landing/pulls
```

## Get a pull request

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

```json
{
  "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

```http
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](#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

```http
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:

- `merge` writes a merge commit.
- `squash` writes one commit titled `<title> (#N)`, with the pull request body.
- `rebase` replays the commits. It works on linear branches only, with you as the committer.
- `fast-forward` moves 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.

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

```json
{
  "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](https://status.sailfork.com/docs/permissions): 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

```http
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](#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. |

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

```http
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

```http
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](#proof). |

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

```json
{
  "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.

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

```http
POST /api/repos/{owner}/{repo}/pulls/{n}/threads/{id}/resolve
```

Needs push access. Body `{ "resolved": true }` or `false`. Returns the thread.

### Edit a comment

```http
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

```http
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

```http
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

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

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

```http
DELETE /api/repos/{owner}/{repo}/pulls/{n}/presence
```

Takes your spot down at once. Returns `204`.

## Keep a pull request current

### Update the branch

```http
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

```http
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

```http
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](#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](#edit-a-pull-request)).

## Checks

```http
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](https://status.sailfork.com/docs/apps#check-runs) 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. |

```json
{
  "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](https://status.sailfork.com/docs/api-ci).

## Briefs for agents

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

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://status.sailfork.com/api/repos/fenil/ocean-landing/brief/14?comments=3"
```

```json
{
  "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

```http
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

```http
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

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

```json
[
  { "number": 14, "added": 12, "removed": 3, "files": 2, "behind": 0, "conflicts": [], "paths": ["src/tides.ts", "src/tides.test.ts"] }
]
```

### Pull requests touching a path

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

---

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