Ferndesk

Articles

Export articles incrementally

A sync feed of every article in your help center, ordered oldest-updated_at first, cursor-paginated.

Unlike GET /articles, this feed is the complete mirror contract:

  • It includes every status — draft, published, unpublished, AND trashed articles all appear, each carrying its current status. A trashed article shows up here with status: "trashed" so a downstream mirror can delete it. This is intentional: consumers see deletions and unpublishes as status transitions rather than rows silently vanishing.
  • since (ISO 8601) is required on the first request and bounds the feed to articles updated at or after that time.
  • On subsequent pages omit since and pass the next_cursor from the previous response as start_cursor; the cursor carries the exact (updated_at, id) position.
  • format=markdown returns contentMarkdown instead of contentHtml.

Requires the content:write scope (the feed includes non-published statuses).

Required scope: content:write

GET /articles/incremental

Export articles incrementally

curl --request GET \
  --url 'https://api.ferndesk.com/v1/articles/incremental' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "results": [
    {
      "id": "<string>",
      "title": "<string>",
      "slug": "<string>",
      "contentHtml": "<string>",
      "contentMarkdown": "<string>",
      "contentJson": "<string>",
      "url": "<url>",
      "sectionId": "<string>",
      "collectionId": "<string>",
      "status": "<string>",
      "publishedAt": "<string>",
      "createdAt": "<string>"
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}

Cursor-paginated incremental article page

Authorizations

  • Authorization string required header

    All requests require a Bearer token in the Authorization header. API keys are prefixed with fdsk_ and should be kept secret. You can generate and manage keys from the Developer settings page.

    Keys can be restricted to any subset of these scopes (each endpoint lists the scope it requires via x-required-scopes):

    • content:read: Read and search help center articles, collections, sections, and translations
    • content:write: Create and edit article drafts, users, tasks; move articles and collections
    • content:publish: Publish, unpublish, restore, and trash content (make changes live)
    • analytics:read: Read help center reporting, analytics, and article feedback
    • conversations:read: Read AI assistant conversations and transcripts
    • webhooks:manage: Create and manage outbound webhook subscriptions

    Granting content:write or content:publish implies content:read. Keys minted before scoping have null scopes = full access (legacy mode).

Query Parameters

  • format string enum

    Content rendering format. html (default) returns contentHtml; markdown returns contentMarkdown; json returns contentJson — the raw stored ProseMirror/Tiptap document. The JSON uses Ferndesk’s ProseMirror schema (custom nodes like callout, steps, and cards) and is the lossless representation of the article body. Example: markdown

  • page_size integer

    Number of items to return per page (1-100). Example: 20

  • since string (date-time)

    ISO 8601 timestamp lower bound (inclusive) on updated_at. Required on the first request; omit it and pass start_cursor on subsequent pages. Example: 2026-01-15T18:25:43.511Z

  • start_cursor string

    Opaque pagination cursor. Pass the next_cursor from a previous response to fetch the next page. Example: eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ

Response

application/json
  • results[] object array

    Items in this page. Article payload returned by article endpoints.

    + Show Child Attributes
    • id string

      Ferndesk article ID (art_...).

    • title string

      Primary article title.

    • slug string | null

      URL slug for the article.

    • contentHtml string

      Article content rendered as HTML. Present when format=html (default).

    • contentMarkdown string

      Article content rendered as Markdown. Present when format=markdown.

    • contentJson any | null

      Raw stored ProseMirror/Tiptap document. Present when format=json. Uses Ferndesk’s ProseMirror schema (custom nodes like callout, steps, cards) and is the lossless representation.

    • url string (uri) | null

      Canonical public URL for this article.

    • sectionId string | null

      Section ID containing the article.

    • collectionId string | null

      Optional collection grouping ID for the article.

    • status string | null

      Article publish status.

    • publishedAt string | null

      Timestamp when the article was published.

    • createdAt string

      ISO 8601 timestamp in UTC.

    • updatedAt string

      ISO 8601 timestamp in UTC.

  • has_more boolean

    Whether more items are available after this page.

  • next_cursor string | null

    Cursor to pass as start_cursor for the next page, or null on the last page.