Разработчикам

# Создавайте с 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, который она возвращает.
-   Проверяйте ответы с ошибками и лимиты каждой операции. Даже для описанной в документации операции может понадобиться роль, конфигурация сервера или внешний провайдер.