changelog-site

name	changelog-site
display_name	Changelog Site API
description	Manage changelog entries, subscribers, and site settings for a self-hosted changelog publishing tool.
base_url	http://localhost:3000
auth	none
version	1.0

Changelog Site Skill

When to use

Use this skill to:

• Create, update, and publish changelog entries
• Manage the draft/published workflow
• List and remove email subscribers
• Configure site settings and SMTP credentials
• Retrieve entries for display or export

Base URL

http://localhost:3000

No authentication is required. This API is intended for single-user local/self-hosted deployment.

Quick Reference

Action	Method	Path
List all entries	GET	/api/entries
Get single entry	GET	/api/entries/:slug
Create entry	POST	/api/entries
Update entry	PUT	/api/entries/:slug
Delete entry	DELETE	/api/entries/:slug
Publish entry	POST	/api/entries/:slug/publish
List subscribers	GET	/api/subscribers
Remove subscriber	DELETE	/api/subscribers/:id
Get settings	GET	/api/settings
Update settings	PUT	/api/settings

API Reference

GET /api/entries

List entries. Defaults to published only.

Parameters:

Name	Type	Default	Description
status	string	published	"published", "draft", or "all"
category	string	-	Filter by category slug
limit	integer	20	Max entries per page
offset	integer	0	Pagination offset

Example:

curl http://localhost:3000/api/entries?status=all&limit=10

Response:

{
  "entries": [
    {
      "id": 1,
      "slug": "dark-mode-support",
      "title": "Dark mode support across all pages",
      "category": "added",
      "version": "v3.4.0",
      "is_draft": false,
      "published_at": "2026-03-20T10:00:00.000Z",
      "created_at": "2026-03-19T14:22:00.000Z"
    }
  ],
  "total": 18,
  "offset": 0,
  "limit": 20
}

GET /api/entries/:slug

Get a single entry with full body content.

curl http://localhost:3000/api/entries/dark-mode-support

Response:

{
  "id": 1,
  "slug": "dark-mode-support",
  "title": "Dark mode support across all pages",
  "category": "added",
  "version": "v3.4.0",
  "body_md": "We've added a full dark mode...\n\n## What's new\n\n- ...",
  "body_html": "<p>We've added a full dark mode...</p>",
  "is_draft": false,
  "published_at": "2026-03-20T10:00:00.000Z",
  "created_at": "2026-03-19T14:22:00.000Z",
  "updated_at": "2026-03-20T09:55:00.000Z"
}

POST /api/entries

Create a new entry. Saved as draft by default.

curl -X POST http://localhost:3000/api/entries \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Bulk export for all data types",
    "category": "added",
    "version": "v3.5.0",
    "body_md": "You can now export data in bulk...\n\n## Formats\n\n- CSV\n- JSON"
  }'

Response: 201 Created with the created entry object including generated slug.

PUT /api/entries/:slug

Update an existing entry (draft or published).

curl -X PUT http://localhost:3000/api/entries/bulk-export-for-all-data-types \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Bulk export for all data types",
    "category": "added",
    "version": "v3.5.0",
    "body_md": "Updated body content..."
  }'

POST /api/entries/:slug/publish

Publish a draft entry. Sends email notifications to all confirmed subscribers and updates the RSS feed.

curl -X POST http://localhost:3000/api/entries/bulk-export-for-all-data-types/publish

Response:

{
  "slug": "bulk-export-for-all-data-types",
  "published_at": "2026-03-20T11:30:00.000Z",
  "notifications_sent": 247
}

DELETE /api/entries/:slug

Delete an entry permanently.

curl -X DELETE http://localhost:3000/api/entries/dark-mode-support

Response: 204 No Content

GET /api/subscribers

List all subscribers.

Parameters:

Name	Type	Default	Description
status	string	all	"confirmed", "pending", or "all"
limit	integer	50	Max per page
offset	integer	0	Pagination offset

curl http://localhost:3000/api/subscribers?status=confirmed

Response:

{
  "subscribers": [
    {
      "id": 1,
      "email": "[e-mail]",
      "status": "confirmed",
      "subscribed_at": "2026-03-18T08:00:00.000Z",
      "last_notified_at": "2026-03-20T11:30:00.000Z"
    }
  ],
  "total": 247
}

DELETE /api/subscribers/:id

Remove a subscriber immediately.

curl -X DELETE http://localhost:3000/api/subscribers/42

GET /api/settings

Retrieve current site settings.

curl http://localhost:3000/api/settings

Response:

{
  "product_name": "Acme App",
  "description": "Product updates, bug fixes, and new features.",
  "public_url": "https://changelog.acmeapp.com",
  "entries_per_page": 20,
  "rss_enabled": true,
  "email_notifications": true,
  "smtp_host": "smtp.postmarkapp.com",
  "smtp_port": 587,
  "smtp_user": "api-key-abc123",
  "from_address": "[e-mail]"
}

Note: smtp_password is never returned by the API.

PUT /api/settings

Update site settings.

curl -X PUT http://localhost:3000/api/settings \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Acme App",
    "smtp_host": "smtp.postmarkapp.com",
    "smtp_port": 587,
    "smtp_user": "api-key-abc123",
    "smtp_password": "new-secret",
    "from_address": "[e-mail]",
    "email_notifications": true
  }'

POST /api/settings/test-email

Send a test email to verify SMTP configuration. Uses currently saved SMTP settings.

curl -X POST http://localhost:3000/api/settings/test-email \
  -H "Content-Type: application/json" \
  -d '{"to": "[e-mail]"}'

Entry Object

interface Entry {
  id: number;
  slug: string;            // URL-safe, auto-generated from title
  title: string;
  category: Category;
  version: string | null;  // e.g. "v3.4.0"
  body_md: string;         // Raw markdown source
  body_html: string;       // Sanitized HTML rendered from body_md
  is_draft: boolean;
  published_at: string | null;  // ISO 8601
  created_at: string;
  updated_at: string;
}

type Category = "added" | "fixed" | "changed" | "deprecated" | "security" | "removed";

Category values

Value	Badge color	Use for
added	Green	New features and capabilities
fixed	Blue	Bug fixes and error corrections
changed	Amber	Behavior or configuration changes
deprecated	Orange	Features marked for future removal
security	Red	Vulnerability patches, CVEs
removed	Gray	Features fully removed

Error responses

All errors return JSON with a consistent shape:

{
  "error": "Entry not found",
  "code": "NOT_FOUND"
}

HTTP status	code	Meaning
400	VALIDATION_ERROR	Invalid input fields
404	NOT_FOUND	Entry or subscriber does not exist
409	CONFLICT	Slug already in use
500	INTERNAL_ERROR	Unexpected server error

Environment variables

Variable	Default	Description
PORT	3000	HTTP server port
DATA_DIR	./data	Directory for SQLite file
PUBLIC_URL	-	Full URL of the public changelog page