Розробникам

Створюйте з Welley

За допомогою Welley API можна створювати клієнти, скрипти, інструменти для спільнот та інтеграції. Актуальна довідка Swagger описує операції та схеми, які ви можете використовувати.

Відкрити актуальний Swagger UI Завантажити OpenAPI JSON

Ми плануємо в майбутньому випустити Welley з відкритим кодом. Дата випуску й ліцензія ще не оголошені.

Почніть із публічного запиту

API працює через HTTPS, і більшість операцій приймають і повертають JSON. Публічні операції читання можуть працювати без акаунта.

Прочитайте інформацію про сервер

Цей запит повертає публічні метадані про сервер. Він не змінює жодних даних сервера.

curl --fail --silent --show-error "https://welley.social/api/v1/instance"

Знайдіть операцію в Swagger

Перш ніж писати клієнт, перевірте параметри операції, схему запиту, схему відповіді та дозволи.

Автентифікація інтеграції

Захищені операції потребують чинного токена в заголовку Authorization. Наш офіційний CLI надсилає токен із префіксом Bearer.

Перегляньте свої ефективні дозволи на сервері

Задайте в WELLEY_TOKEN ваш чинний токен так, як ви зазвичай поводитеся з секретами. Цей приклад лише читає дані.

curl --fail --silent --show-error \ -H "Authorization: Bearer $WELLEY_TOKEN" \ "https://welley.social/api/v1/rbac/permissions"

Для інтеграції створіть персональний токен доступу в налаштуваннях акаунта.
Дайте йому назву та термін дії. API також приймає expiresInDays=0 для токена без збереженого терміну дії.
Обмежте, які глобальні дозволи, дозволи груп і які групи може використовувати токен.
Якщо список дозволів залишити порожнім, це поле обмежується лише вашим поточним доступом. Токен не може надати права, яких у вас немає.
Секрет токена ви побачите лише один раз. Збережіть його, перш ніж закрити результат створення.
Щоб керувати токенами, потрібен сеанс входу в акаунт. Персональний токен доступу не може створювати, показувати, копіювати чи відкликати токени.

Перевірте дозволи та область дії

Автентифікація повідомляє API, хто звертається. Дозволи ролі визначають, які операції доступні тому, хто звертається.

API повертає 401, коли захищений запит не має чинної автентифікації.
API повертає 403, коли в того, хто звертається, немає потрібного дозволу.
Назви дозволів мають вигляд Resource.Action, наприклад GroupSettings.Manage.
Для операцій із вебхуками та дозволами в певній області опустіть scope, щоб використати область сервера. Для області групи передайте TypeId групи.
Читайте опис кожної операції. Деякі кінцеві точки використовують підписи HTTP або інший протокол замість токена акаунта.

Оберіть розділ API

Довідка охоплює соціальні функції, інтеграції та адміністрування сервера. Наведені тут приклади становлять лише невелику частину API.

Акаунти й профілі

Читайте профілі, керуйте ідентичностями акаунта та користуйтеся операціями експорту або переносу акаунта.

Метод	Шлях	Операція	Доступ
GET	`/api/v1/users`	Прочитайте локальний або віддалений профіль за іменем користувача.	Публічно або з необов'язковим токеном
POST	`/api/v1/users`	Додайте ще один профіль до поточного акаунта в межах ліміту сервера.	Потрібен токен

Дописи та стрічки

Читайте стрічки та створюйте дописи. Інші операції стосуються відповідей, опитувань, реакцій, чернеток і збережених дописів.

Метод	Шлях	Операція	Доступ
GET	`/api/v1/posts`	Читайте публічні дописи як гість або персоналізовану стрічку після автентифікації.	Публічно або з необов'язковим токеном
POST	`/api/v1/posts`	Створіть допис із його вмістом і налаштуванням, хто може його бачити.	Потрібен токен

Групи та події

Створюйте інструменти для спільнот на основі груп, членства, каналів, модерації та подій.

Метод	Шлях	Операція	Доступ
POST	`/api/v1/groups`	Створіть групу з дозволами автентифікованого користувача.	Потрібен токен
GET	`/api/v1/events`	Покажіть публічні події або події, які бачить автентифікований користувач.	Публічно або з необов'язковим токеном
POST	`/api/v1/events`	Створіть подію. Для події групи потрібен GroupEvents.Create.	Потрібен токен

Розмови та сповіщення

Читайте кімнати розмов і їхні повідомлення. Читайте списки сповіщень і оновлюйте, прочитані вони чи ні.

Метод	Шлях	Операція	Доступ
GET	`/api/v1/rooms`	Покажіть кімнати поточного користувача. Щоб продовжити список, використайте nextCursor із тіла відповіді.	Потрібен токен
GET	`/api/v1/user-notifications`	Покажіть сповіщення поточного користувача.	Потрібен токен

Медіа, пошук і переклад

Завантажуйте медіа, шукайте вміст, який вам доступний, і замовляйте переклад тексту.

Метод	Шлях	Операція	Доступ
POST	`/api/v1/uploads`	Створіть запис завантаження, а потім надішліть вміст файлу через PUT на URL завантаження, який він поверне.	Потрібен токен
GET	`/api/v1/search`	Шукайте вміст, який бачить той, хто звертається, або розв’язуйте підтримувані URL.	Публічно або з необов'язковим токеном
POST	`/api/v1/translate/text`	Перекладіть текст запитаною мовою.	Потрібен токен

Вебхуки та ШІ-агенти

Підключайте зовнішні сервіси через вебхуки. Налаштовуйте ШІ-агентів через API агентів.

Метод	Шлях	Операція	Доступ
GET	`/api/v1/webhooks/events`	Отримайте список підтримуваних типів подій вебхуків.	Потрібен токен
POST	`/api/v1/webhooks`	Створіть вебхук в області сервера або групи, на яку у вас є дозвіл. Секрет підпису HTTP показується лише один раз.	Потрібен токен
GET	`/api/v1/ai-agents`	Покажіть ШІ-агентів, яких бачить той, хто звертається.	Потрібен токен

Адміністрування сервера та груп

Використовуйте API для налаштувань, скарг, модерації, керування федерацією, квот і адміністрування розгортання.

Метод	Шлях	Операція	Доступ
GET	`/api/v1/rbac/permissions`	Прочитайте ефективні дозволи для поточного користувача й області.	Потрібен токен
GET	`/api/v1/settings`	Прочитайте налаштування платформи, якщо акаунт має потрібні дозволи.	Публічно або з необов'язковим токеном

Обробка відповідей і медіа

Дотримуйтеся власної пагінації та процесу завантаження кожної операції.

Для стрічок із курсором переходьте за посиланнями пагінації, які повертає сервер. Не будуйте курсори, здогадуючись про ID.
Кімнати повертають непрозорий nextCursor у тілі відповіді. Коли продовжуєте список, залишайте ті самі фільтри.
Щоб завантажити медіа, створіть запис завантаження, а потім надішліть вміст на URL, який він поверне.
Перевірте відповіді з помилками та обмеження кожної операції. Навіть задокументована операція може потребувати ролі, конфігурації сервера або зовнішнього провайдера.