Platform API (/v1)
Platform API — это версионируемый HTTP-интерфейс Waafir. Используйте его, чтобы читать данные вашей организации и управлять ею из собственных систем. Он охватывает вашу команду (приглашение участников, смена ролей, удаление), предоставление доступа к комнатам данных, папки, файлы, Q&A, чат и агентов комнаты данных, активность и вовлечённость по каждому контрагенту, а также мониторинг портфеля.
Это отдельный интерфейс от MCP-серверов Waafir, которые открывают ту же платформу ИИ-клиентам в виде инструментов. Оба используют для аутентификации одни и те же персональные токены доступа.
Базовый URL
Каждый эндпоинт расположен по адресу:
https://app.waafir.io/api/v1Справочник эндпоинтов перечисляет каждый из них
по полному пути, например GET /api/v1/team.
Ваш первый вызов
- Выпустите токен. В Waafir откройте Дополнения → Конфигурация и
выпустите персональный токен доступа. Для начала достаточно токена
read. Скопируйте значение, которое начинается сwaafir_pat_. Оно показывается только один раз. - Узнайте, кто вы.
GET /api/v1/sessionвозвращает личность и организацию, от имени которых действует токен. Используйте его, чтобы проверить, что токен работает, прежде чем строить на нём интеграцию:
curl -s https://app.waafir.io/api/v1/session \
-H "Authorization: Bearer $WAAFIR_TOKEN"{
"orgId": "…",
"userId": "…",
"email": "you@example.com",
"orgRole": "admin",
"authMethod": "pat",
"principalType": "user"
}401 означает, что токен отсутствует, введён с ошибкой, истёк или отозван.
Другие отказы обычно содержат машиночитаемый code, описанный на странице
кодов ошибок. У некоторых его нет, поэтому
всегда ориентируйтесь в конечном счёте на HTTP-статус.
Как устроен справочник
Страницы эндпоинтов и кодов ошибок генерируются из собственного дерева маршрутов платформы при каждой публикации этого сайта. Они не пишутся вручную. Продакшен-релиз строит их из того же коммита, что и приложение, поэтому они перечисляют маршруты, которые обслуживает этот релиз, с ограничением по роли и областью действия токена, которые требует каждый эндпоинт, и параметрами запроса, которые он принимает. Их списки ошибок — это известный минимум, а не исчерпывающий перечень: эндпоинт может возвращать коды, которые генератор не видит, поэтому обрабатывайте неперечисленные ошибки по HTTP-статусу.
Версионирование
/v1 развивается только путём добавлений в пределах своей версии. Waafir может
добавлять поля ответа и необязательные параметры запроса. В пределах /v1 он не
удаляет и не меняет тип существующего поля и не удаляет эндпоинты. Несовместимое
изменение выходит под новым префиксом версии. Пишите клиенты так, чтобы они
игнорировали незнакомые поля.
Куда двигаться дальше
- Аутентификация: токены, области действия, потолок роли и токены, ограниченные комнатами данных.
- Эндпоинты: все эндпоинты, сгруппированные по областям.
- Коды ошибок: известные отказы и что с ними делать.
- Справочник Loan API и сборник рецептов: контракт запросов и ответов для приёма данных мониторинга портфеля.