CommitFlowAPI Reference

API Reference

Programmatic access to CommitFlow. All endpoints return JSON. Base URL: https://commitflow.org

Authentication

Session Auth — Authenticate via GitHub OAuth login. Session cookie is set automatically by the browser.
API Key — Generate from Dashboard Settings. Pass in header: x-api-key: cflow_... or Authorization: Bearer cflow_...
Webhook Signature — GitHub webhooks use HMAC-SHA256 signature verification.

Endpoints

GET/api/workspaces/currentSession

Get the current authenticated user's workspace.

Response: { workspace: { id, name, slug, logo_url, primary_color, custom_domain } }

PATCH/api/workspaces/updateSession

Update workspace name, primary color, or custom domain.

Body: { name?: string, primary_color?: string, custom_domain?: string }

POST/api/workspaces/logoSession

Upload a workspace logo image.

GET/api/entriesSession

List changelog entries for a workspace with pagination.

Query: workspace_id (required), page, page_size

POST/api/entriesSession

Create a new changelog entry.

Body: { workspace_id, title, content, summary?, category: "new"|"improved"|"fixed"|"deprecated", version? }

GET/api/entries/[id]Session

Get a single entry with linked commits.

PATCH/api/entries/[id]Session

Update an existing entry (title, content, category, etc).

DELETE/api/entries/[id]Session

Delete an entry permanently.

POST/api/entries/publishInternal

Publish a draft entry and trigger distribution to channels.

Body: { entry_id }

GET/api/entries/recentSession

Get most recent entries across workspace.

POST/api/entries/[id]/viewNone

Increment view count for a public entry.

GET/api/feedbackSession

List feedback posts for a workspace.

Query: workspace_id (required)

POST/api/feedbackSession

Create a new feedback post.

Body: { workspace_id, title, description? }

POST/api/feedback/[id]None

Vote on a feedback post.

Body: { voter_email }

GET/api/subscribersSession

List active subscribers for a workspace.

Query: workspace_id (required)

POST/api/subscribersSession

Add a subscriber to a workspace.

Body: { workspace_id, email }

DELETE/api/subscribersSession

Remove a subscriber.

Body: { workspace_id, email }

GET/api/channelsSession

List distribution channels (Slack, Discord, email).

Query: workspace_id (required)

POST/api/channelsSession

Add a distribution channel.

Body: { workspace_id, type: "slack"|"discord"|"email", config: {...} }

GET/api/reposSession

List connected GitHub repositories.

Query: workspace_id (required)

POST/api/reposSession

Connect a GitHub repository for auto-generation.

Body: { workspace_id, full_name }

GET/POST/api/users/api-keySession

Get API key status or generate a new key. Keys are SHA-256 hashed.

POST/api/webhook/githubSignature

GitHub push webhook. Auto-generates changelog entries from commits.

Verifies x-hub-signature-256. Requires webhook secret configured on repo.

GET/api/mcpAPI Key

MCP JSON-RPC endpoint. Supports tools: list_entries, create_entry, update_entry, publish_entry, list_feedback, update_feedback_status, get_stats, list_subscribers.

GET/api/mcp/sseAPI Key

MCP Server-Sent Events stream for persistent agent connections.

GET/api/widget.jsNone

Embeddable changelog widget JavaScript. Supports data-workspace, data-color, data-position params.

Rate Limiting

Free plan: 100 requests/hour. Pro/Team: 1000 requests/hour. Rate limit headers are included in responses: X-RateLimit-*