Создать сущность

Запрос позволяет создать новую сущность — цель, проект или портфель проектов.

POST

https://api.tracker.yandex.net/v3/entities/<тип_сущности>

Формат запроса

Перед выполнением запроса получите доступ к API.

Чтобы создать новую сущность, используйте HTTP-запрос с методом POST. В теле запроса укажите параметры в формате JSON.

POST /v3/entities/<тип_сущности>
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
   "fields": {
      "summary": "<название>",
      "lead": "username",
      "end": "2025-12-01"
      ...
   }
}
Заголовки
  • Host: адрес узла, предоставляющего API.

  • Authorization: токен для авторизации в одном из форматов:

    • OAuth <OAuth-токен> при авторизации по протоколу OAuth 2.0. Читать подробнее

    • Bearer <IAM-токен> при авторизации с помощью IAM-токена — если к Трекеру привязана организация Yandex Cloud Organization. Читать подробнее

  • X-Org-ID или X-Cloud-Org-ID: идентификатор организации.

    • Используйте заголовок X-Org-ID, если к Трекеру привязана организация Яндекс 360 для бизнеса.

    • Используйте заголовок X-Cloud-Org-ID, если к Трекеру привязана организация Yandex Cloud Organization.

    Чтобы узнать идентификатор организации, перейдите на страницу АдминистрированиеОрганизации и скопируйте значение поля идентификатор.

Ресурс
Параметр Описание Тип данных
<тип_сущности> Тип сущности:
  • project — проект;
  • portfolio — портфель;
  • goal — цель
Строка
Параметры запроса

Дополнительные параметры

Параметр Описание Тип данных
fields Дополнительные поля сущности, которые будут включены в ответ. Строка
Параметры тела запроса

Тело запроса содержит информацию, необходимую для создания новой сущности:

Обязательные параметры

Параметр Описание Тип данных
fields Объект с настройками сущности. Подробнее в разделе Дополнительные параметры сущности Объект

Поля объекта fields

Параметр

Описание

Тип данных

summary

Название (обязательное поле)

Строка

teamAccess

Настройки доступа:

  • true— доступ только для участников проекта, портфеля или цели.
  • false — доступ имеют другие пользователи, кроме участников проекта, портфеля или цели.

О настройке прав доступа для пользователей и групп см. в разделе Изменить настройки доступа сущности.

Логический

description

Описание

Строка

markupType

Тип отображаемой в тексте разметки. Если вы используете в тексте комментария или описания сущности разметку YFM, укажите значение md

Строка

author

Автор (идентификатор пользователя)

Строка

lead

Ответственный (идентификатор пользователя)

Строка

teamUsers

Участники (массив идентификаторов пользователей)

Массив строк

clients

Заказчики (массив идентификаторов пользователей)

Массив строк

followers

Наблюдатели (массив идентификаторов пользователей)

Массив строк

start

Дата начала в формате YYYY-MM-DDThh:mm:ss.sss±hhmm

Дата

end

Дедлайн в формате YYYY-MM-DDThh:mm:ss.sss±hhmm

Дата

tags

Теги

Массив строк

parentEntity

Данные о родительских сущностях. Для проекта и портфеля — поле «Входит в портфель»

Объект

entityStatus

Статус.

Допустимые значения статуса

Для проекта или портфеля:

  • draft — Новый;
  • draft2 — Черновик;
  • in_progress — В работе;
  • according_to_plan — По плану;
  • postponed — Отложен;
  • at_risk — Есть риски;
  • blocked — Заблокирован;
  • launched — Завершен;
  • cancelled — Отменен.

Для цели:

  • draft — Новая;
  • according_to_plan — По плану;
  • at_risk — Есть риски;
  • blocked — Заблокирована;
  • achieved — Достигнута;
  • partially_achieved — Частично достигнута;
  • not_achieved — Не достигнута;
  • exceeded — Превышена;
  • cancelled — Отменена.

Строка

Поля объекта parentEntity

