# LogPulse — full developer docs

> Machine-readable changelogs for coding agents: versions, breaking changes, migration steps and deprecations over REST, JSON Feed, llms.txt and a public MCP server.

## Concepts

- A **changelog** belongs to one product and has a slug (e.g. `acme`), optional repository URL and package names.
- A **release** has: version (unique, e.g. 2.0.0), title, summary, category (new | improved | fixed), Markdown notes, published_at, breaking_changes[] ({summary, affects?, migration?}) and deprecations[] ({item, replacement?, removal_version?, note?}).
- Feeds only include releases that are published, not scheduled for later and not targeted at a user segment.
- A **version diff** covers releases after `from` up to and including `to`. Comparison is semver-style: "v2.0.0" = "2.0.0", pre-releases sort before the release, two/four-part versions work. Unversioned releases are skipped in diffs. Unknown versions add a note instead of failing.

## MCP server

- Endpoint: https://release-ripple-roadmap.lovable.app/mcp
- Transport: Streamable HTTP.
- Reading: no authentication; only published releases and public roadmap items are returned.
- Writing (publish_release, post_roadmap_update): send a LogPulse API key as the HTTP header `Authorization: Bearer lp_…`, configured in the MCP client. Keys are never tool arguments.
- Rate limits: 120 requests/minute per IP, 120/minute per API key; HTTP 429 with Retry-After when exceeded. convert_changelog also uses the converter budget (10/minute, 100/day per IP).
- Server card: https://release-ripple-roadmap.lovable.app/mcp/server-card (also https://release-ripple-roadmap.lovable.app/.well-known/mcp/server-card.json); listed in https://release-ripple-roadmap.lovable.app/.well-known/api-catalog and https://release-ripple-roadmap.lovable.app/.well-known/ai-catalog.json.
- Claude Code (read): `claude mcp add --transport http logpulse https://release-ripple-roadmap.lovable.app/mcp`
- Claude Code (read + publish): `claude mcp add --transport http logpulse https://release-ripple-roadmap.lovable.app/mcp --header "Authorization: Bearer $LOGPULSE_API_KEY"`
- Cursor (.cursor/mcp.json): `{"mcpServers":{"logpulse":{"url":"https://release-ripple-roadmap.lovable.app/mcp","headers":{"Authorization":"Bearer ${env:LOGPULSE_API_KEY}"}}}}` (drop "headers" for read-only)

### search_changelogs (no sign-in)

Find a public LogPulse changelog by package name, repository, product name or slug. Returns slugs to use with the other tools.

Inputs:
- `query` (string, required): Package (e.g. @acme/analytics), repository (acme/analytics-js), product name or slug.
- `limit` (integer (1–25)): Maximum results. Default 10.

Example: `{"query":"@acme/analytics"}`

### get_changelog (no sign-in)

Get a changelog's name, repository, packages, latest version and feed links.

Inputs:
- `changelog` (string, required): Changelog slug, e.g. "acme". Use search_changelogs to find it from a package or repository name.

Example: `{"changelog":"acme"}`

### list_releases (no sign-in)

List published releases, newest first, with versions, breaking changes, migration steps and deprecations.

Inputs:
- `changelog` (string, required): Changelog slug, e.g. "acme". Use search_changelogs to find it from a package or repository name.
- `limit` (integer (1–100)): Maximum releases. Default 20.
- `since` (string (date-time)): Only releases published at or after this ISO 8601 time.
- `breaking_only` (boolean): Only releases that contain breaking changes.

Example: `{"changelog":"acme","limit":5}`

### get_release (no sign-in)

Get one release by version (2.0.0 or v2.0.0) or URL slug, with full notes, breaking changes and deprecations.

Inputs:
- `changelog` (string, required): Changelog slug, e.g. "acme". Use search_changelogs to find it from a package or repository name.
- `release` (string, required): Version like 2.0.0, or the release's URL slug.

Example: `{"changelog":"acme","release":"2.0.0"}`

### compare_versions (no sign-in)

Answer “what changed between two versions, and what do I need to change?”: breaking changes with migration steps, deprecations and every release after `from` up to `to`.

Inputs:
- `changelog` (string, required): Changelog slug, e.g. "acme". Use search_changelogs to find it from a package or repository name.
- `from` (string): The version the user is on, e.g. 1.4.0. Omit to start from the first release.
- `to` (string): The version to upgrade to. Omit for the latest.
- `format` ("markdown" | "json"): markdown (default) returns an upgrade guide; json returns structured data.

Example: `{"changelog":"acme","from":"1.4.0","to":"2.0.0"}`

### get_roadmap (no sign-in)

Get the public roadmap: items under review, planned, in progress and shipped, with vote counts.

Inputs:
- `changelog` (string, required): Changelog slug, e.g. "acme". Use search_changelogs to find it from a package or repository name.
- `status` ("under_review" | "planned" | "in_progress" | "shipped"): Only items in this column.

