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. Authentication, scopes, errors and paging work as described in REST API.

RoutePurposeSign-in
GET /api/searchCode, file path and repository searchOptional
GET /api/explore/reposList public repositoriesNone
GET /api/repos/{owner}/{repo}/symbolsFind definitions by nameOptional
GET /api/repos/{owner}/{repo}/symbols/refsDefinitions and references of one nameOptional
POST /api/peopleResolve names and emails to peopleNone
GET /api/repos/{owner}/{repo}/people/{handle}A person's relation to one repositoryOptional
GET /api/versionServer versionNone
GET /api/statusDatabase and storage healthNone

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.

Search code

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 parameterTypeDescription
qstring, required1 to 256 characters on one line. A literal substring unless regex is true.
regexbooleanTreat 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.
casebooleantrue for a case-sensitive match. The default ignores case.
repostringSearch one repository, written owner/name.
pathstringKeep files whose path contains this text, such as src/lib/ or .svelte.
langstringKeep files in this language, using a language value from a result. Case-insensitive.
refstringA 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.
limitintegerFiles 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.

curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://status.sailfork.com/api/search?q=tideTable&repo=fenil/ocean-landing&lang=TypeScript&limit=5"
{
  "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:

FieldDescription
reposRepositories whose name matches, at most 10. Each has owner, name, about, visibility and ranges.
pathsMatching file paths: repo (owner/name), path, language, ranges, and ref when the request had one.
filesMatching 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.
truncatedtrue 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.
partialRepositories in the results that are indexed only up to the per-repository text bound.
tookMsServer 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.

StatusMeaning
422q is missing, too long, spans lines, or is not a valid pattern, or repo is not owner/name.
429More than 30 searches a minute from one address.
503Search 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

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 parameterTypeDescription
qstringUp to 100 characters on one line. A case-insensitive substring of the owner, name or about text.
sortupdated or nameupdated (default) is newest push first, using creation time before the first push. name is A to Z.
cursorstringThe previous page's next, with the same q and sort. Any other value is a 422.
limitinteger1 to 100, default 30.
curl "https://status.sailfork.com/api/explore/repos?q=ocean&limit=2"
{
  "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

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 parameterTypeDescription
qstring, required1 to 128 characters on one line. A case-insensitive substring of the name.
kindstringfunction, 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.
pathstringKeep definitions whose file path contains this text.
refstringA branch, tag or commit. Default: the default branch.
limitinteger1 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.

curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://status.sailfork.com/api/repos/fenil/ocean-landing/symbols?q=tide&kind=function&limit=2"
{
  "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

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 parameterTypeDescription
namestring, requiredAn exact, case-sensitive identifier, up to 128 characters on one line.
pathstringKeep results whose file path contains this text.
refstringA branch, tag or commit. Default: the default branch. Same rules as symbol search.
limitintegerReferences returned, 1 to 1000, default 100. Definitions are capped at 200.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://status.sailfork.com/api/repos/fenil/ocean-landing/symbols/refs?name=tideTable"
{
  "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

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 fieldTypeDescription
namesstring arrayAt most 200. A Sailfork handle, or github:<login> for someone a GitHub move brought who was not on Sailfork.
emailsstring arrayAt 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.

curl -X POST -H "Content-Type: application/json" \
  -d '{"names":["fenil","github:octocat"],"emails":["fenil@example.com"]}' \
  https://status.sailfork.com/api/people
{
  "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

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.

curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  https://status.sailfork.com/api/repos/fenil/ocean-landing/people/fenil
{
  "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:

ValueMeaning
ownerOwns the repository, or owns the organization that does.
maintainerCan push.
memberA member of the owning organization with read access only.
contributorHas a merged pull request in this repository.
first-timeAnyone 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

GET /api/version

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

curl https://status.sailfork.com/api/version
{ "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

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.

curl https://status.sailfork.com/api/status
{ "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.

Loading Sailfork