Packages

Get a package or repository changelog

Read release notes for a package or repository, ordered newest first. Retrieve recent releases to catch up on changes, or a version range to review everything between two releases.

Use this endpoint to understand what changed before updating a dependency. You can request just the release timeline or include the full release-note text.

Selector catalogue

Use the following selectors with the fields query parameter to choose which fields the response includes. See Choose what the response includes for details.

Selector	Data	Default
`statements`	Parsed statement page and release totals; no classification work. Timeline metadata remains required.	No
`statements.classification`	Available classifications with uncertainty/provenance; implies statement items and assessment coverage. Missing answers are null; waits are bounded.	No
`statements.full_text`	Uncut returned quotes and retained predecessor context; implies items independently of classification and raw release bodies.	No
`statements.coverage`	Assessment coverage and page metadata without item text; does not imply items. Reduces payload, not classification work.	No
`entries`	Complete timeline metadata: version, normalized_version, published_at and html_url when available.	Yes
`entries.body`	Third-party Markdown bodies; implies the complete entries metadata group.	Yes
`entries.*`	Explicit union of entries and entries.body.	No

Parsed statements are opt-in and require package addressing. statements returns parsed quotes and release totals without requesting labels. statements.classification includes available labels and assessment coverage; selected unavailable labels are null. statements.coverage requests coverage without item text. statements.full_text returns uncut quotes and predecessor context independently of raw release bodies or labels. Timeline metadata remains required. Explicit fields replaces defaults; defaults and entries.* do not include statements.

Page controls are computation inputs, separate from fields. Active tiers request labels and imply assessment coverage, including with coverage-only selection; unassessed statements do not match. Zero matches with incomplete coverage do not prove absence of actionable changes. Coverage-only reduces payload, not assessment work. Waiting is bounded, so answers can remain unavailable. Read every page to exhaust matching parsed bullets; complete text only means uncut returned quotes. Offsets address current notes/labels without a snapshot guarantee. Compare available coverage, versions and source URLs and restart at offset zero if they change; unchanged counts/URLs cannot detect every wording change.

GET

changelog

GET /v1/changelog?registry=npm&name=express HTTP/1.1
Host: api.githits.dev
Authorization: Bearer <token>

{
  "entries": [
    {
      "body": "## Changes\nBug fixes.",
      "html_url": "https://github.com/expressjs/express/releases/tag/5.2.1",
      "normalized_version": "5.2.1",
      "published_at": "2026-01-15T12:00:00Z",
      "version": "5.2.1"
    }
  ],
  "mode": "latest",
  "package": {
    "limit": 10,
    "name": "express",
    "registry": "npm",
    "to_version": "5.2.1"
  },
  "source": "releases"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-GitHits-Client-Name

string

Optional client attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.

X-GitHits-Client-Version

string

Optional client-version attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped.

X-GitHits-Agent

string

Optional agent attribution: trimmed printable ASCII, at most 160 bytes. Invalid optional values are dropped.

X-GitHits-Session-ID

string

Optional caller-defined session ID: one to 64 ASCII letters, digits, underscores or hyphens, preserved exactly. Supply the header at most once. Invalid supplied IDs return 400 INVALID_SESSION_ID; no session is created.

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9_-]{1,64}$

Query Parameters

registry

enum<string>

Canonical lowercase registry, required together with name and mutually exclusive with repo_url. Same registry set as package inspection.

Available options:

npm,

pypi,

hex,

crates,

vcpkg,

zig,

nuget,

maven,

packagist,

rubygems,

go,

swift

name

string

Registry package name, preserved exactly and limited to 255 UTF-8 bytes without control characters. Required with registry, forbidden with repo_url.

repo_url

string

Full HTTP(S) repository URL; mutually exclusive with registry/name. The source owns supported repository hosts and canonicalization.

git_ref

string

Optional repository file branch/tag lookup context; trimmed, blank is absent. Not a version bound or resolved commit assertion.

from_version

string

Normalized lower range bound, exclusive for released versions; enables complete-range mode and forbids limit. With from_version=1.0.0&to_version=1.2.0, releases are newer than 1.0.0 through 1.2.0 inclusive. Blank is absent; Go numeric versions gain lowercase v and existing lowercase v is accepted (uppercase V is rejected), Swift and Packagist allow native v/V tags, other modes reject numeric v/V-prefixed tags. Special unreleased entries follow source-specific handling.

to_version

string

Optional normalized upper bound, inclusive for released versions; special unreleased entries follow source-specific handling. Omitted or latest resolves the latest package version; repository mode remains uncapped. Alone this keeps latest-count mode.

limit

integer

default:10

Latest-mode positive integer count, default 10, minimum 1, maximum 50. Forbidden with nonblank from_version. Range results have no count cap or pagination.

Required range: 1 <= x <= 50

fields

string

default:entries,entries.body

Finite response groups: entries, entries.body, entries.*, statements, statements.classification, statements.full_text, statements.coverage. Defaults to entries,entries.body. Explicit selection replaces defaults; entries.body includes entry metadata. Select entries alone for a timeline without release-note bodies. This reduces transfer size, but the changelog is still retrieved.

Use the case-sensitive selectors in the catalogue. Order and duplicate selectors do not affect the result. ASCII whitespace around selectors is ignored. The decoded value is limited to 2048 UTF-8 bytes. Empty or unknown selectors and repeated fields query parameters return 400 VALIDATION_ERROR. A group does not include nested groups unless the catalogue says so; only listed wildcard bundles are supported.

statements_first

integer

default:100

Matching statement page size. Requires a statement selector; independent of release limit.

Required range: 1 <= x <= 100

statements_offset

integer

default:0

Matching offset into current notes/labels, not a retained snapshot. Requires a statement selector.

Required range: 0 <= x <= 2147483647

statements_tiers

string

Comma-separated must_act, should_know, no_impact, unclassified. Omit for all parsed statements including unassessed. Active filters request labels, apply before paging and imply assessment coverage; allowed with coverage-only. Requires a statement selector. Empty or unknown tokens fail validation.

Response

Available changelog entries, newest first

Latest or range release timeline with optional paged parsed statements.

entries

object[]

required

Release entries, newest first. An empty array means the available release history had no matches. Range results are not truncated.

Show child attributes

mode

enum<string>

required

Effective mode, determined by the presence of from_version.

Available options:

latest,

range

package

object

required

Required resolved addressing and effective query bounds from the source.

Show child attributes

requested_git_ref

string

Requested git ref after trimming; request context, not a verified resolved commit or source provenance.

source

string

Top-level source (usually releases, changelog_file or hexdocs), omitted for registry-only timelines. Does not describe each entry's body availability or attest a resolved git ref.

statements

object

Selected parsed statements and source-wide coverage; omitted by existing defaults.

Show child attributes

⌘I

GET /v1/changelog?registry=npm&name=express HTTP/1.1
Host: api.githits.dev
Authorization: Bearer <token>

{
  "entries": [
    {
      "body": "## Changes\nBug fixes.",
      "html_url": "https://github.com/expressjs/express/releases/tag/5.2.1",
      "normalized_version": "5.2.1",
      "published_at": "2026-01-15T12:00:00Z",
      "version": "5.2.1"
    }
  ],
  "mode": "latest",
  "package": {
    "limit": 10,
    "name": "express",
    "registry": "npm",
    "to_version": "5.2.1"
  },
  "source": "releases"
}

Get started

v1 reference

Get a package or repository changelog

Selector catalogue

Authorizations

Headers

Query Parameters

Response