Example: `{"changelog":"acme","status":"in_progress"}`

### convert_changelog (no sign-in)

Turn any project's CHANGELOG.md text, or a GitHub release, releases page, repository or changelog file URL, into a machine-readable changelog: versions, dates, breaking changes with migration steps, and deprecations. Works for projects that aren't on LogPulse.

Inputs:
- `url` (string (GitHub URL)): A release (…/releases/tag/v1.2.0), the releases page, a repository or a CHANGELOG.md file. Use this or markdown.
- `markdown` (string (≤900 KB)): The changelog text itself. Use this or url.
- `name` (string): Project name to use in the summary.
- `include_notes` (boolean): Include each release's full notes in the JSON. Default false.

Example: `{"url":"https://github.com/vercel/next.js/releases/tag/v15.0.0"}`

### publish_release (API key with releases:write)

Publish a release note to your own changelog right after shipping — with version, breaking changes, migration steps and deprecations. Goes live in the hosted changelog, the widget and release emails.

Inputs:
- `title` (string (≤140), required): Short, user-facing headline.
- `version` (string): Semantic version like 2.1.0 (a leading v is dropped). Must be unique in your changelog.
- `summary` (string (≤280)): One-sentence summary shown in lists and feeds.
- `body` (string (markdown)): Full release notes.
- `category` ("new" | "improved" | "fixed"): Default new.
- `labels` (string[] (≤10)): Short labels, e.g. API, Dashboard.
- `status` ("published" | "draft"): published (default) goes live now, or at published_at. draft waits for a human to review it.
- `published_at` (string (date-time)): Schedule for later. Defaults to now.
- `breaking_changes` ({ summary, affects?, migration? }[]): What breaks for existing users, each with migration steps (markdown).
- `deprecations` ({ item, replacement?, removal_version?, note? }[]): What is deprecated, its replacement and planned removal version.
- `author_name` (string): Shown as the author. Defaults to the API key's name.
- `slug` (string): URL slug. Generated from the title when omitted.

Example: `{"title":"Webhooks retry automatically","version":"2.1.0","category":"improved","body":"Failed webhook deliveries now retry with backoff for 24 hours.","deprecations":[{"item":"retry_once option","replacement":"retry_policy","removal_version":"3.0.0"}]}`

### post_roadmap_update (API key with roadmap:write)

Add an item to your roadmap, or update one by id — move it to in progress or shipped, change its ETA, or link the release that shipped it.

Inputs:
- `id` (string (uuid)): Update this item instead of creating a new one. get_roadmap lists ids.
- `title` (string (≤140)): Item title. Required when creating.
- `description` (string | null): What and why, in a sentence or two.
- `status` ("under_review" | "planned" | "in_progress" | "shipped"): Roadmap column. New items default to planned.
- `label` (string | null): Short tag, e.g. API or Mobile.
- `eta` (string | null): Free text, e.g. Q3 or July.
- `is_public` (boolean): Show on the public roadmap. Defaults to true for new items.
- `linked_release` (string | null): Release id, version or slug that shipped this item.

Example: `{"id":"3f0c5c1e-7b7a-4b9e-9a54-2c1d8f6a1b20","status":"shipped","linked_release":"2.1.0"}`

## REST API

Base URL: https://release-ripple-roadmap.lovable.app/api/public/v1. OpenAPI: https://release-ripple-roadmap.lovable.app/openapi.json. Feed endpoints are public, CORS-enabled and cached for 60 seconds. Publishing endpoints need `Authorization: Bearer lp_…` (create keys in Dashboard → Agents & API; scopes read, releases:write, roadmap:write). Rate limits: 300 requests/minute per IP and 120/minute per API key.

