Documentation

Cadiro gives you a hosted public changelog page in minutes. Here's how it works:

• Sign up at cadiro.io and create your first project. Pick a name, slug, and accent color.
• Write entries in the editor. Add a title, pick categories (New, Improved, Fixed), and write your update using the rich text editor. Optionally add a hero image.
• Publish when you're ready, or schedule it for a future date (Pro+). Your public changelog is live instantly at your-slug.cadiro.io.
• Share the link with your users. They can subscribe to email updates, react to entries, and browse your full history.

Your public changelog URL is your-slug.cadiro.io by default. On Pro and Team plans you can map a custom domain instead — see the Custom Domain section below.

On Pro and Team plans you can schedule entries to publish automatically at a future date and time. This is useful for coordinating changelog updates with product launches, marketing campaigns, or planned maintenance windows.

How to schedule an entry: In the entry editor, open the publish dropdown and choose Schedule. Pick a date and time — Cadiro stores the time in UTC. The entry will remain in Scheduled status in your dashboard until that moment arrives, then automatically switch to Published and go live on your public changelog.

Editing scheduled entries: You can edit the content or change the scheduled time at any point before it publishes. You can also publish it immediately by changing the status to Published, or revert it to a draft.

Subscriber notification emails (if enabled) are sent at the moment the entry goes live, not when you schedule it.

Pro and Team plans unlock hero image and GIF uploads on changelog entries. A hero image appears as a full-width banner at the top of your entry card and on the individual entry page — great for showcasing screenshots, animated demos, or feature artwork.

Uploading a hero image: In the entry editor, click the image area at the top of the editor. You can upload a static image (PNG, JPG, WebP) or an animated GIF. Cadiro stores the file in secure cloud storage and serves it via CDN.

Removing a hero image: Click Remove below the current hero image. The image will be cleared when you save.

Free plan: Hero image uploads are not available on the Free plan. If you downgrade from a paid plan, any existing hero images on published entries are preserved — they will not be deleted. You just won't be able to add new ones until you upgrade.

Supported formats: PNG, JPG, WebP, GIF. Recommended dimensions: 1200 × 630px or wider for best results across cards and Open Graph previews.

Pro and Team plans include per-entry view counts. Every time a visitor loads an individual entry page, the view count increments automatically — no tracking scripts required.

Where to find them: View counts appear in your project's Analytics tab in the dashboard. Entries are listed with their total view count, sorted by most viewed.

What counts as a view: Each page load of the individual entry URL is counted. Views on the main changelog feed page (where entry content is previewed inline) are not counted separately — only direct entry page visits.

View counts start accumulating from the moment you publish. Historical views before upgrading to Pro are not back-filled.

In addition to the three built-in categories (New, Improved, Fixed), Pro and Team plans let you create your own custom labels with any name and color. Use them to tag entries with product areas, platforms, audiences, or whatever categorization makes sense for your product.

Creating labels: Go to your project's Settings page and scroll to the Custom Labels section. Click Add label, enter a name (e.g. "Beta", "API", "Mobile"), and pick a color using the color picker. Save.

Using labels on entries: When writing or editing an entry, the category selector shows all your custom labels alongside the built-in ones. You can apply multiple labels to a single entry.

On the public changelog: Custom labels appear as colored badges on entry cards and on individual entry pages. Visitors can also filter entries by custom label using the sidebar filter panel (on desktop) or the pill filters (on mobile).

Editing or deleting labels: You can rename or recolor labels at any time in Settings. Deleting a label removes it from the filter list, but does not retroactively remove it from entries that already use it — those entries will still display the label ID as a plain badge until you manually update them.

Free plan changelogs display a small "Powered by Cadiro" badge in the footer. This is how Cadiro grows — we appreciate it.

On Pro and Team plans, you can remove this badge completely. Go to your project's Settings page and toggle off Show "Powered by Cadiro". The footer badge will be hidden from your public changelog immediately after saving.

You can also choose to keep it on even if you're on a paid plan — the toggle is optional. Some users keep it as a subtle nod to the tooling they use.

