# 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](https://sailfork.com/docs/releases). Authentication, scopes, errors and paging rules are in the [REST API overview](https://sailfork.com/docs/api); 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](https://sailfork.com/docs/api#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

| 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](#download-an-asset-by-id) for this asset. |
| `createdAt` | string | ISO timestamp. |

## Read releases

### List releases

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

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://sailfork.com/api/repos/fenil/ocean-landing/releases?page=1"
```

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

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

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  https://sailfork.com/api/repos/fenil/ocean-landing/releases/tags/v1.2.0
```

## Create and change releases

### Create a release

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

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

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

```sh
curl -X PATCH -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"draft":false}' \
  https://sailfork.com/api/repos/fenil/ocean-landing/releases/6f1c2a52-8d34-4b8e-9d8a-2f0f5c1d7a10
```

### Delete a release

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

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

```sh
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://sailfork.com/api/repos/fenil/ocean-landing/releases/6f1c2a52-8d34-4b8e-9d8a-2f0f5c1d7a10/assets
```

```json
{
  "id": "0d7e6b4a-3c1f-4a9e-8b2d-5e7f1a3c9d60",
  "name": "ocean-landing-1.3.0.tar.gz",
  "contentType": "application/gzip",
  "size": 1048576,
  "downloads": 0,
  "url": "https://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

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

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

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

```sh
curl -L -O https://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

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

```sh
curl https://sailfork.com/api/cli/latest
```

```json
{
  "version": "0.2.14",
  "tag": "sailfork-cli-v0.2.14",
  "publishedAt": "2026-11-05T21:30:00Z",
  "releaseUrl": "https://sailfork.com/sailfork/cli/releases/tag/sailfork-cli-v0.2.14",
  "checksumsUrl": "https://sailfork.com/sailfork/cli/releases/download/sailfork-cli-v0.2.14/SHA256SUMS",
  "targets": {
    "aarch64-apple-darwin": {
      "url": "https://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](#download-an-asset-by-tag-and-name) 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.

---

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