Changelogs

Create a changelog

Creates a changelog (release note). Omit state or use state: "draft" to save a draft. Use state: "live" to publish it in the same request, without notification emails.

POST

/v2/outbound/changelogs

Create a changelog

curl --request POST \
  --url https://do.featurebase.app/v2/outbound/changelogs \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-09-03.pulsar' \
  --header 'Content-Type: application/json' \
  --data '
{
  "allowedSegmentIds": [
    "507f1f77bcf86cd799439011"
  ],
  "categories": [
    "New",
    "Fixed",
    "Improved"
  ],
  "date": "2024-01-15",
  "featuredImage": "https://example.com/image.png",
  "htmlContent": "<p>Exciting new features to explore.</p>",
  "idempotencyKey": "create-onboarding-2026-11-05",
  "locale": "en",
  "markdownContent": "Exciting new features to explore.",
  "state": "live",
  "title": "New Features changelog",
  "translations": {
    "fr": {
      "markdownContent": "De nouvelles fonctionnalités.",
      "title": "Nouveautés"
    }
  }
}
'

{
  "allowedSegmentIds": [],
  "availableLocales": [
    "en",
    "de",
    "fr"
  ],
  "categories": [
    {
      "id": "6438a1efda3640f8feb72121",
      "name": "New Features",
      "roles": []
    }
  ],
  "commentCount": 2,
  "content": "<p>Your changelog content in HTML format.</p>",
  "createdAt": "2023-12-12T00:00:00.000Z",
  "date": "2023-05-07T12:59:59.000Z",
  "emailSentToSubscribers": true,
  "featuredImage": "https://cdn.example.com/images/feature.png",
  "id": "6457e3ff70afca5d8c27dccc",
  "isDraftDiffersFromLive": false,
  "isPublished": true,
  "locale": "en",
  "markdownContent": "Your changelog content in markdown format.",
  "notifications": {},
  "object": "changelog",
  "organization": "myorg",
  "publishedLocales": [
    "en",
    "de"
  ],
  "slug": "your-awesome-changelog",
  "slugs": {
    "de": "dein-tolles-changelog",
    "en": "your-awesome-changelog"
  },
  "state": "live",
  "title": "Your awesome changelog!",
  "updatedAt": "2023-12-13T00:00:00.000Z",
  "url": "https://myorg.featurebase.app/en/changelog/your-awesome-changelog"
}

For imports, provide date to preserve the original publication date. Live creation uses the normal publishing flow, and emits the existing changelog.published webhook. To publish an existing draft, schedule publication or request notification emails, use POST /v2/outbound/changelogs/{id}/publish.

Supply translations to create multiple languages in one request. Each key is an enabled locale; each new entry needs title and nonempty htmlContent or markdownContent. Top-level title and content are still required and override the primary-locale entry. With state: "live", all created translations publish without notification emails. Media limits apply across all languages: 100 items, 15 MB per image and 50 MB total imported images. Uploaded assets are not rolled back if a later step fails.

Live creation requires an enabled changelog locale. Every allowedSegmentId must exist in your organization; invalid IDs are rejected rather than removed. If publication fails after creation, inspect the Changelog at the response's Location header before retrying publication. Do not repeat the create request. The response includes x-should-retry: false to prevent automatic SDK retries after creation.

Required Fields

title - The title of the Changelog

Content

Provide content in one of two formats (at least one is required):

htmlContent - HTML content, including Featurebase custom blocks
markdownContent - Markdown content

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"]). Categories must already exist
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. Accepts user segment ids and company segment ids (a company segment means "people with a company in the segment"). Every id must be a segment of your organization: an unknown or deleted id is rejected with 400.
locale - The locale of the Changelog (defaults to the organization default)
date - The date of the Changelog
state - draft (default) or live. Live creation publishes immediately without notification emails

Response

Returns the created Changelog object with object: "changelog".

Errors

400 - Invalid or missing fields
404 - A category name does not exist in your organization

Compatibility

Changelogs appear as Updates in the dashboard. Keep using /v2/outbound/changelogs, client.outbound.changelogs, and the changelog.published webhook. This reference describes Pulsar. The original /v2/changelogs routes still work; their behavior follows the selected API version. The Outbound paths require Pulsar or later. In Pulsar, the API key owner needs a full seat and the manage_changelogs permission.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-09-03.pulsar, 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Example: 2026-09-03.pulsar

Body

