| GitVerse

6. `PUT /repos/{owner}/{repo}/contents/{filename}` — Создать или обновить файл

Описание

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

⚠️ Для обновления файла обязательно указывать SHA-хеш текущей версии файла (поле sha в теле запроса).

Параметры URL

Параметр	Обязательный	Описание
`owner`	Да	Владелец репозитория (пользователь или организация)
`repo`	Да	Название репозитория (без расширения `.git`)
`filename`	Да	Путь к файлу в репозитории (например, `docs/README.md`)

Параметры запроса

Данный метод не принимает параметров в строке запроса.

Тело запроса

Тело запроса обязательно и должно быть в формате JSON. Поддерживаемые поля:

Поле	Тип	Обязательный	Описание
`content`	string	Да	Содержимое файла в Base64
`message`	string	Нет	Сообщение коммита (по умолчанию: `"Update file via API"`)
`branch`	string	Нет	Целевая ветка (по умолчанию — ветка по умолчанию репозитория)
`sha`	string	Только при обновлении	SHA-хеш текущей версии файла (обязателен при обновлении)
`new_branch`	string	Нет	Если указано — создается новая ветка на основе `branch` и в нее вносится изменение
`signoff`	boolean	Нет	Добавить подпись `Signed-off-by` в коммит

При создании файла поле sha не указывается.
При обновлении — обязательно.

Пример запроса

Создать новый файл

curl -X PUT "https://api.gitverse.ru/repos/alice/my-project/contents/docs/README.md" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/vnd.gitverse.object+json;version=1" \
  -d '{
    "content": "IyBNeSBQcm9qZWN0CkhlbGxvLCB3b3JsZCE=",
    "message": "Add README",
    "branch": "main"
  }'

Обновить существующий файл

curl -X PUT "https://api.gitverse.ru/public/api/repos/alice/my-project/contents/docs/README.md" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/vnd.gitverse.object+json;version=1" \
  -d '{
    "content": "IyBNeSBQcm9qZWN0CkhlbGxvLCB1cGRhdGVkIHdvcmxkIQ==",
    "message": "Update README content",
    "branch": "main",
    "sha": "a1b2c3d4e5f67890..."
  }'

Ответ (200 OK)

Пример JSON-ответа:

{
  "content": {
    "type": "file",
    "encoding": "base64",
    "size": 35,
    "name": "README.md",
    "path": "docs/README.md",
    "content": "IyBNeSBQcm9qZWN0CkhlbGxvLCB1cGRhdGVkIHdvcmxkIQ==",
    "sha": "f9e8d7c6b5a4...",
    "url": "https://api.gitverse.ru/public/api/repos/alice/my-project/contents/docs/README.md",
    "html_url": "https://gitverse.ru/alice/my-project/blob/main/docs/README.md",
    "git_url": "https://api.gitverse.ru/public/api/repos/alice/my-project/git/blobs/f9e8d7c6b5a4...",
    "download_url": "https://gitverse.ru/alice/my-project/raw/main/docs/README.md",
    "_links": {
      "self": "https://api.gitverse.ru/public/api/repos/alice/my-project/contents/docs/README.md",
      "git": "https://api.gitverse.ru/public/api/repos/alice/my-project/git/blobs/f9e8d7c6b5a4...",
      "html": "https://gitverse.ru/alice/my-project/blob/main/docs/README.md"
    }
  },
  "commit": {
    "sha": "c1d2e3f4a5b6...",
    "html_url": "https://gitverse.ru/alice/my-project/commit/c1d2e3f4a5b6...",
    "author": {
      "name": "Alice",
      "email": "alice@example.com",
      "date": "2025-10-15T12:00:00Z"
    },
    "committer": {
      "name": "Alice",
      "email": "alice@example.com",
      "date": "2025-10-15T12:00:00Z"
    },
    "message": "Update README content"
  }
}

Формат ответа

application/vnd.gitverse.object+json;version=1

Коды ответа

Код	Статус	Описание
200	OK	Файл успешно создан или обновлен
400	Bad Request	Некорректное тело запроса, отсутствует `content` или неверный Base64
401	Unauthorized	Не передан или недействителен токен авторизации
403	Forbidden	Нет прав на запись в репозиторий
404	Not Found	Репозиторий или указанный `branch` не найдены
409	Conflict	SHA не совпадает с текущей версией файла (при обновлении)
422	Unprocessable Entity	Ошибка валидации (например, попытка создать файл с уже существующим именем без `sha`)
500	Internal Server Error	Внутренняя ошибка сервера

5. GET /repos/{owner}/{repo}/contents/{path} — получить содержимое файла или папки 7. DELETE /repos/{owner}/{repo}/contents/{filename} — удалить файл

6. PUT /repos/{owner}/{repo}/contents/{filename} — Создать или обновить файл