dotfiles/docs/research/2026-07-21-gitverse-api.md

API GitVerse для задач

Проверено 21 июля 2026 года по официальной документации, спецификации OpenAPI, ответам действующего сервера и коду веб-интерфейса.

Зачем проверяли

Мы хотели понять, можно ли управлять задачами проекта dotfiles программно и со временем перенести туда часть локального процесса из .scratch. Для этого нужно было ответить на два вопроса:

1. Совместим ли GitVerse с API GitHub или GitLab либо использует свой API?
2. Можно ли через этот API создавать, менять и закрывать задачи?

Ответ

GitVerse предоставляет собственный REST API на https://api.gitverse.ru. Он похож на GitHub REST API по маршрутам и структуре части ответов, но полной совместимости GitVerse не заявляет. С GitLab API он несовместим уже на уровне маршрутов: GitLab использует /api/v4/projects/:id/issues, а GitVerse использует /repos/{owner}/{repo}/issues.

Поддержка задач сейчас неполная: публичный API поддерживает получение списка и отдельной задачи, чтение временной шкалы и меток, а также создание и изменение комментариев и реакций. В опубликованном контракте нет создания, изменения, закрытия или удаления самой задачи. Поэтому заменить им полноценное управление задачами пока нельзя.

Веб-интерфейс умеет создавать задачи, но использует для этого отдельный внутренний API и браузерную сессию. Токен Public API этот внутренний сервер не принимает.

Почему комментарии есть, а создания задачи нет

GitVerse использует общую модель обсуждений для задач и запросов на слияние. Поэтому GET /repos/{owner}/{repo}/issues/{index} возвращает любой из этих объектов, а комментарии к обоим создаются через POST /repos/{owner}/{repo}/issues/{index}/comments.

Жизненный цикл запросов на слияние вынесен в /pulls: там есть создание и изменение запроса. Для обычной задачи симметричных POST /issues и PATCH /issues/{index} в Public API нет. Наличие POST для комментария не означает, что через тот же API можно создать саму задачу.

Как проверяли

1. В официальных спецификациях OpenAPI 1.0-1.7 у /issues и /issues/{index} найден только GET. Для комментариев опубликованы методы записи, а для запросов на слияние есть отдельные методы /pulls.
2. OPTIONS для коллекции задач и /issues/1 вернул 405 с Allow: GET. Запрос списка без токена вернул 401 Unauthorized и заголовок GitVerse-Api-Version: 1.
3. Токен work-usa с правом «Репозитории: Запись» успешно прочитал репозиторий через Bearer-аутентификацию: GET /repos/ddementiev/dotfiles вернул 200. GET /user с тем же токеном вернул 403, поэтому этот маршрут не подходит для проверки токена с ограниченными правами. Basic-аутентификация вернула 401. Токен создан 20 июля 2026 года и действует до 31 декабря 2026 года.
4. Настоящий POST /repos/ddementiev/dotfiles/issues проверен с двумя телами: GitHub-подобным и тем, которое отправляет веб-интерфейс. Оба запроса вернули 400 и пустую JSON-строку. Такой же ответ получен для заведомо несуществующего пути. Ни одна тестовая задача не создалась.
5. В рабочих JavaScript-модулях GitVerse найден отдельный внутренний API веб-интерфейса и точное тело запроса создания задачи. Это наблюдение за реализацией сайта, а не публичный контракт.
6. Безопасный GET к внутреннему API с тем же Public API-токеном вернул 401 и {"message":"Wrong auth info"}. Внутренний клиент использует cookie браузерной сессии.

Контракт Public API

• Базовый адрес: https://api.gitverse.ru. Опубликован собственный контракт GitVerse Public API и официальный OpenAPI 2.0 версии 1.7.0.
• Обязательны заголовки Authorization: Bearer <TOKEN> и Accept: application/vnd.gitverse.object+json;version=1. Токен создается в профиле: «Настройки» → «Управление токенами»; инструкция по токенам предлагает включить доступ к репозиториям.
• Лимит составляет 2000 запросов в час на идентификатор авторизованного пользователя. При превышении сервер отвечает 429 и передает остаток, время сброса и Retry-After; см. официальное описание ограничений.
• Для списков используются page, per_page и заголовок ответа Link. Верхняя граница per_page в открытом контракте не указана.

Опубликованные операции с задачами

