Projects, portfolios, and goals

The Entities API presents a unified set of methods for goal, project, or portfolio management with enhanced flexibility and functionality.

With this API, you can:

Additional entity parameters

The request body for managing entities and responses to requests may contain the fields object with additional entity parameters. See all allowed fields of the fields object in the table below.

To edit entity parameters, you can use the set, add, remove, and other operators. For more information, see Editing parameters.

To include additional parameters in the response body, add the fields parameter to the request address and specify one or more values.

For example, you can configure the response to include a project description and details of the checklist items.

POST https://api.tracker.yandex.net/v3/entities/project/12345/checklistItems?fields=description,checklistItems

The response body will include a fields object with the requested information.

Field

Description

Data type

Entity type

summary

Entity name

String

Project
Portfolio
Goal

description

Entity description

String

Project
Portfolio
Goal

author

Author

Object

Project
Portfolio
Goal

lead

Lead

Object

Project
Portfolio
Goal

teamUsers

Participants

Object array

Project
Portfolio
Goal

clients

Customers

Object array

Project
Portfolio
Goal

followers

Followers

Object array

Project
Portfolio
Goal

start

Start date in the format YYYY-MM-DD

String

Project
Portfolio

end

Deadline in the format YYYY-MM-DD

String

Project
Portfolio
Goal

quarter

Start and deadline quarter in the format YYYY QN

String array

Project
Portfolio

metricItems

Metrics — dashboard widgets charts. Learn more about metrics

Object array

Project
Portfolio
Goal

checklistItems

Checklist used in projects and portfolios. Learn more about checklists

Object array

Project
Portfolio

keyResultItems

List of key results in goals. Learn more about key results

Object array

Goal

progressPercentage

Goal progress value. Calculated automatically based on sub-goals and key results. For details, see Tracking progress.

The value can range from 0 to 1. If there are no sub-goals or key results, the value is null.

This parameter is read-only

Number

Goal

tags

Tags

Array of strings

Project
Portfolio
Goal

parentEntity

Details about parent entities. For a project or portfolio: "Included in the portfolio" field

Object

Project
Portfolio
Goal

teamAccess

Access settings:

  • true: Only project, portfolio, or goal participants have access.
  • false: Users who aren't members of the project, portfolio, or goal also have access.

This option doesn't apply if access settings are inherited from the parent entity. See the permissionSources parameter description.

String

Project
Portfolio
Goal

entityStatus

Status

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

Project
Portfolio
Goal

issueQueues

Queues whose issues are included in the project. Read-only parameter

Object array

Project

lastCommentUpdatedAt

Last comment date in the format YYYY-MM-DD

String

Project
Portfolio
Goal

linkedGoalsCount

Number of linked goals

Number

Project
Portfolio

linkedProjectsCount

Number of linked projects and portfolios

Number

Goal

Fields of objects that contain user data

The author, lead, teamUsers, clients, and followers entity parameters contain objects with the following 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

Fields of objects in the metricItems array

Parameter Description Data type
id Metric ID String
text Metric name String
url Link to widget String

Fields of objects in the checklistItems array

Parameter Description Data type
id Сhecklist item ID. String
text Text of the checklist item. String
textHtml Text of the checklist item in HTML format. String
checked Checklist item completion flag:
  • true: Item marked as completed.
  • false: Item not marked as completed.
 Boolean
assignee Assignee of the checklist item. Map object
deadline Deadline for the checklist item. Map object
checklistItemType Type of the checklist item. String

Fields of objects in the keyResultItems array

Parameter Description Data type
id ID of a checklist item String
text Text of a key result String
type Method used to measure the progress toward the key result:
  • value: Based on the specific value.
  • binary: Based on whether the key result was achieved.
 String
deadline Deadline of a key result Map object
progress Quantitative metrics to track progress by value Map object
achieved Indicates whether the key result was achieved:
  • true: Marked as achieved.
  • false: Not marked as achieved.
 Boolean
assignee Key result assignee Map object

deadline object fields

Parameter Description Data type
date Deadline in YYYY-MM-DDThh:mm:ss.sss±hhmm format. Date
deadlineType Deadline type:
  • date
  • quarter
 String
isExceeded Flag indicating if the deadline has passed:
  • true: Passed.
  • false: Not passed.
 Boolean

progress object fields

Parameter Description Data type
start Initial progress value of a key result Number
end Target progress value of a key result Number
current Current progress value of a key result Number

parentEntity object fields

Parameter Description Data type
primary The main portfolio (for projects and portfolios) or parent goal (for goals) Object
secondary For projects and portfolios: a list of additional portfolios
For goals, the parameter value is always empty		 Array of objects

If the request address specifies the API v2, the parentEntity object contains information only about the main portfolio or parent goal.

{% include notitle parent-entity %}

Fields of the object that contains entity data

The primary and secondary parameters contain objects with the following fields:

Parameter Description Data type
self Address of the API resource with information about the entity String
id Entity ID String
display Entity name String

issueQueues object fields

Parameter Description Data type
self Address of the API resource with information about the queue. String
id Queue ID. String
key Queue key. String
display Queue name displayed. String
Previous
Editing a local queue field
Next
Creating an entity