Create docs article

Create a help-center article. Pass language to create a translation row instead of populating the base. Requires the docs:write scope.

POST /docs/articles

Create docs article

cURL

curl --request POST \
  --url https://productlane.com/api/v2/docs/articles \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "<string>",
  "content": "<string>",
  "summary": "<string>",
  "group_id": "<string>",
  "parent_article_id": "<string>",
  "portal_instance_id": "<string>",
  "order": 1,
  "published": true,
  "icon": "<string>",
  "image_url": "<string>",
  "language": "<string>"
}
'

200

{
  "id": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "title": "<string>",
  "summary": "<string>",
  "content": "<string>",
  "icon": "<string>",
  "url_name": "<string>",
  "published": true,
  "visibility": "public",
  "visibility_tier": "public",
  "kind": "doc",
  "external_url": "<string>",
  "archived": true,
  "show_on_home_page": true,
  "image_url": "<string>",
  "group_id": "<string>",
  "parent_article_id": "<string>",
  "order": 123,
  "portal_instance_id": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

title · string · required

Minimum string length: 1

content · string · required

Markdown body. Tabs and code groups use the and tags. Example keys, ids and tokens are placeholders like <your-widget-key />, never a made-up value that looks real. House shape: one ## per section, a --- divider above each one that has content above it, > for a callout, and backticks for a navigation path.

Minimum string length: 1

summary · string

Maximum string length: 300

group_id · string

Required unless parent_article_id is set, in which case the article joins the parent's group.

Minimum string length: 1

parent_article_id · string

Root-level article id to nest this article under as a subpage. Subpages nest one level deep, join their parent's group and portal, and are never more visible than their parent.

Minimum string length: 1

portal_instance_id · string | null

Portal instance id to assign, from GET /docs/portals. Omit to inherit the parent's or the group's portal; null forces the Main (Root) portal.

order · integer

Position among its siblings, ascending. A subpage defaults to the end of its parent's subpages, any other article to the top of its group.

Required range: x >= 0

published · boolean

visibility · enum<string>

Defaults to public. agent keeps the article off your docs site while the Productlane Agent still answers from it; internal restricts it to the AI Assistant.

Available options: public, agent, internal, unlisted

icon · string

Nucleo icon name in PascalCase (e.g. FilePen). Defaults to Page2.

Required string length: 1 - 64

image_url · string<uri> | null

Cover image URL. Must be a file you uploaded through POST /api/v2/files, so it sits on our uploads domain. The blur placeholder the portal shows is computed for you.

language · string

BCP-47 language code. When set, the article is created with the body on a translation row and the base row stays empty.

Response

200

application/json

Successful response

id · string · required

created_at · string · required

updated_at · string · required

title · string · required

summary · string · required

content · string · required

icon · string · required

Name of a Nucleo icon (PascalCase, e.g. Notepad, Atom). Must be a valid icon from https://nucleoapp.com - unknown names will not render in the dashboard or portal.

url_name · string · required

published · boolean · required

visibility · enum<string> · required

Whether the article is on your docs site. Deprecated: read visibility_tier for the agent and internal split.

Available options: public, unlisted

visibility_tier · enum<string> · required

agent and internal articles both stay off your docs site and out of portal search. The Productlane Agent answers customers from an agent article, and never links it. An internal article is read by the AI Assistant alone.

Available options: public, agent, internal

kind · enum<string> · required

link rows point at a page you host elsewhere: content is empty and external_url holds the address.

Available options: doc, link

external_url · string | null · required

archived · boolean · required

show_on_home_page · boolean · required

image_url · string | null · required

group_id · string | null · required

parent_article_id · string | null · required

order · integer · required

Position among its siblings, ascending. Sort by it to match the order the docs site renders.

portal_instance_id · string | null · required