# 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](https://gitverse.ru/docs/developers/public-api/) и
  [официальный OpenAPI 2.0](https://gitverse.ru/gitverse/rest-api-description/content/master/v1/openapi-1.7.json)
  версии 1.7.0.
- Обязательны заголовки
  `Authorization: Bearer <TOKEN>` и
  `Accept: application/vnd.gitverse.object+json;version=1`.
  Токен создается в профиле: «Настройки» → «Управление токенами»;
  [инструкция по токенам](https://gitverse.ru/docs/collaborative/authentification/tokens/)
  предлагает включить доступ к репозиториям.
- Лимит составляет 2000 запросов в час на идентификатор авторизованного
  пользователя.
  При превышении сервер отвечает `429` и передает остаток, время сброса и
  `Retry-After`; см. [официальное описание ограничений](https://gitverse.ru/docs/developers/public-api/using-public-api/rate-limits).
- Для списков используются `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](https://gitverse.ru/gitverse/rest-api-description/content/master/v1/openapi-1.7.json).

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

Токен взят из локального хранилища 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/ddementiev/dotfiles/issues)
показывает другую точку входа:

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

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

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

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

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

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

```bash
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](https://docs.gitlab.com/api/rest/) и
  [Issues API](https://docs.gitlab.com/api/issues/).
- Это не совместимая замена GitHub API. Совпадают некоторые маршруты и поля,
  но отличаются хост, MIME-тип, версия и полнота операций. Например, GitHub
  документирует `POST /repos/{owner}/{repo}/issues` и изменение задачи, а
  GitVerse для этого маршрута публикует только `GET`; см.
  [GitHub Issues API](https://docs.github.com/en/rest/issues/issues).
- Сходство с GitHub намеренное и частичное: в документации GitVerse некоторые
  дубли полей ответа прямо объясняются
  [совместимостью с GitHub API](https://gitverse.ru/docs/developers/public-api/repositories/api-post-orgs-repos).
  Это не обещание полной совместимости клиента или контракта.

## Решение для dotfiles

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

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

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

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