Help Center

Manage the project’s help-center articles and their categories. Requires the help center to be enabled for the project — when it’s off, every endpoint below returns 404.

Article bodies are Markdown, not HTML. The portal renders them through a viewer that never evaluates raw HTML, so any HTML you post is shown to readers as literal text.

GET/v1/articles

Parameter	Type	Description
`status`	`string`	Filter by status: draft, published, or archived.
`category_id`	`string`	Only articles in this category.
`limit`	`integer`	Page size. Defaults to 25, max 100.
`offset`	`integer`	Number of items to skip. Defaults to 0.

GET/v1/articles/search

Parameter	Type	Description
`q`required	`string`	Search query. Supports quoted phrases, OR, and -negation.
`limit`	`integer`	Result count. Defaults to 25, max 100.

GET/v1/articles/:id

POST/v1/articles

Parameter	Type	Description
`title`required	`string`	Up to 200 characters.
`body`	`string`	Markdown. Up to 50,000 characters.
`excerpt`	`string`	One-line summary, up to 300 characters. Derived from the body when omitted.
`slug`	`string`	URL segment, up to 80 characters. Derived from the title when omitted.
`category_id`	`string`	Category to file the article under.

PATCH/v1/articles/:id

Parameter	Type	Description
`title`	`string`	New title.
`body`	`string`	New Markdown body.
`excerpt`	`string`	New summary; null clears it.
`slug`	`string`	New URL segment.
`category_id`	`string`	New category; null makes the article uncategorised.
`status`	`string`	draft, published, or archived.

DELETE/v1/articles/:id

Articles are always created as drafts — publishing is a separate PATCH, so nothing reaches your portal by accident. Creating an article requires paid-plan write access, as does every other mutating method here.

List articles


curl "https://api.supdesk.app/v1/articles?status=published&limit=10" \
  -H "Authorization: Bearer sd_live_..."


{
  "data": [
    {
      "id": "8f7a...",
      "title": "How do I reset my password?",
      "slug": "how-do-i-reset-my-password",
      "body": "Open **Settings**, then choose *Reset password*.",
      "excerpt": "Open Settings, then choose Reset password.",
      "status": "published",
      "category_id": "3c2b...",
      "published_at": "2026-07-01T09:12:00Z",
      "helpful_count": 12,
      "not_helpful_count": 1,
      "created_at": "2026-06-28T14:03:00Z",
      "updated_at": "2026-07-01T09:12:00Z"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "has_more": false }
}

Unfiltered, this returns drafts and archived articles too, newest edit first. Pass status=published for what customers can actually see.

Search articles


curl "https://api.supdesk.app/v1/articles/search?q=reset+password&limit=5" \
  -H "Authorization: Bearer sd_live_..."


{
  "data": [
    {
      "id": "8f7a...",
      "title": "How do I reset my password?",
      "slug": "how-do-i-reset-my-password",
      "category_slug": "getting-started",
      "category_name": "Getting started",
      "snippet": "Open Settings, then choose Reset password.",
      "rank": 0.6079
    }
  ]
}

Full-text search over published articles only, ranked, with a plain-text snippet around the match. Titles are weighted above summaries, and summaries above bodies. An empty or unparseable query returns an empty list rather than an error.

Get an article


curl "https://api.supdesk.app/v1/articles/8f7a..." \
  -H "Authorization: Bearer sd_live_..."

Returns a single article in the same shape as the list, or 404 when the id is unknown in your project.

Create an article


curl -X POST https://api.supdesk.app/v1/articles \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How do I reset my password?",
    "body": "Open **Settings**, then choose *Reset password*.",
    "category_id": "3c2b..."
  }'


{
  "data": {
    "id": "8f7a...",
    "title": "How do I reset my password?",
    "slug": "how-do-i-reset-my-password",
    "body": "Open **Settings**, then choose *Reset password*.",
    "excerpt": "Open Settings, then choose Reset password.",
    "status": "draft",
    "category_id": "3c2b...",
    "published_at": null,
    "helpful_count": 0,
    "not_helpful_count": 0,
    "created_at": "2026-07-01T09:12:00Z",
    "updated_at": "2026-07-01T09:12:00Z"
  }
}

Returns 201. Omitting slug derives one from the title, with a -2, -3… suffix if that address is taken. Omitting excerpt derives one from the body.

Your plan caps how many articles a project can keep — Free 5, Pro 50, Team unlimited. Past the cap this returns limit_reached (429). Archived articles don’t count, so archiving one frees a slot.

Update an article


curl -X PATCH https://api.supdesk.app/v1/articles/8f7a... \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "published" }'

Only the fields you send are written, so a PATCH never blanks something you left out. Setting status to published stamps published_at the first time and preserves it afterwards — fixing a typo doesn’t make an old article look new. Setting it to archived retires the article without deleting it.

Un-archiving an article re-checks the plan cap, and can return limit_reached.

Delete an article


curl -X DELETE https://api.supdesk.app/v1/articles/8f7a... \
  -H "Authorization: Bearer sd_live_..."

Deletes the article and its reader feedback permanently, and returns 204. To retire an article while keeping it, set its status to archived instead.

Parameter	Type	Description
`limit`	`integer`	Page size. Defaults to 25, max 100.
`offset`	`integer`	Number of items to skip. Defaults to 0.

Parameter	Type	Description
`name`required	`string`	Up to 80 characters.
`description`	`string`	Shown on the portal, up to 300 characters.
`sort_order`	`integer`	Display position. Defaults to 0.

Parameter	Type	Description
`name`	`string`	New name.
`description`	`string`	New description; null clears it.
`sort_order`	`integer`	New display position.

Errors

Alongside the standard codes:

Code	Status	When
`not_found`	404	Unknown id — or the help center is switched off for this project.
`forbidden`	403	A write on a plan without API write access.
`limit_reached`	429	The plan’s article allowance is spent.