Documentation menu

Read API and webhooks

On Pro, your published changelog is available two ways for machines: a read API you can poll, and outbound webhooks we send when an entry publishes. Both are managed in the repo's settings, under API. (If you just want the entries in a feed reader or an existing tool, the RSS and Atom feeds are free and need no token — see Your changelog page.)

Tokens

Create an API token from the API settings page. Tokens look like clp_live_… and are shown once, at creation — we store only a hash, so a lost token can't be recovered, only revoked and replaced. A token is scoped to all the repos you own, or to a subset you pick.

Creating and revoking tokens is limited to the account owner.

The read API

Two endpoints, both returning only published entries — drafts and archived entries are never exposed:

GET /api/v1/repos/:owner/:repo/entries
GET /api/v1/repos/:owner/:repo/entries/:id

Authenticate with the token as a bearer header:

curl -H "Authorization: Bearer clp_live_..." \
  https://changelogpilot.com/api/v1/repos/acme/widgets/entries

The list returns entries newest first as { "data": [...], "next_cursor": "..." }. Page with ?limit (default 20, maximum 100) and pass next_cursor back as ?cursor to fetch the next page; a null next_cursor means you've reached the end.

Each entry looks like:

{
  "id": "…",
  "title": "v1.4.0",
  "published_at": "2026-08-21T02:11:00.000Z",
  "url": "https://changelog.yourproduct.com/#v1-4-0",
  "content_html": "<p>…</p>",
  "content_markdown": "…",
  "pr_numbers": [141, 143],
  "tag": "v1.4.0"
}

url is the entry's canonical public permalink — your custom domain while it's serving, the platform URL otherwise.

Rate limit

Each token gets about 60 requests per minute. Past that you'll get a 429 with a Retry-After header. Cache on your side rather than polling hot.

Outbound webhooks

Add an HTTPS endpoint in the API settings and we POST to it whenever an entry publishes. The signing secret (whsec_…) is shown once, at creation. Adding and removing endpoints, like creating and revoking tokens, is limited to the account owner. The payload:

{
  "event": "entry.published",
  "delivered_at": "2026-08-21T02:11:03.000Z",
  "repo": { "owner": "acme", "repo": "widgets" },
  "entry": { … }
}

entry is exactly the read-API entry shape above.

Verifying deliveries

Every delivery carries three headers:

  • X-ChangelogPilot-Signature — sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with your signing secret. Recompute it and compare with a constant-time equality before trusting the payload.
  • X-ChangelogPilot-Timestamp — the send time (unix seconds), so you can reject stale replays.
  • X-ChangelogPilot-Delivery — a stable delivery id. Retries of the same delivery reuse it, so you can deduplicate.

Retries

Respond with a 2xx quickly — anything else, or no answer within 10 seconds, counts as a failure. A failed delivery is retried four more times over roughly the next hour and a half, with increasing gaps. Every retry re-sends the identical body under the identical signature and delivery id. Recent deliveries, with status and response codes, are listed on the API settings page.

If you downgrade

Tokens and webhook endpoints are kept, but stop working — API requests are refused and deliveries pause until you're back on Pro. Nothing needs recreating.