REST API

Programmatic access to the Releases index via HTTP.

All endpoints are prefixed with /v1 and return JSON.

Authentication

Read endpoints are public. Write endpoints require a Bearer token:

curl -H "Authorization: Bearer YOUR_KEY" https://api.releases.sh/v1/...

Stats

`GET /v1/stats`

Returns counts of organizations, sources, releases, and products.

Organizations

`GET /v1/orgs`

List all organizations with source counts and metadata.

`GET /v1/orgs/:slug`

Get organization details including sources, products, and release metrics.

`GET /v1/orgs/:slug/releases`

Paginated release feed across all sources in the org.

Param	Description
`cursor`	Pagination cursor from previous response
`limit`	Results per page (1-100, default 20)

`GET /v1/orgs/:slug/activity`

Weekly release activity for the organization.

Param	Description
`from`	Start date (YYYY-MM-DD)
`to`	End date (YYYY-MM-DD)

Products

`GET /v1/products`

List products. Filter with ?orgId=....

`GET /v1/products/:slug`

Get product details by slug or ID.

Sources

`GET /v1/sources`

List sources with filters.

Param	Description
`independent`	Only sources not tied to an org
`orgSlug`	Filter by organization slug
`productSlug`	Filter by product slug
`hasFeed`	Only sources with a feed URL
`query`	Substring search on name, slug, or URL
`category`	Filter by category

`GET /v1/sources/:slug`

Source details with paginated releases.

Param	Description
`page`	Page number
`pageSize`	Results per page

`GET /v1/sources/:slug/activity`

Weekly release activity for a source. Accepts from and to date params.

`GET /v1/sources/:slug/recent-releases`

Releases after a cutoff date. Requires ?cutoff=ISO-date.

`GET /v1/sources/:slug/changelog`

