# GitVerse API — рабочие эндпоинты и питфолы (проверено 2026-09-06)

## Ключевой факт: базовый URL

- **API: `https://api.gitverse.ru`** (Gitea-совместимый: `/user/repos`, `/repos/{owner}/{repo}/...`, `/users/{login}`)
- **НЕ** `https://gitverse.ru/api/v1/...` — этот путь отдаёт HTML (Next.js SPA), а не JSON. Любой curl туда вернёт `<DOCTYPE html>`.
- API-документация (человекочитаемая, по эндпоинтам): `https://gitverse.ru/docs/developers/public-api` (страница SPA, парсить текст через curl -sL + strip тегов).

## Аутентификация

- Все токены — в `/opt/hermes/.hermes/secrets/git-tokens.env` (source): `GITVERSE_PAT`, `GITEA_TOKEN`, `GITVERSE_LOGIN`, `GITVERSE_API`, `GITEA_API`.
- `Authorization: Bearer <PAT>` (gitverse) и `Authorization: token <GITEA_TOKEN>` (gitea).
- Для создания/чтения объектов репо gitverse рекомендован Accept: `application/vnd.gitverse.object+json;version=1` (без него `/user` и `/user/repos` отдают 400).

## Создание репозитория

```bash
source /opt/hermes/.hermes/secrets/git-tokens.env
curl -s -X POST "$GITVERSE_API/user/repos" \
  -H "Authorization: Bearer $GITVERSE_PAT" \
  -H "Accept: application/vnd.gitverse.object+json;version=1" \
  -H "Content-Type: application/json" \
  -d '{"name":"repo-name","description":"...","private":true}'
```

- HTTP 201 = создан; в ответе `id`, `full_name`, `html_url`, `clone_url`, `default_branch` (у GitVerse — `master` при пустом репо).
- Поддерживаемые поля тела: `name` (обязательное), `description`, `private`, `auto_init`, `gitignores[]`, `is_template`. НЕ поддерживаются `license_template`, `has_wiki`, `has_issues` (API их игнорирует/ошибается).
- `auto_init: true` создаёт пустой README — для пуша готовой локальной истории ставить `false`.

## Питфол: реальный логин аккаунта ≠ ожидаемый

- В remote можно заложить `https://estorozhenko:<TOKEN>@gitverse.ru/estorozhenko/openspec-lab.git`, но push упадёт/remote не совпадёт, если фактический логин другой.
- Реальный владелец виден в ответе API: поле `full_name` = `<реальный-логин>/<repo>` (в нашем случае аккаунт оказался **kpa39l**, не estorozhenko).
- После создания репо: `git remote set-url origin https://<реальный-логин>:<TOKEN>@gitverse.ru/<реальный-логин>/<repo>.git`, затем `git push -u origin main`.
- Проверка перед push, если сомневаетесь: `curl -s -H "Authorization: Bearer $TOKEN" https://api.gitverse.ru/user` → `"login"` в JSON.
- GitVerse может создать дефолтную ветку `master` (пустой репо). Локально `main` — при пуше `-u origin main` ветка создастся, но дефолт останется `master`; менять в настройках репо или оставить как есть.

## Краткая справка по docs

Полезные эндпоинты (Gitea-совместимые, все под api.gitverse.ru):
- `GET /user` — текущий пользователь (login, id)
- `GET /user/repos` — список своих репозиториев
- `POST /user/repos` — создать
- `PATCH /repos/{owner}/{repo}` — обновить метаданные (в т.ч. mirror)
- `GET /repos/{owner}/{repo}` — инфо репозитория

Полная навигация по докам: страница `/docs/developers/public-api` содержит ссылки вида `/docs/developers/public-api/<category>/<api-slug>` — категории: repositories, git-database, actions, collaborators, orgs-teams, migration, user-management.