Центр помощи

Управление статьями центра помощи проекта и их категориями. Требуется, чтобы центр помощи был включён для проекта — если он выключен, все эндпоинты ниже возвращают 404.

Текст статей — это Markdown, а не HTML. Портал отображает его через просмотрщик, который никогда не выполняет сырой HTML, поэтому любой отправленный HTML читатели увидят как обычный текст.

GET/v1/articles

Parameter	Type	Description
`status`	`string`	Фильтр по статусу: draft, published или archived.
`category_id`	`string`	Только статьи этой категории.
`limit`	`integer`	Размер страницы. По умолчанию 25, максимум 100.
`offset`	`integer`	Сколько элементов пропустить. По умолчанию 0.

GET/v1/articles/search

Parameter	Type	Description
`q`required	`string`	Поисковый запрос. Поддерживает фразы в кавычках, OR и -отрицание.
`limit`	`integer`	Количество результатов. По умолчанию 25, максимум 100.

GET/v1/articles/:id

POST/v1/articles

Parameter	Type	Description
`title`required	`string`	До 200 символов.
`body`	`string`	Markdown. До 50 000 символов.
`excerpt`	`string`	Краткое описание в одну строку, до 300 символов. Если не указано — берётся из текста.
`slug`	`string`	Сегмент URL, до 80 символов. Если не указан — строится из заголовка.
`category_id`	`string`	Категория, в которую поместить статью.

PATCH/v1/articles/:id

Parameter	Type	Description
`title`	`string`	Новый заголовок.
`body`	`string`	Новый текст в Markdown.
`excerpt`	`string`	Новое описание; null очищает его.
`slug`	`string`	Новый сегмент URL.
`category_id`	`string`	Новая категория; null убирает категорию.
`status`	`string`	draft, 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": "kak-sbrosit-parol",
      "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": "kak-sbrosit-parol",
      "category_slug": "nachalo-raboty",
      "category_name": "Начало работы",
      "snippet": "Откройте Настройки и выберите Сбросить пароль.",
      "rank": 0.6079
    }
  ]
}

Полнотекстовый поиск только по опубликованным статьям, отсортированный по релевантности, с текстовым фрагментом вокруг совпадения. Заголовки весят больше описаний, а описания — больше текста. Пустой или неразбираемый запрос возвращает пустой список, а не ошибку.

Получить статью


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

Возвращает одну статью в том же виде, что и в списке, либо 404, если такой id в вашем проекте неизвестен.

Создать статью


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": "kak-sbrosit-parol",
    "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). Архивные статьи не учитываются, поэтому архивирование освобождает место.

Обновить статью


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

Parameter	Type	Description
`limit`	`integer`	Размер страницы. По умолчанию 25, максимум 100.
`offset`	`integer`	Сколько элементов пропустить. По умолчанию 0.

GET/v1/article-categories/:id

POST/v1/article-categories

Parameter	Type	Description
`name`required	`string`	До 80 символов.
`description`	`string`	Показывается на портале, до 300 символов.
`sort_order`	`integer`	Позиция отображения. По умолчанию 0.

PATCH/v1/article-categories/:id

Parameter	Type	Description
`name`	`string`	Новое название.
`description`	`string`	Новое описание; null очищает его.
`sort_order`	`integer`	Новая позиция отображения.

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": "nachalo-raboty",
    "description": null,
    "sort_order": 1,
    "created_at": "2026-07-01T09:12:00Z"
  }
}

Категории перечисляются по sort_order, затем по названию. Слаги строятся из названия так же, как слаги статей строятся из заголовка.

Удаление категории возвращает 204 и не удаляет её статьи — они остаются без категории и по-прежнему доступны через поиск и с главной страницы центра помощи.

Ошибки

Помимо стандартных кодов:

Код	Статус	Когда
`not_found`	404	Неизвестный id — либо центр помощи отключён для этого проекта.
`forbidden`	403	Запись на плане без доступа к API на запись.
`limit_reached`	429	Квота статей плана исчерпана.