Розробникам

# Створюйте з Welley

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

[Відкрити актуальний Swagger UI](https://welley.social/q/swagger-ui/) [Завантажити OpenAPI JSON](https://welley.social/q/openapi?format=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, який він поверне.
-   Перевірте відповіді з помилками та обмеження кожної операції. Навіть задокументована операція може потребувати ролі, конфігурації сервера або зовнішнього провайдера.