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:read scope 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:write scope. Writers also see drafts.
  • Hidden repositories. A private repository answers 404 to 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 403 and name the mirror. Those releases, with their assets and download counts, come from GitHub and have fromGithub: true.

The release object

FieldTypeNotes
idstringRelease id, used in edit, delete and upload routes.
tagstringThe git tag, slashes included.
titlestringMay be empty. Show the tag then.
notesstringMarkdown.
draftbooleanDrafts are visible to writers only.
prereleaseboolean
authorstringA handle, or github:<login> for a GitHub author without a Sailfork account.
fromGithubbooleantrue for releases that came from a GitHub mirror or move.
createdAtstringISO timestamp.
publishedAtstring or nullnull while a draft.
shastring or nullThe tag's commit, with annotated tags resolved. null when the tag is not in the repository.
assetsarrayRelease assets, ordered by name.

Each asset has these fields.

FieldTypeNotes
idstringAsset id.
namestringFile name, unique within the release.
contentTypestring
sizenumberBytes.
downloadsnumberDownload count.
urlstringThe download route for this asset.
createdAtstringISO 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.

QueryTypeNotes
pageinteger, optionalStarts 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 fieldTypeNotes
tagstring, requiredA valid git tag name: at most 255 bytes, no spaces, none of ~ ^ : ? * [ \, no ... Whitespace around it is trimmed.
titlestring, optionalAt most 256 characters.
notesstring, optionalMarkdown, at most 125000 characters.
draftboolean, optionalDefault false. A draft needs no tag yet.
prereleaseboolean, optionalDefault 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
StatusWhen
403The repository is a GitHub-mirrored one, or you lack write access.
409The tag already has a release. Edit that one instead.
422Invalid 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": true unpublishes a release and clears publishedAt.
  • Errors match create: 403 on a mirrored repository, 404 for an unknown id, 409 when another release has the tag, 422 for 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.

HeaderNotes
Content-TypeStored as the asset's contentType. Defaults to application/octet-stream when missing or not a media type.
X-FilenameThe 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"
}
StatusWhen
404The release id does not exist in this repository.
409The release already has an asset with that name. Delete it first.
413The file is over 2 GB.
422The file is empty, or the release already holds 1000 assets.
429You 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.

QueryTypeNotes
versionstring, optionalReturn 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.

StatusWhen
404No release matches, or the requested version does not exist.
422version is not in the form 0.2.14.
503No 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.

Loading Sailfork