List changelog entries

Goal

Read the managed changelog corpus (docs/releases/*.yaml) over HTTP to render your own release notes page, drive a CI bot, or sync release entries into a CRM. The endpoint serves the same data the docs-site widget consumes.

Prerequisites

None — the endpoint serves public-audience entries to anonymous callers. audience=admin entries are served only with a console session and the owner or admin role.

Steps

1. List the latest entries

curl -X GET 'https://api.veriko.mx/v1/public/changelog?lang=en&limit=25'

Response (200):

{
  "data": [
    {
      "id": "url-convention",
      "schema_version": 1,
      "release_version": "1.49.6",
      "audience": ["public"],
      "category": "breaking",
      "severity": "medium",
      "breaking": true,
      "title": "URL convention formalized + 13 path moves",
      "summary": "...",
      "permalink": "/changelog/v1.49.6/url-convention",
      "tags": ["api", "openapi", "routes"]
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "limit": 25,
      "has_more": false,
      "next_cursor": null
    },
    "audience": "public",
    "lang": "en"
  }
}

2. Filter by category, date range, or language

Query param	Description
`lang`	`en` or `es`. Bilingual fields collapse to the requested locale.
`audience`	`public` (default for anonymous) or `admin` (console session with the owner or admin role only).
`category`	`feat`, `fix`, `breaking`, `deprecation`, `security`, `docs`, `infra`, `refactor`.
`from` / `to`	ISO 8601 date-time bounds (filter by release `published_at`).
`limit`	1–100, default 25.
`cursor`	Opaque base64 cursor from `meta.pagination.next_cursor`.
`include`	`summary` (default) or `body` (adds raw Markdown).

# Only breaking changes since the start of the year
curl 'https://api.veriko.mx/v1/public/changelog?category=breaking&from=2026-01-01T00:00:00Z'

3. Paginate

The response includes meta.pagination.next_cursor. Pass it back as ?cursor=… on the next request to fetch the next page. The cursor is opaque (base64-encoded JSON internally) — do not parse it client-side.

curl 'https://api.veriko.mx/v1/public/changelog?limit=10&cursor=eyJyZWxlYXNlX3ZlcnNpb24iOiIxLjQ3LjEi…'

4. ETag negotiation

The endpoint returns a weak ETag header. Send it back as If-None-Match on a subsequent request to receive 304 Not Modified without a body when the corpus has not changed:

curl -H 'If-None-Match: W/"a1b2c3d4"' \
     'https://api.veriko.mx/v1/public/changelog'

Use this to drive lightweight polling without re-downloading the payload every cycle.

Errors

Status	Code	Cause
—	—	A malformed cursor is not an error: it is ignored and the listing starts from the beginning.
400	`invalid_timestamp`	The date parameter is not ISO 8601.
401	`unauthorized`	Requested `audience=admin` while unauthenticated.
403	`permission_denied`	Authenticated, but without the owner or admin role.
429	`rate_limit_exceeded`	Polling too aggressively.

Notes

Embargoed entries (embargo_until in the future) are excluded for anonymous and public-audience requests. Admins see them.
Unpublished entries (published_at: null) are excluded for public-audience requests. Admins see them.
These routes live under /v1/public/*, the namespace reserved for the public catalogue served without authentication.