Read the canonical CHANGELOG.md (or CHANGES.md / HISTORY.md / RELEASES.md / NEWS.md) tracked for a GitHub source. Supports heading-aligned range slicing by characters or by tokens (cl100k_base) — useful for agent-friendly Context7-style access to large files (e.g. Apollo Client's 700KB CHANGELOG).

Param	Description
`offset`	Character offset into the full file. Snapped forward to the next `##`/`###`/`#` heading unless 0.
`limit`	Target slice size in characters. The slice ends at a heading boundary; overshoots to the next heading if a single section is bigger than `limit`. Default 40000 when either range param is present and `tokens` is not set.
`tokens`	Target slice size in tokens (cl100k_base). Walks sections forward under the budget with the same heading-snap and overshoot rules as `limit`. Takes precedence when both are passed. Recommended brackets: `2000` / `5000` / `10000` / `20000`.

With no range params, the full file is returned (back-compat). Response body:

{
  "path": "CHANGELOG.md",
  "filename": "CHANGELOG.md",
  "url": "https://github.com/org/repo/blob/HEAD/CHANGELOG.md",
  "rawUrl": "https://raw.githubusercontent.com/org/repo/HEAD/CHANGELOG.md",
  "bytes": 732634,
  "fetchedAt": "2026-04-14T12:17:50.633Z",
  "content": "## 4.1.7\n\n...",
  "offset": 0,
  "limit": 40000,
  "tokens": 5000,
  "nextOffset": 18932,
  "totalChars": 732571,
  "sliceTokens": 4871,
  "totalTokens": 182445
}

totalTokens is cached per file and always returned. tokens (echoed budget) and sliceTokens (actual encoded count of the returned content) are only populated when the request used token mode.

Note: totalTokens is an exact cl100k_base count for files under 256KB. For files above that cap, the value is approximated as ceil(totalChars / 4) to keep the upsert path fast. sliceTokens is always exact because slices stay under the cap. If you need a precise total for a large file, sum sliceTokens across a full walk via nextOffset.

Chain successive requests by passing the returned nextOffset back as the next offset. nextOffset is null when the slice reaches the end of the file. The canonical file is refreshed on a 24h TTL by the API worker cron for github sources.

Releases

`GET /v1/releases/latest`

Unified feed of the most recent releases. Backs the CLI's tail/latest command and the public homepage activity feed. The default unfiltered request is cached in KV for 5 minutes (X-Cache: HIT|MISS); any request that applies source, org, a non-default count, or include_coverage=true bypasses the cache (X-Cache: BYPASS) and is served directly from the database.

Param	Description
`count`	Max releases to return (1-100, default 10)
`source`	Source slug or id to filter by (mutually exclusive with `org`)
`org`	Org slug or id to filter by (mutually exclusive with `source`)
`include_coverage`	Include coverage-side rows (default `false` — hides duplicate-launch coverage items)

Coverage-side releases are hidden by default so the feed shows one entry per launch. source and org both accept either a slug or an id (src_…, org_…).

`GET /v1/releases/:id`

Get full release details by ID, including content and media assets.

Search

`GET /v1/search`

Hybrid search across orgs, products, sources, releases, and CHANGELOG chunks. FTS5 and vector similarity are fused with Reciprocal Rank Fusion; hybrid is the default.

Param	Description
`q`	Search query (required)
`limit`	Max results (default 20)
`offset`	Pagination offset
`mode`	`lexical`, `semantic`, or `hybrid` (default `hybrid`). `lexical` returns the legacy FTS-only shape.

Hybrid and semantic responses include a ranked chunks array interleaved with release hits, plus mode, degraded, and degradedReason fields. degraded: true means the request fell back to lexical because Vectorize or the embedding provider was unavailable — results are still returned.

Each chunk hit carries sourceSlug, orgSlug, filePath, offset, length, heading, snippet, and score so clients can chain into GET /v1/sources/:slug/changelog?offset=... for surrounding context.

`GET /v1/related/releases`

Semantically similar releases for an anchor release. Reuses the release's existing vector — no re-embedding.

Param	Description
`release`	Anchor release id (required)
`scope`	`org` (same organization) or `global` (default `global`)
`limit`	Max results (1-20, default 5)

Degrades to an empty items array with degraded: true when Vectorize bindings are unavailable. Anchor is excluded from its own results. Cached for 5 minutes.

`GET /v1/related/sources`

Semantically similar sources for an anchor source. Uses the entity vector.

Param	Description
`source`	Anchor source slug or id (required)
`scope`	`org` (siblings in the same organization) or `global` (default `global`)
`excludeOrgSlug`	Optional org slug to exclude from global results (used to avoid overlap when rendering both scopes together)
`limit`	Max results (1-20, default 5)

Same degradation and anchor-exclusion semantics as /v1/related/releases.

Summaries

`GET /v1/summaries`

Get cached AI summaries for a source.

Param	Description
`sourceSlug`	Source slug (required, or use sourceId)
`type`	`rolling` or `monthly`
`year`	Filter by year (for monthly summaries)
`month`	Filter by month

Web URL formats

Every org and source page on releases.sh has three machine-readable URL suffixes alongside the HTML:

Suffix	Content-Type	Use case
`.json`	`application/json`	Programmatic / agent consumption
`.md`	`text/markdown`	LLM context, prompt-friendly output
`.atom`	`application/atom+xml`	Feed readers (Feedly, Inoreader, NetNewsWire), webhook bots

https://releases.sh/anthropic          # HTML
https://releases.sh/anthropic.json     # JSON
https://releases.sh/anthropic.md       # Markdown
https://releases.sh/anthropic.atom     # Atom 1.0 feed

The same suffixes work on source pages (/{org}/{source}.atom) and standalone sources (/source/{slug}.atom).

Atom feeds include the 50 most recent entries with stable <id>s, RFC 3339 timestamps, and HTML-typed content. They respond to If-None-Match / If-Modified-Since with 304 Not Modified when unchanged — drop in to any feed reader or polling tool without a custom adapter. The feed is also advertised from each HTML page via <link rel="alternate" type="application/atom+xml"> for browser auto-discovery.