Skip to Content
APIリファレンスヘルプセンター

ヘルプセンター

プロジェクトのヘルプセンター記事とそのカテゴリを管理します。プロジェクトでヘルプセンターが有効になっている必要があり、オフの場合は以下のすべてのエンドポイントが 404 を返します。

記事の本文は HTML ではなく Markdown です。ポータルは生の HTML を決して評価しないビューアで描画するため、送った HTML は読者にそのままの文字列として表示されます。

GET/v1/articles

ParameterTypeDescription
statusstringステータスで絞り込み: draft、published、archived。
category_idstringこのカテゴリの記事のみ。
limitintegerページサイズ。既定 25、最大 100。
offsetintegerスキップする件数。既定 0。

GET/v1/articles/search

ParameterTypeDescription
qrequiredstring検索クエリ。引用符付きフレーズ、OR、-による除外に対応。
limitinteger結果件数。既定 25、最大 100。

GET/v1/articles/:id

POST/v1/articles

ParameterTypeDescription
titlerequiredstring200 文字まで。
bodystringMarkdown。50,000 文字まで。
excerptstring1 行の要約、300 文字まで。省略時は本文から生成。
slugstringURL セグメント、80 文字まで。省略時はタイトルから生成。
category_idstring記事を分類するカテゴリ。

PATCH/v1/articles/:id

ParameterTypeDescription
titlestring新しいタイトル。
bodystring新しい Markdown 本文。
excerptstring新しい要約。null で消去。
slugstring新しい URL セグメント。
category_idstring新しいカテゴリ。null でカテゴリ無しに。
statusstringdraft、published、archived。

DELETE/v1/articles/:id

記事は必ず 下書き として作成されます。公開は別の PATCH なので、誤ってポータルに出ることはありません。記事の作成には有料プランの書き込みアクセスが必要で、ここにある他のすべての更新系メソッドも同様です。

記事の一覧

curl "https://api.supdesk.app/v1/articles?status=published&limit=10" \
  -H "Authorization: Bearer sd_live_..."
{
  "data": [
    {
      "id": "8f7a...",
      "title": "パスワードをリセットするには？",
      "slug": "how-do-i-reset-my-password",
      "body": "**設定** を開き、*パスワードをリセット* を選びます。",
      "excerpt": "設定を開き、パスワードをリセットを選びます。",
      "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 }
}

絞り込まない場合は下書きとアーカイブ済みも含め、更新が新しい順に返ります。顧客に実際に見えているものだけが必要なら status=published を指定してください。

記事の検索

curl "https://api.supdesk.app/v1/articles/search?q=パスワード+リセット&limit=5" \
  -H "Authorization: Bearer sd_live_..."
{
  "data": [
    {
      "id": "8f7a...",
      "title": "パスワードをリセットするには？",
      "slug": "how-do-i-reset-my-password",
      "category_slug": "getting-started",
      "category_name": "はじめに",
      "snippet": "設定を開き、パスワードをリセットを選びます。",
      "rank": 0.6079
    }
  ]
}

公開済みの記事のみを対象とした全文検索で、関連度順に並び、一致箇所の周辺をプレーンテキストの抜粋で返します。タイトルは要約より、要約は本文より重く評価されます。空のクエリや解析できないクエリはエラーではなく空のリストを返します。

記事の取得

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

一覧と同じ形の記事を 1 件返します。プロジェクト内に該当 id がなければ 404 です。

記事の作成

curl -X POST https://api.supdesk.app/v1/articles \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "パスワードをリセットするには？",
    "body": "**設定** を開き、*パスワードをリセット* を選びます。",
    "category_id": "3c2b..."
  }'
{
  "data": {
    "id": "8f7a...",
    "title": "パスワードをリセットするには？",
    "slug": "how-do-i-reset-my-password",
    "body": "**設定** を開き、*パスワードをリセット* を選びます。",
    "excerpt": "設定を開き、パスワードをリセットを選びます。",
    "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"
  }
}

201 を返します。slug を省くとタイトルから生成し、そのアドレスが使用済みなら -2、-3… と接尾辞を付けます。excerpt を省くと本文から生成します。

プランごとにプロジェクトが保持できる記事数の上限があります — Free 5、Pro 50、Team 無制限。上限を超えると limit_reached（429）を返します。アーカイブ済みは数えないため、アーカイブすると 1 枠空きます。

記事の更新

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

書き込まれるのは送ったフィールドだけなので、PATCH が省略したフィールドを空にすることはありません。status を published にすると初回に published_at が記録され、以降は保持されます — 誤字を直しただけで古い記事が新着扱いになることはありません。archived にすると、削除せずにポータルから下げられます。

アーカイブから戻す操作ではプランの上限を再確認するため、limit_reached が返ることがあります。

記事の削除

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

記事と読者からのフィードバックを完全に削除し、204 を返します。記事を残したまま下げたい場合は、ステータスを archived にしてください。

カテゴリ

GET/v1/article-categories

ParameterTypeDescription
limitintegerページサイズ。既定 25、最大 100。
offsetintegerスキップする件数。既定 0。

GET/v1/article-categories/:id

POST/v1/article-categories

ParameterTypeDescription
namerequiredstring80 文字まで。
descriptionstringポータルに表示、300 文字まで。
sort_orderinteger表示位置。既定 0。

PATCH/v1/article-categories/:id

ParameterTypeDescription
namestring新しい名前。
descriptionstring新しい説明。null で消去。
sort_orderinteger新しい表示位置。

DELETE/v1/article-categories/:id

curl -X POST https://api.supdesk.app/v1/article-categories \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "はじめに", "sort_order": 1 }'
{
  "data": {
    "id": "3c2b...",
    "name": "はじめに",
    "slug": "getting-started",
    "description": null,
    "sort_order": 1,
    "created_at": "2026-07-01T09:12:00Z"
  }
}

カテゴリは sort_order、次に名前の順で返ります。スラッグは、記事のスラッグがタイトルから作られるのと同じ方法で名前から作られます。

カテゴリの削除は 204 を返し、その記事は 削除しません — カテゴリ無しになるだけで、検索からもヘルプセンターのトップページからも引き続きたどれます。

エラー

標準のコードに加えて:

コードステータス発生条件
not_found404未知の id — またはこのプロジェクトでヘルプセンターがオフ。
forbidden403API 書き込みアクセスのないプランでの書き込み。
limit_reached429プランの記事枠を使い切った。
Last updated on
ベータWebhook