Ferndesk

Articles

Create an article

Creates a new help center article as an open draft. The article is not live until you publish it (POST /articles/:id/publish), or unless you pass publish: true to publish in one call (the legacy behavior).

Provide body content as either content (Tiptap JSON) or markdown.

Requires the content:write scope. Rate limit: 60 requests per hour per API key.

Required scope: content:write

POST /articles

Create an article

curl --request POST \
  --url 'https://api.ferndesk.com/v1/articles' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "key": "value"
}'
{
  "id": "<string>",
  "title": "<string>",
  "slug": "<string>",
  "contentHtml": "<string>",
  "contentMarkdown": "<string>",
  "contentJson": "<string>",
  "url": "<url>",
  "sectionId": "<string>",
  "collectionId": "<string>",
  "status": "<string>",
  "publishedAt": "<string>",
  "createdAt": "<string>"
}

Created article (draft, or published when publish=true)

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).

Request Body

application/json
  • title string required

    Article title.

  • content any

    Article content as a Tiptap/ProseMirror JSON document. Mutually exclusive with markdown.

  • markdown string

    Article content as Markdown. Converted to rich text on write. Mutually exclusive with content.

  • publish boolean default

    When true, the article is published immediately after creation (legacy one-call behavior). Defaults to false: creation leaves an open draft you publish separately. Default: false.

  • sectionId string required

    Section ID where the article should be created.

  • collectionId string | null

    Optional collection ID to group this article.

  • keywords string

    SEO keywords.

  • metaDescription string

    SEO meta description.

  • ogImage string

    Open Graph image URL.

  • slug string

    Custom URL slug. Providing a new slug automatically enables custom slug mode.

Response

application/json
  • 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.

  • draft_id string | null

    Open draft created for this article, or null when created with publish: true.