On the Pro plan and above you can serve your changelog from your own domain — e.g. updates.yourapp.com — instead of the default Cadiro subdomain.

Step 1 — Add your domain in Settings. Go to your project's Settings page and enter your custom domain under the Custom domain section. Save it.

Step 2 — Create a CNAME record. In your DNS provider, add a CNAME record pointing your subdomain to Cadiro's proxy:

Type:  CNAME
Name:  updates          (or @ for a root domain)
Value: proxy.cadiro.io

DNS changes can take anywhere from a few minutes to 48 hours to propagate depending on your provider. Most propagate within 15 minutes.

Step 3 — Verify. Once DNS has propagated, visit your custom domain in a browser. Cadiro will detect the CNAME and mark your domain as verified. TLS is handled automatically.

Notes:

• Root domains (e.g. yourapp.com) require CNAME flattening or an ALIAS record. Check your DNS provider's documentation.
• Custom domains only work on Pro and Team plans. If you downgrade, your changelog falls back to the default Cadiro URL.
• SSL certificates are provisioned automatically — no manual setup required.

On Pro and Team plans, visitors can subscribe to your changelog and receive an email whenever you publish a new entry. Cadiro handles the entire subscription flow — double opt-in confirmation, unsubscribe links, and delivery.

How subscribers sign up: A subscription form appears on your public changelog page. When a visitor enters their email and clicks Subscribe, they receive a confirmation email. Once they confirm, they're added to your subscriber list.

When notifications are sent: Emails go out automatically when you publish an entry (status changes to Published) or when a scheduled entry goes live. Each email includes the entry title, a preview excerpt, category badges, and a direct link to read the full update.

Managing subscribers: You can view your full subscriber list — broken down by project, with confirmed and pending status — under Subscribers in the dashboard sidebar. The subscriber count is account-wide: your 350 (Pro) or 2,000 (Team) limit is shared across all your projects combined.

Unsubscribing: Every notification email includes a one-click unsubscribe link. Cadiro processes unsubscribes immediately.

Team plan changelogs include a built-in RSS feed. Power users and technical readers can subscribe in any RSS reader and get updates automatically — no email signup required.

Your feed URL is:

https://[your-slug].cadiro.io/rss

The feed includes all published entries with their full title, body content, categories, publication date, and a link back to the individual entry page. It updates automatically whenever you publish a new entry.

If you have a custom domain configured and verified, the feed is also accessible at:

https://your-domain.com/rss

The RSS feed is available on the Team plan only. On Free and Pro plans, the /rss route returns a 404.

The Cadiro widget lets you embed a live changelog feed directly inside your app — no redirect required. When you ship something new, your users see it right there in the UI.

Adding the widget: Go to your project dashboard and click the Widget tab. You'll find your embed snippet there. Add it before the closing </body> tag of your app:

<script
  src="https://cadiro.io/widget.js"
  data-project="your-slug"
  async
></script>

Then add a trigger element where you want the widget to open. The widget attaches to any element with data-cadiro-trigger:

<button data-cadiro-trigger>
  What's new
</button>

Clicking the trigger opens a slide-in panel showing your latest published entries, styled to match your project's accent color.

Unread badge: The widget automatically shows an unread count badge on your trigger element for entries the user hasn't seen yet. The count clears when the panel is opened.

Options: You can customize the widget's position and behavior via data attributes on the script tag:

<script
  src="https://cadiro.io/widget.js"
  data-project="your-slug"
  data-position="bottom-right"   <!-- bottom-right (default) | bottom-left -->
  data-entries="5"               <!-- number of entries to show (default: 5) -->
  async
></script>

The widget is available on the Team plan only. It requires the Widget tab to be enabled in your project settings.

The GitHub integration automatically creates a changelog entry every time a pull request is merged — no copy-pasting from your git history required.

What is a pull request?

A pull request (PR) is how developers propose and merge code changes. When a developer finishes a feature or bug fix, they open a PR to merge their branch into the main branch. When that PR is approved and merged, Cadiro detects it and creates a draft entry ready for you to review.

