# Search and code navigation API

Search code across repositories, find symbol definitions and references, list public repositories, resolve people, and check server health.

These routes find things: code, symbols, public repositories and people. Two small routes report the server version and health. For the product view of search, see [Search](https://status.sailfork.com/docs/search). Authentication, scopes, errors and paging work as described in [REST API](https://status.sailfork.com/docs/api#authentication).

| Route | Purpose | Sign-in |
| --- | --- | --- |
| `GET /api/search` | Code, file path and repository search | Optional |
| `GET /api/explore/repos` | List public repositories | None |
| `GET /api/repos/{owner}/{repo}/symbols` | Find definitions by name | Optional |
| `GET /api/repos/{owner}/{repo}/symbols/refs` | Definitions and references of one name | Optional |
| `POST /api/people` | Resolve names and emails to people | None |
| `GET /api/repos/{owner}/{repo}/people/{handle}` | A person's relation to one repository | Optional |
| `GET /api/version` | Server version | None |
| `GET /api/status` | Database and storage health | None |

Where sign-in is optional, a signed-out caller sees public repositories only. A token needs the `repo:read` scope and then sees every repository its owner can read. A private repository you cannot read is never in the results.

## Code search

### Search code

```http
GET /api/search
```

One query returns three lists: repositories whose name matches, file paths that match (for "go to file"), and files whose content matches, with snippets. Only branch heads are searched, and only text files. Binaries, files over 1 MiB, vendored and build directories (`node_modules`, `vendor`, `dist`, `build`, `target`), lockfiles, `*.min.*` and `*.d.ts` are skipped. A push is searchable within about 2 seconds.

| Query parameter | Type | Description |
| --- | --- | --- |
| `q` | string, required | 1 to 256 characters on one line. A literal substring unless `regex` is true. |
| `regex` | boolean | Treat `q` as a pattern in Rust regex syntax. It runs in linear time and has no backreferences. A pattern that matches the empty string is refused. |
| `case` | boolean | `true` for a case-sensitive match. The default ignores case. |
| `repo` | string | Search one repository, written `owner/name`. |
| `path` | string | Keep files whose path contains this text, such as `src/lib/` or `.svelte`. |
| `lang` | string | Keep files in this language, using a `language` value from a result. Case-insensitive. |
| `ref` | string | A branch name such as `feature/x`. Searches that branch's head instead of each repository's default branch. A branch the repository does not have matches nothing. |
| `limit` | integer | Files and paths returned, 1 to 100, default 20. |

Every branch of a repository is indexed, up to the server's per-repository branch cap (default 256, the default branch first, then by name). A deleted branch drops out of the index.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://status.sailfork.com/api/search?q=tideTable&repo=fenil/ocean-landing&lang=TypeScript&limit=5"
```

```json
{
  "query": "tideTable",
  "repos": [],
  "paths": [
    { "repo": "fenil/ocean-landing", "path": "src/lib/tideTable.ts", "language": "TypeScript", "ranges": [[8, 17]] }
  ],
  "files": [
    {
      "repo": "fenil/ocean-landing",
      "path": "src/lib/tideTable.ts",
      "language": "TypeScript",
      "matchCount": 2,
      "snippets": [
        {
          "lines": [
            { "number": 11, "column": 0, "text": "", "ranges": [] },
            { "number": 12, "column": 0, "text": "export const tideTable = build();", "ranges": [[13, 22]] },
            { "number": 13, "column": 0, "text": "", "ranges": [] }
          ]
        }
      ]
    }
  ],
  "truncated": false,
  "partial": [],
  "tookMs": 14
}
```

Response fields:

| Field | Description |
| --- | --- |
| `repos` | Repositories whose name matches, at most 10. Each has `owner`, `name`, `about`, `visibility` and `ranges`. |
| `paths` | Matching file paths: `repo` (`owner/name`), `path`, `language`, `ranges`, and `ref` when the request had one. |
| `files` | Matching files: `repo`, `path`, `language` (empty when unknown), `matchCount`, `snippets`, and `ref` when the request had one. At most 10 matching lines are shown per file. |
| `truncated` | `true` when more files matched than `limit`, or when the search stopped at its time budget (about 1.2 seconds) and `files` holds what it had found. A term that appears in most files can end this way. |
| `partial` | Repositories in the results that are indexed only up to the per-repository text bound. |
| `tookMs` | Server time in milliseconds. |

Each snippet is a list of lines: a matching line with 2 lines of context, with overlapping windows merged. A line has `number`, `column`, `text` and `ranges`. A context line has no ranges. Lines over 500 bytes are cut around the first match, and `column` is the byte offset of `text` in the full line (0 when not cut).

> [!IMPORTANT]
> Every `ranges` entry is `[start, end)` in UTF-8 byte offsets of the string next to it. Convert them before you slice a JavaScript string. Files rank path matches first, then files with an exact-case match.

| Status | Meaning |
| --- | --- |
| 422 | `q` is missing, too long, spans lines, or is not a valid pattern, or `repo` is not `owner/name`. |
| 429 | More than 30 searches a minute from one address. |
| 503 | Search is busy (two searches run at once on a machine), or the query passed its time budget of about 2 seconds. Retry, or narrow the query. |

## Explore

### List public repositories

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

Lists every public repository a signed-out visitor could open. Repositories scheduled for deletion and personal repositories of suspended accounts are left out. Organization repositories are listed under the organization's handle. The list is the same for everyone, and no sign-in is needed.

| Query parameter | Type | Description |
| --- | --- | --- |
| `q` | string | Up to 100 characters on one line. A case-insensitive substring of the owner, name or about text. |
| `sort` | `updated` or `name` | `updated` (default) is newest push first, using creation time before the first push. `name` is A to Z. |
| `cursor` | string | The previous page's `next`, with the same `q` and `sort`. Any other value is a 422. |
| `limit` | integer | 1 to 100, default 30. |

```sh
curl "https://status.sailfork.com/api/explore/repos?q=ocean&limit=2"
```

```json
{
  "repos": [
    {
      "owner": "fenil",
      "name": "ocean-landing",
      "about": "Landing page with the tide table",
      "defaultBranch": "main",
      "language": "Svelte",
      "pushedAt": "2026-11-08T17:42:10Z",
      "cloneUrl": "https://status.sailfork.com/fenil/ocean-landing.git"
    }
  ],
  "next": null
}
```

`next` is `null` on the last page. `language` is the primary language at the default branch head, and is empty for an empty repository or one not yet counted. A bad `q`, `limit` or `cursor` is a 422. More than 120 requests a minute from one address is a 429.

## Code navigation

Symbol routes read from the same index as code search. Rust, TypeScript, JavaScript, Python and Go (and the `<script>` of Svelte and Vue files) are parsed with tree-sitter. Definitions come from the grammars' tags queries, and references are identifier tokens, so comments and strings never count. Other languages use line patterns and word tokens. Files over 512 KiB are skipped, and symbols follow a push within a few seconds.

Both routes need read access to the repository and answer 404 for a repository you cannot read.

### Find symbols

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

Finds definitions whose name contains `q`. Exact-case name matches come first, then any-case matches, then prefixes, then shorter names, with ties broken by path and line.

| Query parameter | Type | Description |
| --- | --- | --- |
| `q` | string, required | 1 to 128 characters on one line. A case-insensitive substring of the name. |
| `kind` | string | `function`, `method`, `struct`, `enum`, `union`, `trait`, `interface`, `class`, `type`, `module`, `macro`, `const` or `static`. Aliases such as `fn`, `func`, `def`, `mod`, `namespace` and `constant` work. Anything else is a 422. |
| `path` | string | Keep definitions whose file path contains this text. |
| `ref` | string | A branch, tag or commit. Default: the default branch. |
| `limit` | integer | 1 to 200, default 30. |

An indexed branch head is read from the index. Any other ref uses the default branch's index, with the files that differ extracted on demand. That is a 422 when more than 2000 files or 16 MiB differ, and a 404 when the repository has no such ref.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://status.sailfork.com/api/repos/fenil/ocean-landing/symbols?q=tide&kind=function&limit=2"
```

```json
{
  "query": "tide",
  "ref": "main",
  "symbols": [
    {
      "name": "tideTable",
      "kind": "function",
      "path": "src/lib/tideTable.ts",
      "line": 12,
      "language": "TypeScript",
      "text": "export function tideTable(day: string): Tide[] {"
    }
  ],
  "truncated": false,
  "indexing": false,
  "tookMs": 6
}
```

A symbol has `name`, `kind`, `path`, `line` (1-based), `language` (empty when unknown), `text` (the line, trimmed, at most 300 bytes) and `container` (the type, trait, class or module it is declared in, when known). `truncated` is `true` when more than `limit` matched. `indexing` is `true` while the repository's index is behind its refs, so results may be missing or stale.

### Find definitions and references

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

Returns every definition of one identifier and every other line where it occurs as an identifier, ordered by path and line.

| Query parameter | Type | Description |
| --- | --- | --- |
| `name` | string, required | An exact, case-sensitive identifier, up to 128 characters on one line. |
| `path` | string | Keep results whose file path contains this text. |
| `ref` | string | A branch, tag or commit. Default: the default branch. Same rules as symbol search. |
| `limit` | integer | References returned, 1 to 1000, default 100. Definitions are capped at 200. |

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://status.sailfork.com/api/repos/fenil/ocean-landing/symbols/refs?name=tideTable"
```

```json
{
  "name": "tideTable",
  "ref": "main",
  "definitions": [
    {
      "name": "tideTable",
      "kind": "function",
      "path": "src/lib/tideTable.ts",
      "line": 12,
      "language": "TypeScript",
      "text": "export function tideTable(day: string): Tide[] {"
    }
  ],
  "references": [
    { "path": "src/routes/+page.ts", "line": 4, "text": "const tides = tideTable(today);" }
  ],
  "truncated": false,
  "indexing": false,
  "tookMs": 9
}
```

`truncated` is `true` when there are more references than `limit`.

## People

### Resolve people

```http
POST /api/people
```

Turns author strings and commit emails into profiles, so a page can show avatars and links. No sign-in is needed. The route allows 60 requests a minute from one address.

| Body field | Type | Description |
| --- | --- | --- |
| `names` | string array | At most 200. A Sailfork handle, or `github:<login>` for someone a GitHub move brought who was not on Sailfork. |
| `emails` | string array | At most 200. Commit author addresses. |

More than 200 of either is a 422, and past the rate limit it is a 429.

A GitHub account resolves to the Sailfork user who linked it, so imported work follows a person once they join. Addresses resolve through verified Sailfork emails, the commit authors GitHub named during a move, and GitHub no-reply addresses. Keys that cannot be resolved are left out of the response, so show the raw text for them.

```sh
curl -X POST -H "Content-Type: application/json" \
  -d '{"names":["fenil","github:octocat"],"emails":["fenil@example.com"]}' \
  https://status.sailfork.com/api/people
```

```json
{
  "names": {
    "fenil": { "handle": "fenil", "name": "Fenil Sonani", "avatarUrl": "https://status.sailfork.com/avatars/fenil.png" },
    "github:octocat": {
      "name": "The Octocat",
      "avatarUrl": null,
      "github": { "login": "octocat", "avatarUrl": "https://avatars.githubusercontent.com/u/583231" }
    }
  },
  "emails": {
    "fenil@example.com": { "handle": "fenil", "name": "Fenil Sonani", "avatarUrl": "https://status.sailfork.com/avatars/fenil.png" }
  }
}
```

A person has `name`, `avatarUrl` (or `null`), and `handle` when they are on Sailfork. When there is no `handle`, `github` holds `login` and `avatarUrl`, and you can link to `https://github.com/<login>`.

### Get a person's relation to a repository

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

Says who a Sailfork user is to one repository. The site shows it in the card that appears when you hover a name on a pull request. Only readers of the repository can call it, and no sign-in is needed for a public one. An agent's pull request names the person whose token it used as its author, so the card for that handle says who the agent works for.

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

```json
{
  "handle": "fenil",
  "name": "Fenil Sonani",
  "avatarUrl": "https://status.sailfork.com/avatars/fenil.png",
  "joinedAt": "2025-03-02T09:15:00Z",
  "relation": "owner",
  "pulls": { "opened": 14, "merged": 12 }
}
```

`relation` is the strongest that applies:

| Value | Meaning |
| --- | --- |
| `owner` | Owns the repository, or owns the organization that does. |
| `maintainer` | Can push. |
| `member` | A member of the owning organization with read access only. |
| `contributor` | Has a merged pull request in this repository. |
| `first-time` | Anyone else. |

`pulls` counts pull requests with this author in this repository, drafts and imports included. A renamed handle answers under its current handle. The response is a 404 for a private repository you cannot read, an unknown or deleted handle, and `github:<login>` authors, who have no Sailfork account.

## Server

### Get the server version

```http
GET /api/version
```

No sign-in. Use it to tell which build you are talking to.

```sh
curl https://status.sailfork.com/api/version
```

```json
{ "version": "0.9.4", "commit": "eeaabab6", "integrations": { "ssh": true, "github": true, "ci": true } }
```

`commit` is the git commit of the build, or `null` when unknown. `integrations` says whether SSH, the GitHub App and CI are running, as booleans only. A server older than this route answers an empty 404, which is how a client tells it is newer than its server.

### Get the server status

```http
GET /api/status
```

No sign-in. Probes the database and repository storage on every request, each bounded to 2 seconds, and reports only up or down. `git` is up when both are, since a clone needs the database for access and storage for the objects. The response is never cached.

```sh
curl https://status.sailfork.com/api/status
```

```json
{ "database": { "up": true }, "storage": { "up": true }, "git": { "up": true } }
```

All callers share one window of 300 requests a minute. Past it the answer is a 429 with a `Retry-After` header.

---

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