- `GET /changelogs/{slug}`: Get a changelog. Name, repository, packages, latest version and links to every feed.
- `GET /changelogs/{slug}/releases`: List releases. Published releases, newest first, with versions, breaking changes, migration steps and deprecations.
- `GET /changelogs/{slug}/releases/{release}`: Get one release. Look up a release by version (2.0.0 or v2.0.0), URL slug or id.
- `GET /changelogs/{slug}/diff`: Compare two versions. Everything that changed after `from` up to and including `to`: releases, breaking changes with migration steps, and deprecations. Use format=markdown for an upgrade guide an agent can follow.
- `GET /changelogs/{slug}/roadmap`: Get the public roadmap. Public roadmap items with status and vote counts.
- `GET /changelogs/{slug}/feed.json`: JSON Feed 1.1. Standard JSON Feed with LogPulse extensions (`_logpulse`) for version, breaking changes and deprecations.
- `GET /changelogs/{slug}/llms.txt`: Changelog as llms.txt. The whole changelog as plain text for AI tools.
- `GET /search`: Find a changelog. Search by package name (e.g. @acme/analytics), repository, product name or slug.
- `GET /convert`: Convert a GitHub changelog. Free, no key. Fetches a GitHub release, releases page, repository (its CHANGELOG.md, or its releases) or markdown file and returns it as a machine-readable changelog plus an llms.txt-style summary. Rate limit: 10/minute and 100/day per IP.
- `POST /convert`: Convert a changelog. Free, no key. Send CHANGELOG.md text (JSON `markdown`, or a raw text/markdown body) or a GitHub `url`. Understands Keep a Changelog, conventional-changelog, changesets and GitHub release notes. Nothing is stored. Up to 1 MB. Rate limit: 10/minute and 100/day per IP.
- `GET /me` (API key): Check an API key. The workspace, plan and scopes an API key belongs to.
- `GET /releases` (API key): List your releases. Your workspace's releases including drafts. Scope: read.
- `POST /releases` (API key): Create a release. Creates a draft, or publishes right away with status=published (a future published_at schedules it). Publishing updates the widget, hosted changelog, feeds and — on Pro — emails subscribers. Scope: releases:write.
- `PATCH /releases/{release}` (API key): Update or publish a release. Send only the fields to change. Set status=published to publish a draft. Scope: releases:write.
- `GET /roadmap` (API key): List your roadmap. Every roadmap item in your workspace, private ones included. Scope: read.
- `POST /roadmap` (API key): Create a roadmap item. Creates an item, or updates one when `id` is given. Scope: roadmap:write.
- `PATCH /roadmap/{id}` (API key): Update a roadmap item. Move an item between columns (e.g. to shipped) and link the release that shipped it. Scope: roadmap:write.

Errors: `{"error":{"code","message","details?"}}` with codes bad_request (400), unauthorized (401), plan_limit (402), forbidden (403), not_found (404), conflict (409), payload_too_large (413), rate_limited (429), upstream_error (502, converter only).

## Changelog converter (free, no key)

Turn any CHANGELOG.md or GitHub release URL into a machine-readable changelog. Browser: https://release-ripple-roadmap.lovable.app/tools/changelog-to-json.

- `GET https://release-ripple-roadmap.lovable.app/api/public/v1/convert?url=<github url>[&format=llms][&include_notes=false]`
- `POST https://release-ripple-roadmap.lovable.app/api/public/v1/convert` with JSON `{"markdown": "…"}` or `{"url": "…"}` (optional "name", "format", "include_notes"), or a raw `text/markdown` body.
- GitHub URLs: …/releases/tag/<tag>, …/releases/latest, …/releases (100 most recent), a repository (CHANGELOG.md, else releases), or a markdown file (blob or raw.githubusercontent.com).
- Understands Keep a Changelog, conventional-changelog, changesets and GitHub release notes. Breaking changes: Breaking/Major Changes/Migration headings, BREAKING/⚠️/💥 markers, conventional commits with "!"; Removed items count as breaking unless the changelog marks breaking changes itself. Deprecations: Deprecated headings or "is deprecated" items, with replacement and removal version.
- Response: `{"changelog": {format: "logpulse.changelog.v1", name, source, latest_version, release_count, breaking_change_count, deprecation_count, unreleased, releases: [{version, title, date, url, prerelease, yanked, category, summary, changes{added,changed,fixed,removed,security,other}, has_breaking_changes, breaking_changes[], deprecations[], migration_guide, notes_markdown}], warnings}, "llms_txt": "…"}`
- Limits: 10/minute and 100/day per IP (shared with MCP convert_changelog); 1 MB per changelog. Nothing is stored; no AI is used.

## Discovery

- RFC 9727 API catalog: https://release-ripple-roadmap.lovable.app/.well-known/api-catalog (application/linkset+json; HEAD returns Link: <…>; rel="api-catalog")
- MCP server card: https://release-ripple-roadmap.lovable.app/mcp/server-card and https://release-ripple-roadmap.lovable.app/.well-known/mcp/server-card.json (application/mcp-server-card+json)
- AI catalog: https://release-ripple-roadmap.lovable.app/.well-known/ai-catalog.json

### Publish a release

```
curl -X POST https://release-ripple-roadmap.lovable.app/api/public/v1/releases \
  -H "Authorization: Bearer $LOGPULSE_API_KEY" -H "Content-Type: application/json" \
  -d '{"title":"Webhooks retry automatically","version":"2.1.0","category":"improved","status":"published","body":"…","breaking_changes":[],"deprecations":[{"item":"retry_once","replacement":"retry_policy","removal_version":"3.0"}]}'
```

## Plans

- Free: up to 10 published releases, full agent feed and MCP, widget with "Powered by LogPulse".
- Open source: free for public repositories with an open-source license; unlimited releases, AI drafts, email blasts; badge stays.
- Pro: €12/month or €99/year + VAT; everything, no badge, custom domain on request, up to 5 team members.