allowedSegmentIdsstring[]

Segment IDs that can view the changelog

Maximum array length: 100

categoriesstring[]

Category names for the changelog

Maximum array length: 100

datestring | null

The changelog date

Example: 2024-01-15

featuredImagestring

Featured image URL for the changelog. External images are uploaded to Featurebase storage.

Example: https://example.com/image.png

htmlContentstring

HTML content of the changelog. Provide either htmlContent or markdownContent. Featurebase custom blocks and external image uploads are supported.

Example: <p>Exciting new features to explore.</p>

idempotencyKeystring

Optional retry protection. Retrying with the same key and request returns the first result (for 7 days) instead of creating a copy. The same key with another request answers 409 idempotency_conflict.

Required string length: 8 - 128

Pattern: ^[a-zA-Z0-9_.:-]+$

Example: create-onboarding-2026-11-05

localeenum<string>

The changelog locale. Defaults to the organization default locale.

Available options: ar, am, fa, ht, lo, my, pa, ps, so, tl, ur, he, ta, te, mr, gu, kn, ml, ha, jv, yo, ig, uz, ne, sd, az, si, km, kk, bn, bs, pt-BR, bg, ca, hr, cs, da, nl, en, et, fi, fr, de, el, hi, hu, id, it, ja, ko, lv, lt, ms, mn, nb, pl, pt, ro, ru, sr, zh-CN, sk, sl, es, sw, sv, th, zh-TW, tr, uk, vi

Example: en

markdownContentstring

Markdown content of the changelog. Provide either htmlContent or markdownContent.

Example: Exciting new features to explore.

stateenum<string>default:draft

Create a draft (default) or publish immediately with live. Live creation preserves the supplied date and does not send notification emails.

Available options: draft, live

Example: live

titlestringrequired

The title of the changelog

Required string length: 1 - 512

Example: New Features changelog

translationsobject

Locale-keyed draft content. Each locale must be enabled in changelog settings. New translations require title and nonempty htmlContent or markdownContent; existing translations preserve omitted fields. Top-level localized fields override the primary-locale entry. An empty dictionary uses the single-locale flow; an empty existing-locale entry is a no-op. POST still requires top-level title and content. POST with state="live" publishes all supplied translations without notification emails. PATCH edits drafts only. Media limits apply across the whole request.

Show child attributes

Response

Created

allowedSegmentIdsstring[]required

Segment IDs that are allowed to view this changelog

availableLocalesstring[]required

Array of locale codes where the changelog has content

categoriesobject[]required

Categories the changelog belongs to

Show child attributes

commentCountnumberrequired

Number of comments

Example: 2

contentstringrequired

Content in HTML format

Example: <p>Your changelog content in HTML format.</p>

createdAtstringrequired

ISO 8601 timestamp when created

Example: 2023-12-12T00:00:00.000Z

datestringrequired

Publication date as ISO 8601 timestamp

Example: 2023-05-07T12:59:59.000Z

emailSentToSubscribersbooleanrequired

Whether email notification was sent to subscribers

Example: true

featuredImagestring | nullrequired

Featured image URL

Example: https://cdn.example.com/images/feature.png

idstringrequired

Unique identifier

Example: 6457e3ff70afca5d8c27dccc

isDraftDiffersFromLivebooleanrequired

Whether the draft content differs from the published live content

Example: false

isPublishedbooleanrequired

Whether the changelog is published (has a live version) in this locale

Example: true

localeenum<string>required

Locale of the changelog

Example: en

markdownContentstring | nullrequired

Content in markdown format

Example: Your changelog content in markdown format.

notificationsobjectrequired

Notification settings for each locale

objectenum<string>required

Object type identifier

Available options: changelog

Example: changelog

organizationstringrequired

Organization identifier

Example: myorg

publishedLocalesstring[]required

Array of locale codes where the changelog is published

slugstringrequired

URL-friendly slug

Example: your-awesome-changelog

slugsobjectrequired

URL-friendly slugs for each locale

stateenum<string>required

State of the changelog

Available options: live, draft

Example: live

titlestringrequired

Changelog title

Example: Your awesome changelog!

updatedAtstringrequired

ISO 8601 timestamp when updated

Example: 2023-12-13T00:00:00.000Z

urlstringrequired

Public URL to view the changelog

Example: https://myorg.featurebase.app/en/changelog/your-awesome-changelog

Still need help? Ask the team