Первый запрос

После OAuth-подключения передавайте access token в заголовке Authorization. Токены нельзя помещать в URL или журналы.

curl https://feylost.ru/api/v1/characters \
  -H "Authorization: Bearer <access_token>"

Ответы с пользовательскими данными имеют Cache-Control: no-store. Тело изменяющих запросов передаётся как JSON и ограничено 2 МБ.

Авторизация

API использует Authorization Code с обязательным PKCE S256 и Dynamic Client Registration. Discovery начинается с защищённого ресурса MCP и приводит клиента к OAuth-серверу Feylost.

Protected resource

/.well-known/oauth-protected-resource

Authorization server

/.well-known/oauth-authorization-server/api/auth

Audience

https://feylost.ru/mcp

Срок действия

Access token 1 час, refresh token до 30 дней

Разрешения

Пользователь видит и подтверждает каждый scope при подключении. Токен открывает только собственные данные и никогда не включает административный режим или эмуляцию пользователя.

Email, пароль, способы входа и удаление аккаунта изменяются только интерактивно на сайте. OAuth-клиент не может захватить учётную запись даже со scope account:write.

Методы API

MCP v2

Один endpoint поддерживает современный протокол MCP 2026-07-28 и stateless-совместимость со старыми клиентами. MCP умеет не только читать лист: отдельные инструменты изменяют умения, инвентарь, броню, оружие, наборы заклинаний, игровое состояние, эффекты и отдых, управляют публичной ссылкой, портретом и PDF.

Перед заполнением клиент может прочитать resources с полной документацией языка, правилами лаконичного текста и контекстом конкретного листа. Инструменты проверки компилируют механику и описания без записи, а сохраняющие операции требуют актуальную версию ресурса.

Механика

feylost://docs/mechanics-language

Описания

feylost://docs/narrative-language

Стиль

feylost://docs/authoring-style

Контекст листа

feylost://sheets/{id}/authoring-context

Версии и конфликты

Персонажи и листы содержат целочисленное поле version. Перед изменением клиент читает ресурс и отправляет полученную версию вместе с PATCH или DELETE. Если ресурс уже изменился, API отвечает HTTP 409.

Для изменения формул листа сначала вызовите GET /sheets/{id}/source, затем передайте оба CAS-маркера - version и baseSourceHash - вместе с новым source. Класс, редакция, владения, категории заклинаний и политика магии входят в атомарный проект механики; карточки сущностей и временные ресурсы игры сайт хранит отдельно.

{
  "version": 4,
  "baseSourceHash": "64 строчных hex-символа из GET",
  "source": "# @fey-project 2\n# @fey-file identity \"персонаж.fey\"\nкласс = \"Воин\"\n..."
}

JSON Patch поддерживает add, replace, remove и test, но применяется только к карточкам персонажей. Проект механики заменяется целиком через source-endpoint.

Ошибки

{
  "error": {
    "code": "validation_error",
    "message": "Проверьте заполнение полей",
    "issues": [{ "path": "name", "message": "Обязательное поле" }]
  }
}