Contact UsGet started
© 2024 Iron Hive LLC Belgrade

Creating an entity

Written by
Updated at February 19, 2024

Use this request to create a new entity: a project or project portfolio.

The request is a unified method for creating projects and portfolios – more flexible and functional than the project creation API.

Request format

Before making a request, get permission to access the API.

To create a new entity, use an HTTP POST request. Request parameters are provided in the request body in JSON format.

POST /v2/entities/{entityType}
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID: <organization ID>

{
   "fields":
   {
      "summary": "<name>",
      "teamAccess": true
   }
}
Headers

  • Host

    Address of the node that provides the API:

    https://api.tracker.yandex.net

  • Authorization

    OAuth token in OAuth <OAuth_token> format, e.g.:

    OAuth 0c4181a7c2cf4521964a72ff********

  • X-Org-ID or X-Cloud-Org-ID

    Organization ID. You can find it out on the Tracker organizations page.

    • If a Yandex 360 for Business organization is the only one linked to Tracker, the X-Org-ID header is used.
    • If a Yandex Cloud Organization organization is the only one linked to Tracker, the X-Cloud-Org-ID header is used.
    • If both Yandex 360 for Business and Yandex Cloud Organization organizations are linked to Tracker at the same time, the X-Org-ID header and the Yandex 360 for Business organization ID are used.
Resource

Resource

Parameter Description Data type
<entity_type> New entity's type:
  • project if creating a project
  • portfolio if creating a portfolio
 String
Request parameters

Additional parameters

Parameter Description Data type
fields Additional entity fields to be included into the response. String
Request body parameters

The request body contains information required to create a new entity:

Required parameters

Parameter Description Data type
fields Object with entity settings. Object

Fields object fields

Parameter Description Data type
summary Name (required field). String
queues Queue (required for projects if the teamAccess field is not set). String
teamAccess Access (required for projects if the queues field is not set). Logical
description Description. String
author Author (user ID). Number
lead Responsible person (user ID). Number
teamUsers Members (array of user IDs). Array of numbers
clients Clients (array of user IDs). Array of numbers
followers Followers (array of user IDs). Array of numbers
start Start date in YYYY-MM-DDThh:mm:ss.sss±hhmm format. Date
end Deadline in YYYY-MM-DDThh:mm:ss.sss±hhmm format. Date
tags Tags. Array of strings
parentEntity Parent entity (portfolio) ID. Number
entityStatus Status:
  • draft: Draft
  • in_progress: In progress
  • launched: New
  • postponed: Postponed
  • at_risk: At risk
  • blocked: Blocked
  • according_to_plan: According to plan
 String

Example: Creating a project

  • An HTTP POST method is used.
  • A project named Test Project is created.
  • A queue with the TREK key is linked to the project.
POST /v2/entities/project/ HTTP/1.1
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID: <organization ID>

{
    "fields":
    {
       "summary":"Test Project",
       "queues":"TREK"
    }
}

Response format

If the request is successful, the API returns a response with code 201 Created.

The response body contains information about the new entity in JSON format.

{
   "self": "https://https://api.tracker.yandex.net/v2/entities/project/655f3be523db2132********",
   "id": "655f3be523db2132********",
   "version": 1,
   "shortId": 6,
   "entityType": "project",
   "createdBy": { "self": "https://https://api.tracker.yandex.net/v2/users/11********", "id": "11********", "display": "Full Name", "cloudUid": "ajevuhegoggfk*******", "passportUid": 11******** },
   "createdAt": "2023-11-23T11:47:49.743+0000",
   "updatedAt": "2023-11-23T11:47:49.743+0000"
}
Response parameters
Parameter Description Data type
self Address of the API resource with information about the entity. String
id Entity ID. String
version Entity version. Each change of the parameters increases the version number. Number
shortId Project or portfolio ID String
entityType Entity type. String
createdBy Block with information about the user who created the entity. Object
createdAt Entity creation date in YYYY-MM-DDThh:mm:ss.sss±hhmm format. String
updatedAt Date when the entity was last updated, in YYYY-MM-DDThh:mm:ss.sss±hhmm format. String

createdBy object fields

Parameter Description Data type
self Address of the API resource with information about the user who created the entity. String
id User ID. Number
display Displayed user name. String
cloudUid User unique ID in Yandex Cloud Organization. String
passportUid Unique ID of the user account in the Yandex 360 for Business organization and Yandex ID. String

If the request is processed incorrectly, the API returns a response with an error code:

400
One or more request parameters have an invalid value.
401
The user isn't authorized. Make sure to perform the actions described in API access.
403
Insufficient rights to perform this action. You can check what rights you have in the Tracker interface. The same rights are required to perform an action via the API and interface.
404
The requested object was not found. You may have specified an invalid object ID or key.
409
There was a conflict when editing the object. The error may be due to an invalid update version.
Previous
Projects and portfolios. Overview
Next
Getting entity parameters