Документация API

WebClipper предоставляет REST API для работы с вырезками, папками, рецептами, списками покупок, группами и настройками кабинета. API возвращает JSON и поддерживает CORS, поэтому к нему можно обращаться напрямую из браузера, расширения или мобильного приложения.

Все эндпоинты, кроме перечисленных как открытые (health, register, login, download расширения), требуют аутентификации.

API принимает три способа передачи идентификации. Токен выдаётся в личном кабинете и живёт 7 дней.

Authorization: Bearer eyJ1c2VySWQiOiJleGFtcGxlIiw...

X-WebClipper-Token: eyJ1c2VySWQiOiJleGFtcGxlIiw...

Если токен отсутствует или истёк, API возвращает 401 {"error":"Не авторизован"}.

Полный список основных эндпоинтов. Все пути указываются относительно базового адреса; :id — это UUID объекта.

Создать вырезку · POST /api/clippings

Сохраняет вырезку в кабинет пользователя. Это основной метод, который использует расширение браузера при захвате текста. При успехе возвращается 201 и созданная вырезка.

Поля id, userId, position и createdAt назначает сервер.

Список вырезок · GET /api/clippings

Возвращает массив вырезок текущего пользователя, отсортированный по позиции.

Обновить · PUT /api/clippings/:id

Частичное обновление. Обязателен только title (от 1 до 300 символов); остальные поля опциональны: excerpt, html, tags, accent, encrypted, type. Возвращает {"success":true}.

Переместить · PATCH /api/clippings/:id

Перемещает вырезку в другую папку. Тело: {"folderId":"..."} или {"folderId":null}, чтобы убрать вырезку из папки. Ответ — 204.

Удалить · DELETE /api/clippings/:id

Удаляет вырезку. Ответ — 204.

Дополнительные операции

• PATCH /api/clippings/reorder — порядок вырезок в папке. Тело: {"folderId":"...","order":["id1","id2",...]}.
• POST /api/clippings/:id/copy — копия вырезки (необязательно в папку folderId).
• POST /api/clippings/:id/link — создаёт публичную ссылку, возвращает {"url":"/share/...","token":"..."}.
• DELETE /api/clippings/:id/link?token=... — отменяет публичную ссылку.

Создать папку · POST /api/folders

Создаёт папку для организации вырезок. Поддерживается вложенность до 3 уровней через parentId. При успехе возвращается 201 и созданная папка.

Остальные методы

• GET /api/folders — список папок пользователя.
• PATCH /api/folders/:id — обновление папки (поля те же, что при создании: name, icon, cover, backgroundImage, parentId).
• DELETE /api/folders/:id — удаление папки, ответ 204.

GET /api/settings

Возвращает настройки кабинета текущего пользователя.

PUT /api/settings

Обновляет настройки. Достаточно передать только изменяемые поля.

Формат ошибки: {"error":"...","details":{...}}.

Сохранить вырезку (curl)

curl -X POST "https://webclipper.ru/api/clippings" \
  -H "Content-Type: application/json" \
  -H "X-WebClipper-Token: ВАШ_ТОКЕН" \
  -d '{
    "title": "Пример статьи",
    "excerpt": "Текст сохранённой вырезки",
    "html": "<p>Текст с <b>форматированием</b></p>",
    "source": "https://example.com/article",
    "tags": ["интересное", "статья"],
    "accent": "indigo",
    "type": "article"
  }'

Сохранить вырезку (JavaScript / fetch)

// Пример для браузера или Node.js
const res = await fetch("https://webclipper.ru/api/clippings", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer ВАШ_ТОКЕН", // или X-WebClipper-Token
  },
  body: JSON.stringify({
    title: "Пример статьи",
    excerpt: "Текст сохранённой вырезки",
    source: "https://example.com/article",
  }),
});

if (res.ok) {
  const clipping = await res.json();
  console.log("Сохранено, id:", clipping.id);
} else {
  const err = await res.json();
  console.error("Ошибка:", err.error, err.details);
}

Получить список папок (curl)

curl "https://webclipper.ru/api/folders" \
  -H "X-WebClipper-Token: ВАШ_ТОКЕН"

Переместить вырезку в папку (curl)

curl -X PATCH "https://webclipper.ru/api/clippings/9f1c3a42-2c11-4d9a-8b6e-1d34c99a2f70" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ВАШ_ТОКЕН" \
  -d '{ "folderId": "7a2d0f11-9a51-4c32-a6e7-4d8b22f0c3e1" }'