# Changelogs

Release notes and updates published by the organization. Changelogs keep users informed about new features, improvements, and fixes.

## List all changelogs

 - [GET /v2/changelogs](https://docs.featurebase.app/rest-api/changelogs/listchangelogs.md): Returns all changelogs for the authenticated organization.

Changelogs are release notes and updates that keep users informed about new features, improvements, and bug fixes. Each changelog can have:
- Multiple translations (locales)
- Categories for organization
- Featured images
- Scheduled publishing

### Pagination

This endpoint uses cursor-based pagination:

- limit - Number of changelogs to return (1-100, default 10)
- cursor - Opaque cursor from a previous response's nextCursor field

Example: To paginate through results:
1. First request: GET /v2/changelogs?limit=10
2. If nextCursor is not null, use it for the next page
3. Next request: GET /v2/changelogs?limit=10&cursor={nextCursor}

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of changelog objects
- nextCursor - Cursor for the next page (null if no more results)

### Filtering

Filter changelogs using query parameters:
- id - Find a specific changelog by ID or slug
- q - Search query for title/content
- categories - Filter by category names
- locale - Get changelogs in a specific locale (defaults to org default)
- state - Filter by state: live, draft, or all
- startDate - Include changelogs dated on or after this date
- endDate - Include changelogs dated on or before this date

### Sorting

Results are sorted by date (descending by default):
- sortBy - Field to sort by (currently only date)
- sortOrder - Sort direction: asc or desc (default: desc)

## Create a new changelog

 - [POST /v2/changelogs](https://docs.featurebase.app/rest-api/changelogs/createchangelog.md): Creates a new changelog for the authenticated organization.

### Required Fields

- title - The title of the changelog

### Content

Provide content in one of two formats (at least one is required):
- htmlContent - HTML content of the changelog
- markdownContent - Markdown content of the changelog

Note: For images in content, you can use:
- External URLs in img src attributes (automatically uploaded to our storage)
- Base64 encoded data URIs (data:image/...) which are processed and stored

### Optional Fields

- categories - Array of category names (e.g., ["New", "Fixed", "Improved"])
- featuredImage - URL of the featured image (external URLs are uploaded to our storage)
- allowedSegmentIds - Array of segment IDs that are allowed to view the changelog
- locale - The locale of the changelog (defaults to organization default)
- date - The date of the changelog
- state - The state of the changelog: draft (default) or live

### Response

Returns the created changelog object.

## Get a changelog by ID

 - [GET /v2/changelogs/{id}](https://docs.featurebase.app/rest-api/changelogs/getchangelog.md): Retrieves a single changelog by its unique identifier or slug.

Returns the full changelog object including:
- Title and content (in HTML and markdown formats)
- Featured image
- Publication date
- Categories
- Comment count
- Email notification status

### Localization

The changelog content is returned in the organization's default locale.
If the changelog doesn't exist in the default locale, the first available locale is used.

### State

Both published (live) and draft changelogs can be retrieved.
The state field indicates the current publication status.

## Update a changelog

 - [PATCH /v2/changelogs/{id}](https://docs.featurebase.app/rest-api/changelogs/updatechangelog.md): Updates an existing changelog by its unique identifier.

You can update:
- title - The changelog title
- htmlContent - HTML content (one of htmlContent or markdownContent)
- markdownContent - Markdown content (one of htmlContent or markdownContent)
- categories - Array of category names
- featuredImage - Featured image URL
- allowedSegmentIds - Segment IDs for access control
- date - The date of the changelog

### Content Format

Provide content in one of two formats:
- htmlContent - HTML content of the changelog
- markdownContent - Markdown content of the changelog

Note: For images in content, you can use:
- External URLs in img src attributes (automatically uploaded to our storage)
- Base64 encoded data URIs (data:image/...) which are processed and stored

### Categories

Provide category names as an array. The categories must already exist in your organization.

Example: ["New", "Fixed", "Improved"]

### Response

Returns the updated changelog object with all fields populated.

### Errors

- 400 - Invalid changelog ID format or invalid input
- 404 - Changelog not found or doesn't belong to your organization

## Delete a changelog

 - [DELETE /v2/changelogs/{id}](https://docs.featurebase.app/rest-api/changelogs/deletechangelog.md): Deletes a changelog by its unique identifier.

### Deletion Behavior

The changelog and all associated comments are permanently deleted. This action cannot be undone.

### Permissions

Only organization admins can delete changelogs.

### Response

Returns a deletion confirmation:

json
{
  "id": "6457e3ff70afca5d8c27dccc",
  "object": "changelog",
  "deleted": true
}


### Errors

- 400 - Invalid changelog ID format
- 404 - Changelog not found or doesn't belong to your organization

## Publish a changelog

 - [POST /v2/changelogs/{id}/publish](https://docs.featurebase.app/rest-api/changelogs/publishchangelog.md): Publishes a changelog and optionally sends an email notification to subscribers.

### Optional Fields

- sendEmail - Whether to send an email notification to subscribers (default: false)
- locales - Array of locales to publish. An empty array publishes to all available locales
- scheduledDate - A future date/time when the changelog should be published

### Scheduling

If scheduledDate is provided:
- Must be a future date
- The changelog will be scheduled for publishing at that time
- Any existing scheduled publish for the same locales will be cancelled and replaced

### Email Notifications

If sendEmail is true:
- Email notifications are sent to all subscribers in the published locales
- Emails are only sent once per locale (won't resend on republish)

### Response

Returns a success confirmation:

json
{
  "success": true,
  "state": "published"
}


Or for scheduled publishes:

json
{
  "success": true,
  "state": "scheduled"
}


### Errors

- 400 - Invalid changelog ID or scheduled date is not in the future
- 404 - Changelog not found or doesn't belong to your organization

## Unpublish a changelog

 - [POST /v2/changelogs/{id}/unpublish](https://docs.featurebase.app/rest-api/changelogs/unpublishchangelog.md): Unpublishes a changelog, removing it from public view.

### Optional Fields

- locales - Array of locales to unpublish from. An empty array unpublishes from all locales

### Behavior

- The changelog content is preserved (reverts to draft state)
- Any scheduled publishes for the specified locales are cancelled
- The changelog can be re-published later

### Response

Returns a success confirmation:

json
{
  "success": true,
  "state": "unpublished"
}


### Errors

- 400 - Invalid changelog ID format
- 404 - Changelog not found or doesn't belong to your organization

## Add changelog subscribers

 - [POST /v2/changelogs/subscribers](https://docs.featurebase.app/rest-api/changelogs/addchangelogsubscribers.md): Adds email addresses as changelog subscribers in bulk.

Subscribers will receive email notifications when new changelogs are published (if email notifications are enabled during publishing).

### Request Body

- emails - Array of email addresses to add (required, 1-1000 emails)
- locale - Locale for the subscribers (optional, defaults to organization default)

### Email Validation

- Invalid email addresses are automatically filtered out
- Emails are normalized (trimmed, lowercased)
- Duplicate emails are deduplicated

### Rate Limiting

This endpoint is rate limited to prevent abuse. If you need to import more subscribers, please contact support.

### Response

Returns a confirmation with the count of processed emails:

json
{
  "object": "changelog_subscribers_import",
  "count": 150
}


### Errors

- 400 - Invalid request (empty emails array, too many emails)
- 429 - Rate limit exceeded

## Remove changelog subscribers

 - [DELETE /v2/changelogs/subscribers](https://docs.featurebase.app/rest-api/changelogs/removechangelogsubscribers.md): Removes email addresses from changelog subscribers in bulk.

Removed subscribers will no longer receive email notifications when new changelogs are published.

### Request Body

- emails - Array of email addresses to remove (required, 1-1000 emails)

### Email Handling

- Emails that don't exist as subscribers are silently ignored
- Emails are normalized (trimmed, lowercased) before matching

### Response

Returns a confirmation with the count of processed emails:

json
{
  "object": "changelog_subscribers_removal",
  "count": 150
}


### Errors

- 400 - Invalid request (empty emails array, too many emails)