Добавить элемент в проект репозитория

POST /repos/{owner}/{repo}/projects/{project_number}/items

Описание

Метод POST добавляет элемент в указанный проект репозитория. В GitVerse проект может содержать только задачи, поэтому тип добавляемого элемента — Issue. Задача в теле запроса указывается либо идентификатором id, либо комбинацией owner/repo/number. Метод применяется для размещения задач на Kanban-доске проекта при интеграции с внешними системами управления задачами.

⚠️ Важно: учитывается приватность репозитория и проекта. Если репозиторий или проект приватный, а запрос выполняется не владельцем, соавтором или участником команды с доступом к репозиторию, возвращается ошибка 404.

Токен

Требуется токен с правами на Запись для Репозитория.

Заголовки

ПараметрОбязательныйОписание
AcceptНетТип содержимого ответа. Рекомендуется установить значение application/vnd.gitverse.object+json;version=latest
AuthorizationДаТокен доступа. Формат: Bearer <YOUR-TOKEN> или token <YOUR-TOKEN>
Content-TypeДаТип содержимого запроса: application/json

Параметры пути

В URL запроса необходимо передать следующие идентификаторы ресурса:

ПараметрТипОбязательныйОписание
ownerstringДаВладелец репозитория (логин пользователя или имя организации)
repostringДаНазвание репозитория (без расширения .git)
project_numberintegerДаНомер проекта

Тело запроса

ПараметрТипОбязательныйОписание
typestringНетТип элемента: Issue (задача) или PullRequest (сейчас не поддерживается)
idintegerНетУникальный идентификатор задачи. Можно не отправлять, если переданы owner, repo и number
ownerstringНетВладелец репозитория задачи. Можно не отправлять, если передан id
repostringНетНазвание репозитория задачи. Можно не отправлять, если передан id
numberintegerНетНомер задачи в репозитории. Можно не отправлять, если передан id

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

{
  "type": "Issue",
  "owner": "myorg",
  "repo": "backend-api",
  "number": 156
}

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

Ниже приведен пример использования curl для добавления задачи с номером 156 в проект с номером 1.

curl -X POST "https://api.gitverse.ru/repos/myorg/backend-api/projects/1/items" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Accept: application/vnd.gitverse.object+json;version=latest" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Issue",
    "owner": "myorg",
    "repo": "backend-api",
    "number": 156
  }'

Замените <YOUR-TOKEN> на ваш личный токен доступа.

Ответ при успешном выполнении (201 Created)

При успешном добавлении сервер вернет ответ с кодом 201 Created и телом в формате JSON, содержащим объект добавленного элемента проекта:

{
  "id": 5,
  "node_id": null,
  "project_url": "/repos/myorg/backend-api/projects/1",
  "content": {
    "id": 163200,
    "number": 156,
    "title": "Добавить пагинацию в список проектов",
    "state": "open",
    "user": {
      "id": 516,
      "login": "user123"
    },
    "assignee": null,
    "labels": [],
    "created_at": "2026-09-14T10:00:00Z",
    "updated_at": "2026-09-17T11:05:00Z",
    "html_url": "https://gitverse.ru/myorg/backend-api/issues/156"
  },
  "content_type": "Issue",
  "created_at": null,
  "updated_at": null,
  "archived_at": null,
  "item_url": "/repos/myorg/backend-api/projects/1/items/5",
  "fields": [
    {
      "name": "Status",
      "value": {
        "id": "7",
        "name": {
          "raw": "To Do"
        },
        "color": "BLUE"
      }
    }
  ]
}

Структура ответа

Ответ — объект ProjectItem (добавленный элемент проекта). Он содержит:

ПолеТипОписание
idintegerУникальный идентификатор элемента проекта
node_idstringГлобальный ID узла (GraphQL). В ответах GitVerse всегда null
project_urlstringAPI URL для доступа к проекту
contentobjectОбъект, которым является элемент проекта. В GitVerse всегда задача — см. граф объектов, раздел «Объект Issue»
content_typestringТип контента элемента. В GitVerse всегда Issue
created_atstring / nullВремя создания элемента. В ответах GitVerse всегда null
updated_atstring / nullВремя обновления элемента. В ответах GitVerse всегда null
archived_atstring / nullВремя архивирования элемента. В ответах GitVerse всегда null
item_urlstringAPI URL для доступа к элементу проекта
fieldsarrayПоля элемента проекта. Сейчас содержит только одно поле — статус (колонку, в которой находится задача)

Структура объекта fields (поле Status):

ПолеТипОписание
namestringНазвание поля. Сейчас всегда Status
value.idstringИдентификатор колонки (строкой)
value.name.rawstringНазвание колонки (например, To Do)
value.colorstringЦвет колонки (например, BLUE)

Примечание: поле creator (пользователь, добавивший элемент в проект) в ответах GitVerse не возвращается.

Коды ответа

Результат выполнения запроса определяется по HTTP-статусу:

КодСтатусОписание
201CreatedЭлемент успешно добавлен в проект
400Bad RequestНекорректные параметры запроса
401UnauthorizedНе передан или невалиден токен авторизации
403ForbiddenНедостаточно прав на запись в репозиторий
404Not FoundРесурс не найден либо нет доступа к нему
422Unprocessable EntityОшибка валидации
500Internal Server ErrorВнутренняя ошибка сервера GitVerse

Пример ответа с ошибкой

Пример некорректного запроса: в теле запроса не передан ни идентификатор задачи id, ни комбинация owner/repo/number.

{
  "type": "Issue"
}

Сервер вернет ответ 400 Bad Request:

{
  "message": "Bad Request",
  "documentation_url": "https://gitverse.ru/docs/developers/public-api/errors"
}

Прочие коды ошибки возвращают ответ той же структуры, например 404 Not Found:

{
  "message": "Not Found",
  "documentation_url": "https://gitverse.ru/docs/developers/public-api/errors"
}

Особенности метода

  • в проект добавляются только задачи: значение PullRequest в поле type сейчас не поддерживается;
  • задача может быть указана либо идентификатором id, либо комбинацией owner/repo/number;
  • колонка, в которой размещена задача, указана в поле Status ответа (fields). Чтобы переместить задачу в другую колонку, используйте метод PATCH /repos/{owner}/{repo}/projects/{project_number}/items/{item_id};
  • одновременно задача может принадлежать только одному проекту. Если задача уже находится в другом проекте, она перемещается в указанный проект.

Формат ответа и заголовки

Метод возвращает ответ в формате JSON. Заголовок Content-Type в ответе устанавливается в application/vnd.gitverse.object+json;version=latest.