Параметр Описание Тип данных
primary Идентификатор основного портфеля (для проектов и портфелей) или родительской цели (для целей) Строка
secondary Для проектов и портфелей — идентификаторы дополнительных портфелей
Для целей параметр secondary не поддерживается
Массив строк

Если в адресе запроса указана версия API v2, параметр parentEntity может содержать только идентификатор основной родительской сущности.

Например: "parentEntity": "66e2fa183*****"

Дополнительные параметры

Параметр Описание Тип данных
links Массив объектов с настройками связей с другими сущностями. Массив объектов

Поля объектов массива links

Параметр

Описание

Тип данных

relationship

Тип связи. Для проектов и портфелей:

  • depends on — текущая сущность зависит от связанной
  • is dependent by — текущая сущность блокирует связанную
  • works towards — связь проекта с целью

Для цели:

  • parent entity — родительская цель
  • child entity — подцель
  • depends on — текущая цель зависит от связанной
  • is dependent by — текущая цель блокирует связанную
  • is supported by — связь с проектом

Строка

entity

Идентификатор связанной сущности.

Строка

Пример: Создать проект

  • Используется HTTP-метод POST.
  • Создается проект с названием «Test Project».
  • Проект связан с целью с идентификатором 1234.
POST /v3/entities/project/ HTTP/1.1
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
    "fields": {
       "summary":"Test Project"
    },
   "links": [
     {
       "relationship": "works towards", 
       "entity": 1234
     }
   ]
}

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

В случае успешного выполнения запроса API возвращает ответ с кодом 201 Created.

Тело ответа содержит информацию о созданной сущности в формате JSON.

{
   "self": "https://api.tracker.yandex.net/v3/entities/project/655f3be523db2132********",
   "id": "655f3be523db2132********",
   "version": 1,
   "shortId": 6,
   "entityType": "project",
   "createdBy": {
       "self": "https://api.tracker.yandex.net/v3/users/11********",
       "id": "11********",
       "display": "Имя Фамилия",
       "cloudUid": "ajevuhegoggfk*******", 
       "passportUid": 11********
   },
   "createdAt": "2023-11-23T11:47:49.743+0000",
   "updatedAt": "2023-11-23T11:47:49.743+0000"
}
Параметры ответа
Параметр Описание Тип данных
self Адрес ресурса API, который содержит информацию о сущности Строка
id Идентификатор сущности Строка
version Версия сущности. Каждое изменение параметров увеличивает номер версии.
Редактирование сущности будет заблокировано, если версия достигнет предельного значения: для роботов 10100, для пользователей 11100
Число
shortId Числовой идентификатор сущности Число
entityType Тип сущности Строка
createdBy Блок с информацией о создателе сущности Объект
createdAt Дата создания сущности в формате YYYY-MM-DDThh:mm:ss.sss±hhmm Строка
updatedAt Дата последнего обновления сущности в формате YYYY-MM-DDThh:mm:ss.sss±hhmm Строка
fields Блок с дополнительными полями сущности Объект

Поля объекта createdBy

Параметр Описание Тип данных
self Адрес ресурса API, который содержит информацию о пользователе. Строка
id Идентификатор пользователя. Строка
display Отображаемое имя пользователя. Строка
passportUid Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID. Число
cloudUid Уникальный идентификатор пользователя в Yandex Cloud Organization. Строка

Если запрос не был успешно обработан, API возвращает ответ с кодом ошибки:

400
Один или несколько параметров запроса имеют недопустимое значение.
401
Пользователь не авторизован. Проверьте, были ли выполнены действия, описанные в разделе Доступ к API.
403
У вас не хватает прав на выполнение этого действия. Наличие прав можно перепроверить в интерфейсе Трекера — для выполнения действия при помощи API и через интерфейс требуются одинаковые права.
404
Запрошенный объект не был найден. Возможно, вы указали неверное значение идентификатора или ключа объекта.
409
При редактировании объекта возник конфликт. Возможно, ошибка возникла из-за неправильно указанной версии изменений.