Developer Docs — ShipLog

Introduction

ShipLog Developer Docs

ShipLog transforms Git commits into structured changelogs and product announcements using AI. These docs cover the REST API, authentication, webhooks, third-party integrations, and RSS — all available on Pro and Team plans.

System overview

GitHub

commits · diffs

ShipLog AI

Changelog

Announcement

Fast

Generate a changelog from 100 commits in under 10 seconds.

Extensible

REST API, webhooks, Linear, Jira, Discord, Slack, RSS — plug into your existing toolchain.

Secure

Per-user API keys, Bearer token auth, and row-level security at the database layer.

The REST API (/api/v1/*), API keys, and the MCP server require the Team plan. Webhooks, RSS, and export formats require Pro or higher.

Authentication

API Keys

ShipLog uses static Bearer tokens for REST API authentication. Each key is scoped to a single user account and is only available on the Team plan.

Authentication sequence

Client sends request with Bearer token in header

API hashes the key and queries Supabase

DB returns user identity and active plan

API responds with data scoped to your account

1. Generate a key

Go to Settings → Integrations → API key and click Generate key. Your key is prefixed with sl_live_ followed by 48 random hex characters. It is shown once — copy it immediately.

2. Authenticate requests

Include the key as a Bearer token in the Authorization header on every request.

bash

1	curl https://shiplog-app.com/api/v1/changelogs \
2	-H "Authorization: Bearer sl_live_your_key_here"

Keep your key secret. Anyone who holds it can read all your changelogs. Regenerate it immediately from Settings → Integrations if it is ever exposed.

REST API

Endpoints

Base URL: https://shiplog-app.com/api/v1/ — all responses are JSON. Every endpoint requires a valid Team-plan API key.

GET/api/v1/changelogsTeam plan

GET/api/v1/changelogsList changelogs, newest first, paginated.

Query parameters

limit

numberMax entries to return. Default 20, max 100.

offset

numberNumber of entries to skip. Default 0.

repo

stringFilter by repository in "owner/name" format — e.g. ?repo=acme/api

Example request

bash

1	curl "https://shiplog-app.com/api/v1/changelogs?limit=5&repo=acme/api" \
2	-H "Authorization: Bearer sl_live_your_key_here"

Example response

json

1	{
2	"data": [
3	{
4	"id": "cl_abc123",
5	"slug": "acme-api-v2-1-0-april-2026",
6	"title": "acme/api v2.1.0 — April 2026",
7	"repo_owner": "acme",
8	"repo_name": "api",
9	"changelog_type": "changelog",
10	"is_public": true,
11	"commit_count": 14,
12	"content_md": "## v2.1.0 — April 2026\n...",
13	"range_from": "v2.0.0",
14	"range_to": "v2.1.0",
15	"created_at": "2026-04-02T10:30:00.000Z"
16	}
17	],
18	"meta": { "limit": 5, "offset": 0, "count": 5 }
19	}

Response schema

id

stringUnique changelog ID.

slug

stringURL-safe slug used in the public changelog URL.

title

stringAuto-generated or user-edited title.

content_md

stringFull changelog body in Markdown.

changelog_type

string"changelog" or "announcement".

is_public

booleanWhether the changelog is publicly accessible.

commit_count

numberNumber of commits included in this generation.

created_at

stringISO 8601 creation timestamp (UTC).

Error responses

401Missing or invalid API key.

403Plan does not include API access — Team plan required.

500Internal server error.

POST/api/v1/generateFetch commits, generate with AI, save, return result.

Request body (JSON)

reporeq

stringRepository in "owner/name" format — e.g. "acme/api"

github_tokenreq

stringGitHub Personal Access Token with repo read access (ghp_…)

branch

stringBranch to generate from. Default "main".

limit

numberNumber of recent commits to include. Default 20, max 50.

type

string"changelog" (default) or "announcement".

Example request

bash

1	curl -X POST "https://shiplog-app.com/api/v1/generate" \
2	-H "Authorization: Bearer sl_live_your_key_here" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"repo": "acme/api",
6	"github_token": "ghp_your_token_here",
7	"branch": "main",
8	"limit": 20,
9	"type": "changelog"
10	}'

Example response

json

1	{
2	"id": "cl_abc123",
3	"slug": "acme-api-1714123456789",
4	"title": "acme/api — April 3, 2026",
5	"content_md": "## acme/api — April 3, 2026\n\n### ✨ New Features\n...",
6	"url": "https://shiplog-app.com/changelog/acme-api-1714123456789"
7	}

Error responses

401Missing or invalid API key.

403Team plan required, or generation limit reached.

422Repo not found / not accessible with the provided GitHub token.

502AI generation failed — OpenRouter error.

503Could not reach GitHub or OpenRouter.

Use POST /api/v1/generate to automate changelog creation in CI/CD pipelines or from your AI assistant via the MCP server.

MCP Server

Use ShipLog from your AI assistant

The ShipLog MCP (Model Context Protocol) server lets you generate and list changelogs directly from Cursor, Claude Desktop, or any MCP-compatible AI tool — without opening a browser. Requires the Team plan.

Works in Cursor

Ask Cursor to generate a changelog for any repo. ShipLog fetches commits, runs AI, saves, and returns the result inline.

The MCP server calls POST /api/v1/generate and GET /api/v1/changelogs under the hood using your Team plan API key.

Your key, your data

The server runs locally on your machine. Your API key and GitHub token never leave your environment.

Prerequisites

ShipLog Team plan

API keys and the generate endpoint are Team-only. Upgrade in Settings → Billing.

ShipLog API key

Generate one in Settings → Integrations → API key. Starts with sl_live_.

GitHub PAT (repo scope)

Personal Access Token with full repo read access — needed to fetch commits and file diffs. Create at github.com/settings/tokens.

Node.js 18+

Required to run the server via npx. Check with: node --version

Setup — step by step

Get your ShipLog API key

Go to Settings → Integrations → API key in your ShipLog dashboard and click Generate key. Copy the key — it starts with sl_live_ and is shown only once.

Configure in Cursor

Create or edit .cursor/mcp.json in your workspace root (or ~/.cursor/mcp.json for global access). No installation needed — npx downloads the package automatically.

json

1	{
2	"mcpServers": {
3	"shiplog": {
4	"command": "npx",
5	"args": ["-y", "shiplog-mcp"],
6	"env": {
7	"SHIPLOG_API_KEY": "sl_live_your_key_here"
8	}
9	}
10	}
11	}

Configure in Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows).

json

1	{
2	"mcpServers": {
3	"shiplog": {
4	"command": "npx",
5	"args": ["-y", "shiplog-mcp"],
6	"env": {
7	"SHIPLOG_API_KEY": "sl_live_your_key_here"
8	}
9	}
10	}
11	}

Ask your AI assistant

Reload Cursor or Claude Desktop. The ShipLog tools are now available. Try asking:

text

1	Generate a changelog for acme/backend using my GitHub token ghp_xxx

Changelog generated and saved

ShipLog fetches your commits, runs AI generation, saves the changelog to your account, and returns the full Markdown with a public URL.

Environment variables

SHIPLOG_API_KEYreq

stringYour ShipLog API key (sl_live_…). Generate it in Settings → Integrations.

SHIPLOG_API_URL

stringBase URL of the ShipLog API. Default: "https://shiplog-app.com". Set to "http://localhost:3000" for local development.

Available tools

list_changelogsList saved changelogs, filtered by repo or paginated.

Parameters

repo

stringFilter by repository — e.g. "acme/backend"

limit

numberResults per page. Max 100, default 20.

offset

numberPagination offset. Default 0.

Example prompts

List my last 5 changelogs

Show my changelogs for acme/backend

What changelogs did I generate this week?

generate_changelogFetch commits, generate with AI, save, and return Markdown + URL.

Parameters

reporeq

stringRepository in "owner/name" format — e.g. "acme/backend"

github_tokenreq

stringGitHub PAT with repo read access (ghp_…). Used to fetch commits and file diffs.

branch

stringBranch to generate from. Default "main".

limit

numberNumber of recent commits to include. Default 20, max 50.

type

string"changelog" (default) — structured release notes. "announcement" — product-first, marketing-friendly.

Example prompts

Generate a changelog for acme/backend using my GitHub token ghp_xxx

Create an announcement for the last 10 commits on acme/api main branch

Generate a changelog and announcement for NickKengne/ShipLog

Your GitHub token only needs repo scope (not just public_repo) to access private repositories. Create a fine-grained PAT at github.com/settings/tokens.

Never commit your SHIPLOG_API_KEY or GitHub token to a repository. Use environment variables or a secrets manager instead.

Webhooks

Discord & Slack

Publish any changelog or announcement to a Discord or Slack channel with a single click. ShipLog uses Incoming Webhooks — no OAuth app required on your end.

Discord — step by step

Create an Incoming Webhook

In your Discord server, open Channel Settings → Integrations → Webhooks, then click New Webhook. Choose the target channel and copy the URL.

text

1	https://discord.com/api/webhooks/{channel_id}/{token}

Save in ShipLog

Go to Settings → Integrations → Discord. Paste the webhook URL, give it a label, and click Save.

Generate a changelog

Use the Generate page to create a changelog or announcement from your repository commits.

Click "Publish to Discord"

ShipLog splits the content into ≤2,000-character chunks (Discord's limit) and POSTs each one to your webhook URL.

bash

1	POST https://discord.com/api/webhooks/…
2	Content-Type: application/json
3
4	{ "content": "v1.4.0 changelog\n\n## What\'s New…" }

Message delivered

Your Discord channel receives the formatted changelog message.

Slack — step by step

Create an Incoming Webhook

Go to api.slack.com/apps, create or select an app, enable Incoming Webhooks, click Add to Slack, pick your channel, and copy the webhook URL.

text

1	https://hooks.slack.com/services/T00000000/B00000000/XXXX

Save in ShipLog

Go to Settings → Integrations → Slack. Paste the URL, add a label for the channel, and save.

Generate a changelog

Use the Generate page to build a changelog or announcement from your commits.

Click "Publish to Slack"

ShipLog splits the content into ≤3,000-character chunks (Slack's limit) and POSTs each block to your webhook.

bash

1	POST https://hooks.slack.com/services/…
2	Content-Type: application/json
3
4	{ "text": "v1.4.0 changelog\n\nWhat\'s New…" }

Message delivered

Your Slack channel receives the formatted changelog message.

Integrations

Linear & Jira

ShipLog scans commit messages for issue identifiers like ENG-123 or PROJ-456, fetches their titles and statuses from Linear or Jira, and injects that context into the AI prompt — producing more accurate, issue-linked changelogs.

Commit enrichment pipeline

Commits

ENG-123 · PROJ-456

Issue IDs

[A-Z]+-\d+

Linear API

Jira API

AI prompt

enriched context

Linear — OAuth 2.0

Team

Authorize from Settings → Integrations → Linear. ShipLog requests read,write,issues:create scope. Once connected, issue IDs detected in commits are resolved to their title and status before the AI runs.

text

1	# Identifiers auto-detected in commit messages:
2	ENG-123 FE-45 BACKEND-789

After publishing, ShipLog calls:

POST/api/integrations/linear/comment— posts a comment on each resolved issue

POST/api/integrations/linear/resolve— marks issues as Done

OAuth 2.0 connect — no token storage

Detects ENG-123 patterns in commits

Posts comment on issue after publish

Marks issue as Done automatically

Jira — API Token

Team

Connect from Settings → Integrations → Jira. Provide your Atlassian site URL, email, and an API token. Credentials are verified against Jira's /myself endpoint before saving.

text

1	# Atlassian site URL format:
2	mycompany.atlassian.net
3
4	# Issue IDs auto-detected:
5	PROJ-123 BACKEND-456 OPS-789

Issues fetched via GET /rest/api/3/search using HTTP Basic auth (email + API token).

API token auth — no OAuth needed

Detects PROJ-123 patterns in commits

Fetches issue summaries and status

Shows linked issue context in changelog

RSS Feed

Subscribe to changelogs

Pro and Team users get a public RSS 2.0 feed of all their public changelogs. Share it with users or subscribe internally to track releases across projects.

xml

1	<?xml version="1.0" encoding="UTF-8"?>
2	<rss version="2.0">
3	<channel>
4	<title>My changelogs · ShipLog</title>
5	<link>https://shiplog-app.com</link>
6	<item>
7	<title>v1.4.0 — April 2026</title>
8	<link>https://shiplog-app.com/changelog/…</link>
9	<pubDate>Thu, 02 Apr 2026 10:00:00 GMT</pubDate>
10	<description>New features and bug fixes…</description>
11	</item>
12	</channel>
13	</rss>

Pro + Team only

Available at /api/rss/[userId]

50 latest entries

Newest public changelogs first. No auth required to read.

RSS 2.0 standard

Works in Feedly, Reeder, NetNewsWire, Inoreader, and any reader.

Auto-discoverable

Link tag injected in the public changelog <head> for reader detection.

Feed URL

GEThttps://shiplog-app.com/api/rss/{userId}

Your userId is shown in Settings → Account. It is also linked directly on every public changelog page.

Fetch the feed

bash

1	curl https://shiplog-app.com/api/rss/usr_your_user_id_here

Compatible readers

Feedly

Reeder

NetNewsWire

Inoreader

Rate limits & plans

Plan limits

Usage limits are enforced server-side and reset on the 1st of each calendar month at 00:00 UTC.

FreeProTeam

Repositories

Unlimited

Generations / mo

200

Announcements / mo

100

Commits / generation

File diffs

—

full patch

Private changelogs

—

REST API access

—

RSS feed

—

Discord + Slack

—

Linear + Jira

—

Team members (RBAC)

—

Up to 7

API key

—

Generation count reset

generation_count resets on the 1st of each month at 00:00 UTC. Unused generations do not carry over.

ShipLog REST API

No per-minute limit is enforced on /api/v1/* today. Fair use is expected — automated bulk scraping triggers account review.

GitHub API rate limits

ShipLog calls GitHub using each user's OAuth token — every user has their own independent quota.

5,000

req / hour

Authenticated (OAuth)

5,000 req/h

Per user token. Used for all ShipLog GitHub calls.

Unauthenticated

60 req/h

Per IP. Not used by ShipLog.

Search API

30 req/min

Separate sub-limit. Not used by ShipLog.

GitHub API calls per ShipLog generation

List repos1

Fetch commit list (100/page)1 – 5

Fetch file diffs (Pro/Team)1 per commit, max 50

Total per generation3 – 56

Check your live GitHub quota at GET https://api.github.com/rate_limit with your OAuth token. ShipLog shows a warning in the Generate UI when your remaining quota drops below 200.