Skip to main content
POST
/
knowledge
/
articles
Create an article
curl --request POST \
  --url https://api.getfernand.com/knowledge/articles \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "title": "How to get started",
  "slug": "how-to-get-started",
  "collections": [
    1,
    2
  ],
  "published": true
}
'
{
  "id": 123,
  "title": "How to get started",
  "seo_title": "Getting Started Guide - Complete Tutorial",
  "slug": "how-to-get-started",
  "previous_url": "<string>",
  "description": "Learn how to set up your account and start using our platform in minutes.",
  "content": "<p>Welcome to our platform! This guide will help you get started...</p>",
  "created": "2023-11-07T05:31:56Z",
  "last_updated": "2023-11-07T05:31:56Z",
  "published": true,
  "get_collections": [
    {
      "collection_id": 1,
      "sort": 1
    },
    {
      "collection_id": 3,
      "sort": 2
    }
  ],
  "visibility": "public",
  "get_url": "https://help.piedpiper.com/getting-started/introduction"
}
Creates a new help article. Articles must belong to at least one collection. The slug must be unique and URL-safe. Content can include HTML with images (as URLs or base64 data), which are automatically processed and uploaded to our CDN storage. When published, the article generates a social banner, processes content images, updates search indexes, and optionally indexes into the AI vector store for chat functionality. SEO title defaults to the regular title if not provided.

Authorizations

​
X-API-Key
string
header
required

Authenticate your account by including your secret key in API requests. You can manage your API keys in the Dashboard.

Authentication to the API is performed by using the HTTP Header X-API-Key.

Body

application/json
​
title
string
required

Display title of the article (required).

Maximum string length: 250
Example:

"How to get started"

​
slug
string
required

URL-safe slug for the article (required, lowercase alphanumeric with dashes/underscores).

Maximum string length: 250
Example:

"how-to-get-started"

​
collections
(integer | null)[]
required

Array of collection IDs where the article should be placed (required, at least one, can include null for root).

Example:
[1, 2]
​
published
boolean
required

Whether the article should be published immediately (required).

​
seo_title
string | null

SEO-optimized title for search engines (optional, defaults to title).

Maximum string length: 250
​
previous_url
string | null

Previous URL if migrating from another help system (optional).

Maximum string length: 250
​
description
string | null

Brief description of the article for SEO and previews (optional).

Maximum string length: 250
​
content
string | null

HTML content of the article (optional, max 10MB). Images can be base64-encoded or URLs.

Maximum string length: 16000000
​
template
string | null

Template name to load predefined content (optional).

Maximum string length: 250
​
visibility
enum<string>
default:public

Visibility setting - public (visible to all), chat (only in chat widget), chat_auth (only in chat for authenticated users).

Available options:
public,
chat,
chat_auth
Maximum string length: 10

Response

Article created successfully.

​
id
integer<int64>

Unique identifier for the article.

​
title
string

Display title of the article.

Maximum string length: 250
Example:

"How to get started"

​
seo_title
string

SEO-optimized title for search engines and meta tags.

Maximum string length: 250
Example:

"Getting Started Guide - Complete Tutorial"

​
slug
string

URL-safe slug used in the article's URL path.

Maximum string length: 250
Example:

"how-to-get-started"

​
previous_url
string | null

Previous URL if the article was migrated from another help system, used for redirect tracking.

Maximum string length: 250
​
description
string | null

Brief description used for SEO meta tags and article previews.

Maximum string length: 250
Example:

"Learn how to set up your account and start using our platform in minutes."

​
content
string | null

Full HTML content of the article including formatted text, images, code blocks, and embedded media.

Example:

"<p>Welcome to our platform! This guide will help you get started...</p>"

​
created
string<date-time>

Timestamp when the article was originally created.

​
last_updated
string<date-time>

Timestamp when the article was last modified.

​
published
boolean

Whether the article is published and visible to users (unpublished articles are drafts).

​
get_collections
object[]

List of collections this article belongs to with their sort positions.

Example:
[
  { "collection_id": 1, "sort": 1 },
  { "collection_id": 3, "sort": 2 }
]
​
visibility
enum<string>

Visibility setting - public (visible to all), chat (only in chat widget), chat_auth (only in chat for authenticated users).

Available options:
public,
chat,
chat_auth
Maximum string length: 10
Example:

"public"

​
get_url
string

Full computed URL path to access the article, including collection hierarchy.

Example:

"https://help.piedpiper.com/getting-started/introduction"