Step 1 — Connect your GitHub account. Go to your project's Settings page and scroll to the GitHub Integration section. Click Connect GitHub and authorize Cadiro. You'll be redirected back to Settings once connected.

Step 2 — Select a repository. After connecting, choose which GitHub repository to watch from the dropdown. Cadiro will register a webhook on that repo — you don't need to configure anything in GitHub yourself.

Step 3 — Merge a PR. Cadiro watches for merged pull requests that match one of two trigger conditions. You only need to use one — pick whichever fits your workflow.

Option A: Add a label to the PR

Labels are tags you attach to a pull request in GitHub. To use this trigger:

• First, create a label named changelog in your repo. Go to your repo on GitHub → Issues → Labels → New label. Name it changelog and save.
• When you open a pull request, find the Labels section in the right-hand sidebar and apply the changelog label. You can also add it to an existing PR before merging.
• When the PR is merged, Cadiro creates a draft entry using the PR title and description. The PR title doesn't need any special format.

Option B: Use a conventional commit prefix in the PR title

A conventional commit prefix is a short tag at the very start of your pull request title, followed by a colon and a space. No label required — Cadiro detects the prefix automatically.

When you create (or edit) a pull request in GitHub, set the title like one of these:

feat: Add dark mode
fix: Login button not responding on mobile
perf: Reduce image load time on the dashboard
refactor: Rewrite the onboarding flow

Cadiro strips the prefix and uses the rest as the entry title. So feat: Add dark mode becomes an entry titled Add dark mode in the New category.

You can also add a scope in parentheses — e.g. feat(auth): Add Google login — and Cadiro will still detect it correctly.

Prefix to category mapping:

• feat: — New. Use for new features.
• fix: — Fixed. Use for bug fixes.
• perf: or refactor: — Improved. Use for performance or quality improvements users will notice.

What gets created?

Cadiro creates a draft entry with the PR title as the headline and the PR description as the body. You can edit both before publishing — the PR description is just a starting point. Nothing goes live until you review and publish from your dashboard.

Auto-publish (optional). If you want entries to go live immediately on merge without a review step, you can enable Auto-publish in the GitHub Integration settings. A warning will remind you that entries will be public instantly — you can still edit them after the fact.

PRs that are ignored. A PR is skipped if it is closed without merging, or if it has neither a changelog label nor a recognized conventional commit prefix in the title.

The GitHub integration is available on the Team plan only. See pricing.

The Cadiro REST API lets you create and publish changelog entries programmatically — useful for automating releases from your CI/CD pipeline, GitHub Actions, or deployment scripts.

Authentication: All API requests require a Bearer token. You can generate an API key from your account settings page.

Authorization: Bearer YOUR_API_KEY

Base URL:

https://cadiro.io/api/v1

Create an entry

POST /projects/:slug/entries

{
  "title": "Dark mode support",
  "body_markdown": "We've added dark mode...",
  "categories": ["new", "improved"],
  "status": "published",           // "draft" | "published" | "scheduled"
  "published_at": "2026-03-14T09:00:00Z",   // optional
  "scheduled_for": "2026-03-20T09:00:00Z"   // required if status = "scheduled"
}

Response

{
  "id": "uuid",
  "slug": "dark-mode-support",
  "title": "Dark mode support",
  "status": "published",
  "published_at": "2026-03-14T09:00:00Z",
  "url": "https://your-project.cadiro.io/dark-mode-support"
}

List entries

GET /projects/:slug/entries?status=published&limit=20&offset=0

Get a single entry

GET /projects/:slug/entries/:entry-slug

Update an entry

PATCH /projects/:slug/entries/:entry-slug

{
  "title": "Updated title",
  "status": "published"
}

Delete an entry

DELETE /projects/:slug/entries/:entry-slug

The API is available on the Team plan only. Rate limiting is set at 120 requests per minute per API key. If you exceed this limit you'll receive a 429 Too Many Requests response.

Have questions or need a feature the API doesn't support yet? Contact us.