Create a changelog entry

Creates an entry as a draft, ready for someone to review, edit and publish in Ferndesk. Pass publish: true (with content:publish) to make it live straight away.

POST /v1/changelogs/{id}/entries

Bearer token scope content:write

curl 'https://api.ferndesk.com/v1/changelogs/art_01JXY9AZK4KV/entries?format=markdown' \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "Faster search",
  "markdown": "Search results now load **twice as fast**.",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Welcome to Ferndesk."
          }
        ]
      }
    ]
  },
  "date": "2026-09-30",
  "tags": [
    "new",
    "improved"
  ],
  "announce": false,
  "publish": false
}'

{
  "id": "art_01JXY9AZK4KV",
  "changelogId": "col_01JXYA6ABN52",
  "title": "Faster search",
  "slug": "faster-search",
  "contentHtml": "<p>Search results now load twice as fast.</p>",
  "contentMarkdown": "Search results now load twice as fast.",
  "contentJson": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Welcome to Ferndesk."
          }
        ]
      }
    ]
  },
  "url": "https://docs.example.com/faster-search-A1B2C3",
  "status": "published",
  "date": "2026-09-30",
  "tags": [
    "new"
  ],
  "announce": false,
  "publishedAt": "2026-09-30T14:02:11.000Z",
  "createdAt": "2026-01-15T18:25:43.511Z",
  "updatedAt": "2026-01-15T18:25:43.511Z",
  "draft": {
    "id": "drft_01JXY9AZK4KV",
    "title": "Faster search",
    "contentHtml": "<p>Search results now load twice as fast.</p>",
    "contentMarkdown": "Search results now load twice as fast.",
    "contentJson": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "Welcome to Ferndesk."
            }
          ]
        }
      ]
    },
    "source": "api",
    "updatedAt": "2026-01-15T18:25:43.511Z"
  }
}

Created entry; its body is in draft until published

Path parameters

· 1

id string required

Identifier of the requested resource.

Query parameters

· 1

format string · default: html· enum

Which body field to populate: contentHtml, contentMarkdown, or the lossless contentJson.

values

html
markdown
json

Body

required application/json

title string · min length: 1 required

Entry title.

markdown string

Body as Markdown, converted to rich text; not accepted alongside content.

content any

Body as a Tiptap document; not accepted alongside markdown.

date string · pattern

Date to show on the entry, YYYY-MM-DD. Leave it out to use the day the entry is published.

tags array of string · max items: 4

Tags for the entry. Duplicates are ignored.

values

new
improved
fixed
breaking

announce boolean · default: false

Announces the entry in the help widget once it is live. When a person publishes the entry in Ferndesk, the editor asks them to confirm this choice.

publish boolean · default: false

Publishes the entry in the same call (needs content:publish). By default it is left as a draft for a person to review in Ferndesk.

Path parameters

Query parameters

Body

Responses