💊Docs

Quick Start

Add Version Pill to your app in under 5 minutes.

1

Create a Project

Sign in and create a new project. You'll get a unique slug like my-app.

2

Add Your First Release

Go to Changelog tab and click "New Release". Enter version number, title, and features.

3

Embed in Your App

Copy the embed code and paste it in your app:

<script
  src="https://versionpill.com/embed.js"
  data-project="your-slug"
  data-type="badge"
></script>

React / Next.js

Type-safe React components with full customization options.

Installation

npm install @version-pill/react

Version Pill Badge

import { VersionPill } from "@version-pill/react";

export function Header() {
  return (
    <header className="flex items-center justify-between p-4">
      <Logo />
      <VersionPill
        projectId="your-slug"
        theme="auto"        // "light" | "dark" | "auto"
        position="inline"   // "inline" | "top-right" | "bottom-right"
      />
    </header>
  );
}

Changelog Embed

import { Changelog } from "@version-pill/react";

export function ChangelogPage() {
  return (
    <div className="max-w-3xl mx-auto py-8">
      <h1>What's New</h1>
      <Changelog
        projectId="your-slug"
        maxHeight={600}
        theme="auto"
      />
    </div>
  );
}

Roadmap Embed

import { Roadmap } from "@version-pill/react";

export function RoadmapPage() {
  return (
    <div className="max-w-4xl mx-auto py-8">
      <h1>Roadmap</h1>
      <Roadmap
        projectId="your-slug"
        maxHeight={800}
        theme="auto"
      />
    </div>
  );
}

Props Reference

projectId

Your project slug (required)

theme

"light" | "dark" | "auto" (default: auto)

position

"inline" | "top-right" | "bottom-right" (VersionPill only)

maxHeight

Height in pixels (Changelog/Roadmap only)

showBranding

Show powered by badge (default: true)

onNewVersion

Callback when new version detected

Version Badge

A small pill that goes in your header or footer. Shows current version and links to full changelog.

Basic Usage

<script
  src="https://versionpill.com/embed.js"
  data-project="your-slug"
  data-type="badge"
></script>

Customization Options

data-style

dot, pill, outline, solid, gradient, minimal

Default: dot

data-accent

default, blue, green, purple, orange, red

Default: default

data-icon

true, false

Default: true

data-arrow

true, false

Default: true

data-prefix

any string

Default: v

Example with Customization

<script
  src="https://versionpill.com/embed.js"
  data-project="your-slug"
  data-type="badge"
  data-style="pill"
  data-accent="blue"
></script>

Changelog Widget

Embed your full release history. Updates in real-time when you publish.

<script
  src="https://versionpill.com/embed.js"
  data-project="your-slug"
  data-type="changelog"
  data-height="500"
></script>

Options

data-height

Widget height in pixels (default: 500)

data-theme

light, dark, or auto (default: auto)

data-border

Show border: true or false

Roadmap Widget

Let users see what you're building and submit feature requests.

<script
  src="https://versionpill.com/embed.js"
  data-project="your-slug"
  data-type="roadmap"
  data-height="600"
></script>

Users can submit ideas and vote on features directly from the widget.

GitHub Integration

Automatically publish releases when you create a GitHub release.

GitHub Action

# .github/workflows/version-pill.yml
name: Publish to Version Pill

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Publish Release
        run: |
          curl -X POST "https://api.versionpill.com/api/release/${{ secrets.VERSION_PILL_SLUG }}" \
            -H "Authorization: Bearer ${{ secrets.VERSION_PILL_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "version": "${{ github.event.release.tag_name }}",
              "type": "minor",
              "title": "${{ github.event.release.name }}"
            }'

Setup

  1. Go to Version Pill project → Settings → Copy API Key
  2. In GitHub repo → Settings → Secrets → Actions
  3. Add VERSION_PILL_KEY
  4. Add VERSION_PILL_SLUG

AI Release Notes

Let AI generate release notes from your commit messages.

curl -X POST "https://api.versionpill.com/api/release/your-slug" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.2.0",
    "type": "minor",
    "useAI": true,
    "commits": "feat: add dark mode\nfix: resolve login bug\nchore: update deps"
  }'

When useAI: true is set, Version Pill uses Claude to generate a title, description, feature list, and emoji from your commits.

API Reference

For a complete interactive API reference with examples in every language:

View Full API Docs →

Create Release

POST /api/release/{projectSlug}
{
  "version": "1.2.0",        // required
  "type": "minor",           // required: major, minor, patch
  "title": "New Features",   // required (unless useAI)
  "description": "...",      // optional
  "features": ["..."],       // optional
  "emoji": "✨",              // optional
  "useAI": false,            // optional
  "commits": "..."           // optional (for AI)
}

Get Changelog

GET /api/changelog/{projectSlug}?limit=10

Returns public changelog entries. No authentication required.

Get Roadmap

GET /api/roadmap/{projectSlug}

Returns public roadmap items. No authentication required.

Submit Feature Request

POST /api/ideas/{projectSlug}
{
  "title": "Feature title",
  "description": "Feature description",
  "authorName": "John",      // optional
  "authorEmail": "..."       // optional
}