Метод	Маршрут	Назначение
GET	/repos/{owner}/{repo}/issues	Список задач и запросов на слияние; фильтры state, q, labels, milestones, created_by, assigned_by, mentioned_by, type, since, before, page, per_page
GET	/repos/{owner}/{repo}/issues/{index}	Одна задача или запрос на слияние
GET	/repos/{owner}/{repo}/issues/{index}/timeline	Комментарии и события задачи
GET	/repos/{owner}/{repo}/issues/{index}/labels	Метки задачи
GET, POST	/repos/{owner}/{repo}/issues/{index}/comments	Список и создание комментариев
GET	/repos/{owner}/{repo}/issues/comments/{id}	Один комментарий
PATCH, DELETE	/repos/{owner}/{repo}/issues/{index}/comments/{comment_id}	Изменение и удаление комментария
POST	/repos/{owner}/{repo}/issues/{index}/comments/{comment_id}/reactions	Добавление реакции
DELETE	/repos/{owner}/{repo}/issues/{index}/comments/{comment_id}/reactions/{reaction_id}	Удаление реакции

Источник таблицы: раздел paths официальной спецификации OpenAPI 1.7.

Подробности проверки создания

Токен взят из локального хранилища Git. Его значение не печаталось и не сохранялось в документе.

• GET https://api.gitverse.ru/repos/ddementiev/dotfiles с Bearer-токеном вернул 200. Это подтверждает, что Public API принимает токен и видит репозиторий.
• POST https://api.gitverse.ru/repos/ddementiev/dotfiles/issues с GitHub-подобным телом title и body вернул 400 и пустую JSON-строку.
• Повторный POST с точным форматом веб-интерфейса (title, content, issue_type, assignees, labels и attachments) вернул тот же ответ.
• Такой же 400 сервер возвращает для POST на заведомо несуществующий путь. Поэтому этот ответ выглядит как общая обработка незарегистрированного метода, а не как ошибка полей задачи.
• Ни одна тестовая задача не была создана.

Код веб-интерфейса задач показывает другую точку входа:

https://gitverse.ru/sc/sbt/api/v1/repos/{owner}/{repo}/issues

Форма отправляет туда POST с телом следующего вида:

{
  "title": "...",
  "content": "...",
  "issue_type": 1,
  "assignees": [],
  "labels": [],
  "attachments": []
}

Внутренний клиент передает cookie браузерной сессии. Проверочный GET к этому адресу с токеном work-usa вернул 401 и {"message":"Wrong auth info"}. Эта проверка не запускала внутренний POST и не могла создать задачу. Она показала, что токен Public API не подходит для клиента веб-интерфейса.

Как повторить безопасные проверки

Токен должен находиться в переменной GITVERSE_TOKEN. Команды ниже только читают данные и не создают задач.

curl -sS -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $GITVERSE_TOKEN" \
  -H 'Accept: application/vnd.gitverse.object+json;version=1' \
  https://api.gitverse.ru/repos/ddementiev/dotfiles

curl -sS -X OPTIONS -D - -o /dev/null \
  -H "Authorization: Bearer $GITVERSE_TOKEN" \
  -H 'Accept: application/vnd.gitverse.object+json;version=1' \
  https://api.gitverse.ru/repos/ddementiev/dotfiles/issues

Ожидаются 200 для первого запроса и 405 с Allow: GET для второго. Повторять POST в основном репозитории не следует: если GitVerse добавит метод, проверка создаст настоящую задачу. Для новой проверки нужен временный репозиторий.

Совместимость

• Это не GitLab API. У GitLab базовый путь начинается с /api/v4, а создание задачи выполняется через POST /projects/:id/issues; см. GitLab REST API и Issues API.
• Это не совместимая замена GitHub API. Совпадают некоторые маршруты и поля, но отличаются хост, MIME-тип, версия и полнота операций. Например, GitHub документирует POST /repos/{owner}/{repo}/issues и изменение задачи, а GitVerse для этого маршрута публикует только GET; см. GitHub Issues API.
• Сходство с GitHub намеренное и частичное: в документации GitVerse некоторые дубли полей ответа прямо объясняются совместимостью с GitHub API. Это не обещание полной совместимости клиента или контракта.

Решение для dotfiles

• Оставить .scratch главным хранилищем задач текущей ветки.
• Public API можно использовать для чтения задач. Операции с комментариями опубликованы, но перед постоянным использованием их стоит отдельно проверить на тестовой задаче.
• Не строить интеграцию на внутреннем /sc/sbt/api/v1. Он требует браузерную сессию, не документирован и может измениться без предупреждения.
• Вернуться к переносу .scratch в GitVerse после появления официальных методов создания и изменения задач.

Неизвестно и требует уточнения у GitVerse

• Есть ли закрытая бета или планируемый публичный POST/PATCH для задач.
• Какие права будут нужны для создания задач, если метод появится. Токен с правом «Репозитории: Запись» успешно читает репозиторий, но проверить еще не опубликованную операцию невозможно.
• Поддержит ли GitVerse обычные GitHub-клиенты при замене базового адреса. Официального заявления об этом не найдено, а различия контракта уже исключают надежную совместимость.
• GitVerse MCP использует тот же токен и собственный адрес https://mcp.gitverse.ru, но официальный список его сущностей на 21 июля 2026 года не включает задачи. По документации это не обход отсутствующих операций REST API.

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