Releases API
List, create, edit and delete releases, upload and download their files, and look up the latest CLI build.
A release is a tag with a title, Markdown notes and files to download. For the product view, see Releases. Authentication, scopes, errors and paging rules are in the REST API overview; this page covers only what is specific to releases.
Access rules
- Reading. Anyone can read the releases of a public repository, and a signed-in reader needs the
repo:readscope on a token (token scopes). Readers see published releases only. - Writing. Creating, editing and deleting releases and assets needs write access to the repository and the
repo:writescope. Writers also see drafts. - Hidden repositories. A private repository answers
404to anyone who cannot read it, including on every route below. - Mirrored repositories. If a GitHub mirror brings a repository's pull requests and issues, its releases are read-only. Writes answer
403and name the mirror. Those releases, with their assets and download counts, come from GitHub and havefromGithub: true.
The release object
| Field | Type | Notes |
|---|---|---|
id | string | Release id, used in edit, delete and upload routes. |
tag | string | The git tag, slashes included. |
title | string | May be empty. Show the tag then. |
notes | string | Markdown. |
draft | boolean | Drafts are visible to writers only. |
prerelease | boolean | |
author | string | A handle, or github:<login> for a GitHub author without a Sailfork account. |
fromGithub | boolean | true for releases that came from a GitHub mirror or move. |
createdAt | string | ISO timestamp. |
publishedAt | string or null | null while a draft. |
sha | string or null | The tag's commit, with annotated tags resolved. null when the tag is not in the repository. |
assets | array | Release assets, ordered by name. |
Each asset has these fields.
| Field | Type | Notes |
|---|---|---|
id | string | Asset id. |
name | string | File name, unique within the release. |
contentType | string | |
size | number | Bytes. |
downloads | number | Download count. |
url | string | The download route for this asset. |
createdAt | string | ISO timestamp. |
Read releases
List releases
GET /api/repos/{owner}/{repo}/releases Returns { releases, more }. Writers get drafts first, then published releases, newest first. A page holds 30 releases. more is true when a next page exists.
| Query | Type | Notes |
|---|---|---|
page | integer, optional | Starts at 1. |
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
"https://status.sailfork.com/api/repos/fenil/ocean-landing/releases?page=1" {
"releases": [
{
"id": "6f1c2a52-8d34-4b8e-9d8a-2f0f5c1d7a10",
"tag": "v1.2.0",
"title": "Tide tables",
"notes": "Adds tide tables to the harbor page.",
"draft": false,
"prerelease": false,
"author": "fenil",
"fromGithub": false,
"createdAt": "2026-11-02T18:04:11Z",
"publishedAt": "2026-11-02T18:04:11Z",
"sha": "9b4d0c1e7a3f5d2c8e6b1a0f4c7d9e2b3a5c6d8f",
"assets": [
{
"id": "0d7e6b4a-3c1f-4a9e-8b2d-5e7f1a3c9d60",
"name": "ocean-landing-1.2.0.tar.gz",
"contentType": "application/gzip",
"size": 1048576,
"downloads": 12,
"url": "https://status.sailfork.com/api/repos/fenil/ocean-landing/releases/assets/0d7e6b4a-3c1f-4a9e-8b2d-5e7f1a3c9d60/ocean-landing-1.2.0.tar.gz",
"createdAt": "2026-11-02T18:10:40Z"
}
]
}
],
"more": false
} Get a release by tag
GET /api/repos/{owner}/{repo}/releases/tags/{tag} Returns one release. Write the tag as it is, slashes included, for example releases/tags/rel/2026.11. A draft answers 404 unless you are a writer. A missing tag also answers 404.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
https://status.sailfork.com/api/repos/fenil/ocean-landing/releases/tags/v1.2.0 Create and change releases
Create a release
POST /api/repos/{owner}/{repo}/releases Needs write access and repo:write. Returns 201 with the release.
| Body field | Type | Notes |
|---|---|---|
tag | string, required | A valid git tag name: at most 255 bytes, no spaces, none of ~ ^ : ? * [ \, no ... Whitespace around it is trimmed. |
title | string, optional | At most 256 characters. |
notes | string, optional | Markdown, at most 125000 characters. |
draft | boolean, optional | Default false. A draft needs no tag yet. |
prerelease | boolean, optional | Default false. |
Unknown fields are rejected. A published release needs its tag in the repository, so push the tag first or save a draft.
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"tag":"v1.3.0","title":"Harbor lights","notes":"Dark mode for the harbor page.","draft":true}' \
https://status.sailfork.com/api/repos/fenil/ocean-landing/releases | Status | When |
|---|---|
403 | The repository is a GitHub-mirrored one, or you lack write access. |
409 | The tag already has a release. Edit that one instead. |
422 | Invalid tag, title or notes too long, or a published release whose tag is not in the repository. |
Edit a release
PATCH /api/repos/{owner}/{repo}/releases/{id} Needs write access and repo:write. Send only the fields you want to change: tag, title, notes, draft, prerelease, with the same limits as create. Returns the release.
- Publishing a draft (
"draft": false) or moving a published release to another tag needs that tag to exist in the repository. "draft": trueunpublishes a release and clearspublishedAt.- Errors match create:
403on a mirrored repository,404for an unknown id,409when another release has the tag,422for invalid values.
curl -X PATCH -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"draft":false}' \
https://status.sailfork.com/api/repos/fenil/ocean-landing/releases/6f1c2a52-8d34-4b8e-9d8a-2f0f5c1d7a10 Delete a release
DELETE /api/repos/{owner}/{repo}/releases/{id} Needs write access and repo:write. Returns 204. The release's assets are deleted with it. The git tag stays. 409 means the repository is under a hold and cannot be deleted from right now.
Release assets
Upload an asset
POST /api/repos/{owner}/{repo}/releases/{id}/assets Needs write access and repo:write. The body is the raw file, streamed. Returns 201 with the asset.
| Header | Notes |
|---|---|
Content-Type | Stored as the asset's contentType. Defaults to application/octet-stream when missing or not a media type. |
X-Filename | The asset name, percent-encoded. Directories are dropped and the name is cut to 200 characters. Without it the name is file. |
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" \
-H "Content-Type: application/gzip" -H "X-Filename: ocean-landing-1.3.0.tar.gz" \
--data-binary @ocean-landing-1.3.0.tar.gz \
https://status.sailfork.com/api/repos/fenil/ocean-landing/releases/6f1c2a52-8d34-4b8e-9d8a-2f0f5c1d7a10/assets {
"id": "0d7e6b4a-3c1f-4a9e-8b2d-5e7f1a3c9d60",
"name": "ocean-landing-1.3.0.tar.gz",
"contentType": "application/gzip",
"size": 1048576,
"downloads": 0,
"url": "https://status.sailfork.com/api/repos/fenil/ocean-landing/releases/assets/0d7e6b4a-3c1f-4a9e-8b2d-5e7f1a3c9d60/ocean-landing-1.3.0.tar.gz",
"createdAt": "2026-11-10T17:22:03Z"
} | Status | When |
|---|---|
404 | The release id does not exist in this repository. |
409 | The release already has an asset with that name. Delete it first. |
413 | The file is over 2 GB. |
422 | The file is empty, or the release already holds 1000 assets. |
429 | You have uploaded 10 GB of release assets in the last rolling day. |
Delete an asset
DELETE /api/repos/{owner}/{repo}/releases/{id}/assets/{assetId} Needs write access and repo:write. Returns 204, or 404 when the asset is not on that release.
Download an asset by id
GET /api/repos/{owner}/{repo}/releases/assets/{assetId}/{name} Returns the file bytes. This is the url of an asset. Anyone can download from a public repository. Drafts are visible to writers only. {name} only makes the link readable; the asset id picks the file. Range requests work. A GET of the whole file, or a Range starting at byte 0, adds one to downloads. HEAD requests and resumed ranges do not.
Files are served as downloads unless they are PNG, JPEG, GIF, WebP, AVIF, MP4, WebM, QuickTime or PDF, which can show inline.
Download an asset by tag and name
GET /{owner}/{repo}/releases/download/{tag}/{name} This is a site URL, not under /api. It uses GitHub's URL shape, so installers, Homebrew formulas and scripts can name a file without knowing its id. It answers 302 to a storage link that works for five minutes, with Cache-Control: no-store. Visibility, the draft rule and download counting match the route above. A missing tag or file name answers 404.
curl -L -O https://status.sailfork.com/fenil/ocean-landing/releases/download/v1.2.0/ocean-landing-1.2.0.tar.gz Latest CLI build
Get the latest CLI release
GET /api/cli/latest Public, no token. Returns the newest verified release of the Sailfork CLI, with a download URL and SHA-256 for each platform. The install script and sailfork upgrade read it. A release is served only after every sailfork-cli-<target> archive matched its SHA256SUMS file and carried a valid release signature.
| Query | Type | Notes |
|---|---|---|
version | string, optional | Return this version instead of the newest, prereleases included. Write 0.2.14; v0.2.14 also works. Anything else is 422. |
curl https://status.sailfork.com/api/cli/latest {
"version": "0.2.14",
"tag": "sailfork-cli-v0.2.14",
"publishedAt": "2026-11-05T21:30:00Z",
"releaseUrl": "https://status.sailfork.com/sailfork/cli/releases/tag/sailfork-cli-v0.2.14",
"checksumsUrl": "https://status.sailfork.com/sailfork/cli/releases/download/sailfork-cli-v0.2.14/SHA256SUMS",
"targets": {
"aarch64-apple-darwin": {
"url": "https://status.sailfork.com/sailfork/cli/releases/download/sailfork-cli-v0.2.14/sailfork-cli-aarch64-apple-darwin.tar.gz",
"sha256": "3f1a9c0e7b5d2a8c4e6f1b3d5a7c9e0f2b4d6a8c0e1f3a5b7c9d1e3f5a7b9c0d"
}
}
} targets is keyed by Rust target triple, and each url is a download by tag route. publishedAt can be null.
| Status | When |
|---|---|
404 | No release matches, or the requested version does not exist. |
422 | version is not in the form 0.2.14. |
503 | No release has passed its check yet, or the release repository is not public. The error says why. |
A newest release that has not been checked yet is checked in the background while the last verified one is served. A release that failed its check is skipped.