Creating an entity

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

POST

https://api.tracker.yandex.net/v3/entities/<entity_type>

Request format

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

To create a new entity, use an HTTP POST request. In the request body, specify the parameters in JSON format.

POST /v3/entities/<entity_type>
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

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

Headers

Host: Address of the node that provides the API.
Authorization: Authorization token about these formats:
- OAuth <OAuth_token>: For authorization using the OAuth 2.0 protocol. Learn more
- Bearer <IAM_token>: For authorization using an IAM token, if a Yandex Cloud Organization organization is linked to Tracker. Learn more
X-Org-ID or X-Cloud-Org-ID: Organization ID.
- Use the X-Org-ID header if a Tracker organization is linked to Yandex 360 for Business.
- Use the X-Cloud-Org-ID header if a Tracker organization is linked to Yandex Cloud Organization.
To get the organization ID, go to Administration → Organizations and copy the value from the ID field.

Resource

Parameter	Description	Data type
<entity_type>	Entity type: project portfolio goal	String

Request parameters

Additional parameters

Parameter	Description	Data type
fields	Additional entity fields to include in 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 For more information, see Additional entity parameters.	Map object

fields object fields

Parameter	Description	Data type
summary	Name (required field)	String
queues	Queue (required for the project if the `teamAccess` field isn't specified)	String
teamAccess	Access (required for the project if the `queues` field isn't specified)	Logical
description	Description	String
markupType	Text markup type. If you use YFM markup in a comment or entity description, specify the `md` value	String
author	Author (user ID)	String
lead	Lead (user ID)	String
teamUsers	Participants (array of user IDs)	String array
clients	Customers (array of user IDs)	String array
followers	Followers (array of user IDs)	String array
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	String array
parentEntity	Parent entity data. For a project or portfolio: "Included in the portfolio" field	Object
entityStatus	Status. Acceptable status values For projects or portfolios: `draft`: New. `draft2`: Draft. `in_progress`: In progress. `according_to_plan`: As planned. `postponed`: Postponed. `at_risk`: At risk. `blocked`: Blocked. `launched`: Finished. `cancelled`: Canceled. For goals: `draft`: New. `according_to_plan`: As planned. `at_risk`: At risk. `blocked`: Blocked. `achieved`: Completed. `partially_achieved`: Partially completed. `not_achieved`: Not completed. `exceeded`: Exceeded. `cancelled`: Canceled.	String

parentEntity object fields

Parameter	Description	Data type
primary	ID of the main portfolio (for projects and portfolios) or parent goal (for goals)	String
secondary	For projects and portfolios: IDs of additional portfolios Goals don't support the `secondary` parameter.	Array of strings

If the API v2 is specified in the request address, the parentEntity parameter can contain only the ID of the main parent entity.

For example: "parentEntity": "66e2fa183*****"

Additional parameters

Parameter	Description	Data type
links	Array of objects with settings of links to other entities	Array of objects

links array object fields

Parameter

Description

Data type

relationship

Link type. For projects and portfolios:

depends on: The current entity depends on the linked one.
is dependent by: The current entity blocks the linked one.
works towards: Project link to a goal.

For goals:

parent entity: Parent goal.
child entity: Subgoal.
depends on: The current goal depends on the linked one.
is dependent by: The current goal blocks the linked one.
is supported by: Link to a project.

String

entity

ID of the linked entity.

String

Example: Creating a project

An HTTP POST method is used.
A project named Test Project is created.
The project is linked to the goal with ID 1234.

POST /v3/entities/project/ HTTP/1.1
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

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

Response format

Request executed successfully

Request failed

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://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": "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. Entity edits will be disabled if the version number reaches the threshold value of `10100` (for robots) or `11100` (for users)	Number
shortId	Goal, project, or portfolio ID in Yandex Tracker	String
entityType	Entity type	String
createdBy	Block with information about the entity creator	Map 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
fields	Block with additional entity fields	Map object

createdBy object fields

Parameter	Description	Data type
self	Address of the API resource with information about the user	String
id	User ID.	String
display	Displayed user name	String
passportUid	Unique ID of the user account in the Yandex 360 for Business organization and Yandex ID.	Number
cloudUid	Unique user ID in Yandex Cloud Organization	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 is not authorized. Make sure that actions described in the API access section are performed.

403: You are not authorized 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.

Was the article helpful?

Overview

Getting entity parameters