Skip to content

Tracker SDK

Examples use a client built as tracker = TrackerClient(oauth_token="…", organization_id="…").

TrackerClient

TrackerClient(*, oauth_token: str | None = None, auth: Auth | None = None, organization_id: str | None = None, cloud_organization_id: str | None = None, http: HTTPConfig | None = None, transport: BaseTransport | None = None, before_send: BeforeSend | None = None, guard: Guard | None = None)

Bases: DomainClient

Holds the per-resource tracker clients, all sharing one httpx2 core session.

Examples:

>>> tracker.me.get().login
'alice'

probe

probe() -> None

One cheap authenticated read: the current user.

me

MeClient

MeClient(*, session: SyncSession)

Bases: Resource

The authenticated Tracker user.

get

get() -> Me

GET /myself → the authenticated Me (a safe auth probe).

Returns:

Type Description
Me

The authenticated user.

Examples:

>>> tracker.me.get().login
'alice'

issues

IssuesClient

IssuesClient(*, session: SyncSession)

Bases: Resource

Get, search (paginated), count, create, update, move and suggest Tracker issues.

get

get(issue_key: str, *, expand: str | None = None, fields: str | None = None) -> Issue

GET /issues/{key} → a single Issue.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
expand str | None

The extra blocks to include: transitions, attachments, comments.

None
fields str | None

The comma-separated issue fields to include in the reply.

None

Returns:

Type Description
Issue

The issue.

Examples:

>>> tracker.issues.get("DE-7").summary
'Fix the login page'

search

search(body: IssueSearch, *, limit: int | None = None, next: str | None = None, expand: str | None = None, scroll_type: str | None = None, per_scroll: int | None = None, scroll_ttl_millis: int | None = None) -> Listing[Issue]

POST /issues/_search → every matching issue, page by page, at most limit.

body is {"filter": …} or {"query": …}. limit=None fetches every page (up to Tracker's 10 000 results). scroll_type reads the results by scrolling instead, which has no such cap. A token of a scroll works once: used again, it gives the portion after.

Parameters:

Name Type Description Default
body IssueSearch

The search body, {"filter": …} or {"query": …}.

required
limit int | None

The most issues to return; None fetches every page.

None
next str | None

What an earlier call returned as next. The token carries its listing; give what is required again, and nothing else but the limit.

None
expand str | None

The extra blocks to include: transitions, attachments, comments.

None
scroll_type str | None

sorted (the order of the search) or unsorted to scroll through the results instead of paging by number.

None
per_scroll int | None

The issues a scroll page holds (1000 at most; the API's default is 100).

None
scroll_ttl_millis int | None

How long the scroll stays open between requests, in milliseconds.

None

Returns:

Type Description
Listing[Issue]

The matching issues.

Raises:

Type Description
YandexInvalidRequestError

If limit is below 1.

Examples:

>>> from ycli.yandex.tracker.issues.models import IssueSearch
>>> found = tracker.issues.search(
...     IssueSearch.model_validate({"filter": {"queue": "DE", "status": "open"}}),
...     limit=500,
... )
>>> found.collect().items[0].key
'DE-7'

count

count(body: IssueSearch) -> int

POST /issues/_count → the number of matching issues.

Parameters:

Name Type Description Default
body IssueSearch

The search body, {"filter": …} or {"query": …}.

required

Returns:

Type Description
int

The number of matching issues.

create

create(body: IssueCreate, *, notify: bool | None = None) -> Issue

POST /issues/ — create from a ready body; returns the created Issue.

Parameters:

Name Type Description Default
body IssueCreate

The issue fields.

required
notify bool | None

Whether to notify the users in the issues' fields; None leaves the API's default (it notifies).

None

Returns:

Type Description
Issue

The created issue.

update

update(issue_key: str, body: IssueUpdate) -> Issue

PATCH /issues/{key} — update fields; returns the updated Issue.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
body IssueUpdate

The fields to change.

required

Returns:

Type Description
Issue

The updated issue.

move

move(issue_key: str, queue: str, *, expand: str | None = None, initial_status: bool | None = None, move_all_fields: bool | None = None, notify: bool | None = None, notify_author: bool | None = None) -> Issue

POST /issues/{key}/_move?queue=<key> — returns the moved Issue (new key).

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
queue str

The key of the queue to move the issue to.

required
expand str | None

The extra blocks to include: attachments, comments, workflow, transitions.

None
initial_status bool | None

Whether to reset the status to the new queue's initial one; needed when the queues have different workflows.

None
move_all_fields bool | None

Whether to keep the versions, components and projects the new queue also has; the API clears them by default.

None
notify bool | None

Whether to notify the users in the issues' fields; None leaves the API's default (it notifies).

None
notify_author bool | None

Whether to notify the author of the change; None leaves the API's default (it does not).

None

Returns:

Type Description
Issue

The moved issue.

suggest

suggest(text: str, *, queue: str | None = None, full: bool | None = None, fields: str | None = None, expand: str | None = None, embed: str | None = None) -> ItemList[Issue]

GET /issues/_suggest?input=<text> → issues whose summary contains text.

Parameters:

Name Type Description Default
text str

The text to look for in issue summaries.

required
queue str | None

The key of the queue to search in.

None
full bool | None

Whether to return each issue in full; fields, expand and embed need it.

None
fields str | None

The comma-separated issue fields to include (with full).

None
expand str | None

The extra blocks to include (with full).

None
embed str | None

The blocks named in expand to return in more detail (with full).

None

Returns:

Type Description
ItemList[Issue]

The matching issues.

scroll_clear

scroll_clear(next: str) -> None

Release the scroll a search goes on by, before it expires (POST …/scroll/_clear).

The next of a search by a scroll holds the scroll's id and the scroll's own token, which is all it takes; after it the token goes on nowhere. That token is of no use without the caller's credentials, and dies with the scroll.

Parameters:

Name Type Description Default
next str

What :meth:search by a scroll returned as next.

required

Raises:

Type Description
YandexInvalidRequestError

The token is of anything but a scroll: there is nothing to release.

update_bulk

update_bulk(body: BulkUpdate, *, notify: bool | None = None) -> BulkChange

POST /bulkchange/_update — mass-edit issues. Returns the started BulkChange.

Parameters:

Name Type Description Default
body BulkUpdate

The request body: the issues to change and the field values to set.

required
notify bool | None

Whether to notify the users in the issues' fields; None leaves the API's default (it notifies).

None

Returns:

Type Description
BulkChange

The started bulk change.

Examples:

>>> from ycli.yandex.tracker.bulk.models import BulkUpdate
>>> tracker.issues.update_bulk(
...     BulkUpdate.model_validate(
...         {"issues": ["DE-1", "DE-2"], "values": {"priority": "minor"}}
...     )
... ).status
'CREATED'

move_bulk

move_bulk(body: BulkMove, *, notify: bool | None = None) -> BulkChange

POST /bulkchange/_move — mass-move issues to another queue. Returns a BulkChange.

Parameters:

Name Type Description Default
body BulkMove

The request body: the target queue and the issues to move.

required
notify bool | None

Whether to notify the users in the issues' fields; None leaves the API's default (it notifies).

None

Returns:

Type Description
BulkChange

The started bulk change.

Examples:

>>> from ycli.yandex.tracker.bulk.models import BulkMove
>>> tracker.issues.move_bulk(
...     BulkMove.model_validate({"queue": "CHECK", "issues": ["DE-3"]})
... ).id
'2cd'

transition_bulk

transition_bulk(body: BulkTransition, *, notify: bool | None = None) -> BulkChange

POST /bulkchange/_transition — mass status transition. Returns a BulkChange.

Parameters:

Name Type Description Default
body BulkTransition

The request body: the transition to run and the issues to run it on.

required
notify bool | None

Whether to notify the users in the issues' fields; None leaves the API's default (it notifies).

None

Returns:

Type Description
BulkChange

The started bulk change.

Examples:

>>> from ycli.yandex.tracker.bulk.models import BulkTransition
>>> tracker.issues.transition_bulk(
...     BulkTransition.model_validate({"transition": "close", "issues": ["DE-4"]})
... ).status
'CREATED'

import_

import_(body: ImportTask) -> Issue

POST /issues/_import — import an issue preserving its history. Returns the Issue.

Parameters:

Name Type Description Default
body ImportTask

The issue fields, including the source createdAt and createdBy.

required

Returns:

Type Description
Issue

The imported issue.

Examples:

>>> from ycli.yandex.tracker.issues.models import ImportTask
>>> tracker.issues.import_(
...     ImportTask.model_validate(
...         {
...             "queue": "TEST",
...             "summary": "Old task",
...             "createdAt": "2017-08-29T12:34:41.740+0000",
...             "createdBy": "11",
...             "key": "TEST-41",
...         }
...     )
... ).key
'TEST-41'

comments

CommentsClient

CommentsClient(*, session: SyncSession)

Bases: Resource

List (relative-paginated), get, add, update, delete and react to an issue's comments.

list

list(issue_key: str, *, limit: int | None = None, next: str | None = None, expand: str | None = None) -> Listing[Comment]

All comments on an issue, draining the id=<last comment id> relative cursor.

GET /issues/{key}/comments returns one page at a time; each next page repeats with id=<id of the last comment seen> until a page comes back empty. Capped at limit (None = every comment); a small cap narrows the page to limit rows.

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
limit int | None

The most comments to return; None returns every comment.

None
next str | None

What an earlier call returned as next. The token carries its listing; give what is required again, and nothing else but the limit.

None
expand str | None

The extra blocks to include: attachments, html or all.

None

Returns:

Type Description
Listing[Comment]

The issue's comments.

Examples:

>>> [comment.text for comment in tracker.comments.list("DE-11", limit=500)]
['first', 'second', 'third']

get

get(issue_key: str, comment_id: int | str, *, expand: str | None = None) -> Comment

GET /issues/{key}/comments/{comment_id} — one comment. Returns it.

comment_id is the numeric id or the string longId. expand adds attachments, html or all extra fields.

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
comment_id int | str

The comment's numeric id or string longId.

required
expand str | None

The extra fields to include (attachments, html or all).

None

Returns:

Type Description
Comment

The comment.

Examples:

>>> tracker.comments.get("DE-5", 9001, expand="attachments,html").text_html
'<p>My <strong>first</strong> comment</p>'

create

create(issue_key: str, body: CommentCreate) -> Comment

POST /issues/{key}/comments/ — add a comment. Returns it.

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
body CommentCreate

The new comment: its text and optional summonees and attachment ids.

required

Returns:

Type Description
Comment

The created comment.

Examples:

>>> from ycli.yandex.tracker.models import CommentCreate
>>> tracker.comments.create(
...     "DE-14", CommentCreate.model_validate({"text": "Готово ✅"})
... ).id
141

update

update(issue_key: str, comment_id: int | str, body: CommentUpdate) -> Comment

PATCH /issues/{key}/comments/{comment_id} — edit a comment. Returns it.

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
comment_id int | str

The comment's numeric id or string longId.

required
body CommentUpdate

The comment fields to change.

required

Returns:

Type Description
Comment

The updated comment.

Examples:

>>> from ycli.yandex.tracker.comments.models import CommentUpdate
>>> tracker.comments.update(
...     "DE-16", "161", CommentUpdate.model_validate({"text": "fixed typo"})
... ).text
'fixed typo'

delete

delete(issue_key: str, comment_id: int | str) -> None

Delete a comment (DELETE …/comments/{id} → 204). Raises on non-2xx.

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
comment_id int | str

The comment's id.

required

Examples:

>>> tracker.comments.delete("DE-17", "171")

reactions_create

reactions_create(issue_key: str, comment_id: int | str, name: str) -> Comment

POST …/comments/{comment_id}/reactions/{name} — add a reaction. Returns the comment.

name is an uppercase reaction key (LIKE, DISLIKE, HEART, ROCKET, FIRE, …).

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
comment_id int | str

The comment's numeric id or string longId.

required
name str

The reaction key.

required

Returns:

Type Description
Comment

The comment the reaction was added to.

Examples:

>>> tracker.comments.reactions_create("DE-18", "181", "HEART").id
181

import_

import_(issue_key: str, body: ImportComment) -> Comment

POST /issues/{issue_key}/comments/_import — import a comment; returns Comment.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
body ImportComment

The comment fields, including the source createdAt and createdBy.

required

Returns:

Type Description
Comment

The imported comment.

Examples:

>>> from ycli.yandex.tracker.comments.models import ImportComment
>>> tracker.comments.import_(
...     "TEST-2",
...     ImportComment.model_validate(
...         {
...             "text": "Old comment",
...             "createdAt": "2019-02-03T04:05:06.000+0000",
...             "createdBy": "13",
...         }
...     ),
... ).text
'Old comment'

LinksClient

LinksClient(*, session: SyncSession)

Bases: Resource

List, search (paged), add and delete the links between issues.

list

list(issue_key: str) -> ItemList[Link]

GET /issues/{key}/links → link listing.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required

Returns:

Type Description
ItemList[Link]

The issue's links.

Examples:

>>> tracker.links.list("DE-41").root[0].object_key
'DE-40'

list_filtered

list_filtered(issue_key: str, *, link_types: Sequence[str] | None = None, fields: Sequence[str] | None = None, limit: int | None = None, next: str | None = None) -> Listing[Link]

POST /issues/{key}/links/_list (a read) → links, paged by page/perPage.

link_types keeps only links of these relationships and fields picks the fields to return. Despite the docs calling them type ids, the API takes the relationship phrases of :meth:create (relates, depends on, is subtask for, has epic, …) and answers 400 to a type id such as subtask. Capped at limit (None = every link).

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
link_types Sequence[str] | None

Keep only links of these relationships.

None
fields Sequence[str] | None

The fields to return for each link.

None
limit int | None

The most links to return; None returns every link.

None
next str | None

What an earlier call returned as next. The token carries its listing; give what is required again, and nothing else but the limit.

None

Returns:

Type Description
Listing[Link]

The matching links.

Examples:

>>> found = tracker.links.list_filtered(
...     "DE-44", link_types=["relates", "subtask"], fields=["id", "type"]
... )
>>> [link.id for link in found]
[441, 442]

create

create(issue_key: str, body: LinkCreate) -> Link

POST /issues/{key}/links — link two issues. Returns the link.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
body LinkCreate

The link's relationship and the other issue.

required

Returns:

Type Description
Link

The created link.

Examples:

>>> from ycli.yandex.tracker.links.models import LinkCreate
>>> tracker.links.create(
...     "DE-42",
...     LinkCreate.model_validate(
...         {"relationship": "is dependent by", "issue": "OPS-9"}
...     ),
... ).object_key
'OPS-9'

delete

delete(issue_key: str, link_id: str) -> None

Delete a link (DELETE …/links/{link_id} → 204). Raises on non-2xx.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
link_id str

The link's id.

required

Examples:

>>> tracker.links.delete("DE-43", "431")

import_

import_(issue_key: str, body: ImportLink) -> Link

POST /issues/{issue_key}/links/_import — import an issue link. Returns the Link.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
body ImportLink

The link fields, including the source createdAt and createdBy.

required

Returns:

Type Description
Link

The imported link.

Examples:

>>> from ycli.yandex.tracker.links.models import ImportLink
>>> tracker.links.import_(
...     "TEST-3",
...     ImportLink.model_validate(
...         {
...             "relationship": "depends on",
...             "issue": "TEST-4",
...             "createdAt": "2020-03-04T05:06:07.000+0000",
...             "createdBy": "14",
...         }
...     ),
... ).object.key
'TEST-4'

transitions

TransitionsClient

TransitionsClient(*, session: SyncSession)

Bases: Resource

List an issue's workflow transitions and execute one.

list

list(issue_key: str) -> ItemList[Transition]

GET /issues/{key}/transitions → available transitions.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required

Returns:

Type Description
ItemList[Transition]

The transitions available for the issue.

Examples:

>>> tracker.transitions.list("DE-51").root[0].id
'close'

execute

execute(issue_key: str, transition_id: str, body: TransitionExecute) -> ItemList[Transition]

POST /issues/{key}/transitions/{id}/_execute → available transitions after move.

Returns the transitions available for the issue in its new status, parsed as a ItemList[Transition].

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
transition_id str

The id of the transition to execute.

required
body TransitionExecute

The transition's fields, such as comment or resolution.

required

Returns:

Type Description
ItemList[Transition]

The transitions available after the move.

Examples:

>>> from ycli.yandex.tracker.transitions.models import TransitionExecute
>>> result = tracker.transitions.execute(
...     "DE-52",
...     "close",
...     TransitionExecute.model_validate({"comment": "done", "resolution": "fixed"}),
... )
>>> result.root[0].id
'reopen'

worklog

WorklogClient

WorklogClient(*, session: SyncSession)

Bases: Resource

An issue's worklog (relative-paginated) and its writes; org-wide search and listing.

list

list(issue_key: str, *, limit: int | None = None, next: str | None = None) -> Listing[Worklog]

All worklog entries on an issue, draining the id=<last record id> cursor.

GET /issues/{key}/worklog sorts by ascending record id and pages relatively: each next page repeats with id=<id of the last record seen> until a page comes back empty. Capped at limit (None = every entry); a small cap narrows the page to limit rows.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
limit int | None

The most entries to return; None returns every entry.

None
next str | None

What an earlier call returned as next. The token carries its listing; give what is required again, and nothing else but the limit.

None

Returns:

Type Description
Listing[Worklog]

The issue's worklog entries, ascending by record id.

Examples:

>>> [entry.duration for entry in tracker.worklog.list("DE-61", limit=500)]
['PT1H', 'PT2H', 'PT3H']

search

search(body: WorklogSearch) -> ItemList[Worklog]

POST /worklog/_search → org-wide worklog entries matching the body filter.

body is {"createdBy": …, "createdAt": {"from": …, "to": …}} (all optional).

Parameters:

Name Type Description Default
body WorklogSearch

The filter on createdBy and createdAt.

required

Returns:

Type Description
ItemList[Worklog]

The matching worklog entries.

Examples:

>>> from ycli.yandex.tracker.worklog.models import WorklogSearch
>>> found = tracker.worklog.search(
...     WorklogSearch.model_validate(
...         {
...             "createdBy": "veikus",
...             "createdAt": {
...                 "from": "2018-06-06T00:00:00",
...                 "to": "2018-06-07T00:00:00",
...             },
...         }
...     )
... )
>>> found.root[0].duration
'PT2H'

list_global

list_global(created_by: str | None = None, created_from: str | None = None, created_to: str | None = None) -> ItemList[Worklog]

GET /worklog?createdBy=…&createdAt=from:…&createdAt=to:… → org-wide worklog.

Distinct from :meth:list, which is scoped to a single issue.

Parameters:

Name Type Description Default
created_by str | None

Only entries created by this user.

None
created_from str | None

Only entries created at or after this time.

None
created_to str | None

Only entries created at or before this time.

None

Returns:

Type Description
ItemList[Worklog]

The organisation's matching worklog entries.

Examples:

>>> tracker.worklog.list_global(
...     created_by="alice", created_from="2019-01-01", created_to="2019-02-01"
... ).root[0].duration
'P3W'

create

create(issue_key: str, body: WorklogCreate) -> Worklog

POST /issues/{key}/worklog — log time spent. Returns the created entry.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
body WorklogCreate

The entry's duration, and optionally start and comment.

required

Returns:

Type Description
Worklog

The created entry.

Examples:

>>> from ycli.yandex.tracker.worklog.models import WorklogCreate
>>> tracker.worklog.create(
...     "DE-66",
...     WorklogCreate.model_validate(
...         {"duration": "PT2H", "start": "2021-03-04T10:00:00.000+0300"}
...     ),
... ).duration
'PT2H'

update

update(issue_key: str, record_id: int | str, body: WorklogUpdate) -> Worklog

PATCH /issues/{key}/worklog/{record_id} — edit an entry. Returns it.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
record_id int | str

The entry's id.

required
body WorklogUpdate

The fields to change.

required

Returns:

Type Description
Worklog

The edited entry.

Examples:

>>> from ycli.yandex.tracker.worklog.models import WorklogUpdate
>>> tracker.worklog.update(
...     "DE-67", "671", WorklogUpdate.model_validate({"duration": "PT45M"})
... ).duration
'PT45M'

delete

delete(issue_key: str, record_id: str) -> None

Delete a worklog entry (DELETE …/worklog/{id} → 204). Raises on non-2xx.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
record_id str

The entry's id.

required

Examples:

>>> tracker.worklog.delete("DE-68", "681")

import_

import_(issue_key: str, body: ImportWorklog) -> ItemList[Worklog]

POST /issues/{issue_key}/worklogs/_import — import a worklog (note plural path).

Returns a ItemList[Worklog] — the live endpoint answers with a JSON array of the created worklog record(s), not a single object.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
body ImportWorklog

The worklog fields, including the source createdAt and createdBy.

required

Returns:

Type Description
ItemList[Worklog]

The created worklog record(s).

Examples:

>>> from ycli.yandex.tracker.worklog.models import ImportWorklog
>>> tracker.worklog.import_(
...     "TEST-5",
...     ImportWorklog.model_validate(
...         {
...             "duration": "PT2H",
...             "createdAt": "2021-04-05T06:07:08.000+0000",
...             "createdBy": "15",
...             "start": "2021-04-05T09:00:00.000+0000",
...         }
...     ),
... ).root[0].duration
'PT2H'

changelog

ChangelogClient

ChangelogClient(*, session: SyncSession)

Bases: Resource

The change history of an issue (relative-paginated).

list

list(issue_key: str, *, limit: int | None = None, next: str | None = None, field: str | None = None, change_type: str | None = None, sort: str | None = None) -> Listing[ChangelogEntry]

All changelog events on an issue, draining the id=<last change id> cursor.

GET /issues/{key}/changelog returns one page at a time; each next page repeats with id=<id of the last change seen> until a page comes back empty. Capped at limit (None = the full history); a small cap narrows the page to limit rows.

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
limit int | None

The most events to return; None returns the full history.

None
next str | None

What an earlier call returned as next. The token carries its listing; give what is required again, and nothing else but the limit.

None
field str | None

Keep the changes of this field, e.g. status or checklistItems.

None
change_type str | None

Keep the changes of this type, e.g. IssueWorkflow.

None
sort str | None

The order of the changes: asc or desc.

None

Returns:

Type Description
Listing[ChangelogEntry]

The changelog events.

Examples:

>>> [change.id for change in tracker.changelog.list("DE-21", limit=500)]
['ch1', 'ch2', 'ch3']

checklists

ChecklistsClient

ChecklistsClient(*, session: SyncSession)

Bases: Resource

Get, add, update and delete an issue's checklist items, or clear the whole checklist.

list

list(issue_key: str) -> ItemList[ChecklistItem]

GET /issues/{key}/checklistItems → the issue's checklist items.

Parameters:

Name Type Description Default
issue_key str

The issue key.

required

Returns:

Type Description
ItemList[ChecklistItem]

The issue's checklist items.

Examples:

>>> tracker.checklists.list("DE-31").root[0].text
'Review the PR'

create

create(issue_key: str, body: ChecklistItemCreate) -> Issue

POST /issues/{key}/checklistItems — add an item. Returns the issue wrapper.

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
body ChecklistItemCreate

The new item: its text and optional checked flag, assignee and deadline.

required

Returns:

Type Description
Issue

The issue wrapper with the updated checklist.

Examples:

>>> from ycli.yandex.tracker.checklists.models import ChecklistItemCreate
>>> tracker.checklists.create(
...     "DE-32", ChecklistItemCreate.model_validate({"text": "step 1"})
... ).key
'DE-32'

update

update(issue_key: str, item_id: str, body: ChecklistItemUpdate) -> Issue

PATCH /issues/{key}/checklistItems/{item_id} — edit an item. Returns the wrapper.

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
item_id str

The checklist item's id.

required
body ChecklistItemUpdate

The item fields to change.

required

Returns:

Type Description
Issue

The issue wrapper with the updated checklist.

Examples:

>>> from ycli.yandex.tracker.checklists.models import ChecklistItemUpdate
>>> tracker.checklists.update(
...     "DE-34", "5f4", ChecklistItemUpdate.model_validate({"text": "step 2"})
... ).key
'DE-34'

delete

delete(issue_key: str, item_id: str) -> Issue

DELETE /issues/{key}/checklistItems/{item_id} — remove one item (200 + wrapper).

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
item_id str

The checklist item's id.

required

Returns:

Type Description
Issue

The issue wrapper with the remaining checklist.

Examples:

>>> tracker.checklists.delete("DE-36", "5f6").checklist_items[0].text
'left'

clear

clear(issue_key: str) -> Issue

DELETE /issues/{key}/checklistItems — remove the whole checklist (200 + wrapper).

Parameters:

Name Type Description Default
issue_key str

The issue key.

required

Returns:

Type Description
Issue

The issue wrapper with an empty checklist.

Examples:

>>> tracker.checklists.clear("DE-37").checklist_items
[]

columns

ColumnsClient

ColumnsClient(*, session: SyncSession)

Bases: Resource

List, get, create, update and delete the columns of an agile board.

list

list(board_id: int) -> ItemList[Column]

GET /boards/{board_id}/columns → the board's column listing.

Parameters:

Name Type Description Default
board_id int

The board's id.

required

Returns:

Type Description
ItemList[Column]

The board's columns.

Examples:

>>> tracker.columns.list(73).root[0].name
'Open'

get

get(board_id: int, column_id: int) -> Column

GET /boards/{board_id}/columns/{column_id} → a single board column.

Parameters:

Name Type Description Default
board_id int

The board's id.

required
column_id int

The column's id.

required

Returns:

Type Description
Column

The column.

Examples:

>>> tracker.columns.get(74, 2).name
'Review'

create

create(board_id: int, body: ColumnCreate) -> Column

Create a board column from a typed ColumnCreate body. Returns the new Column.

Parameters:

Name Type Description Default
board_id int

The board's id.

required
body ColumnCreate

The new column's settings.

required

Returns:

Type Description
Column

The created column.

Examples:

>>> from ycli.yandex.tracker.columns.models import ColumnCreate
>>> tracker.columns.create(
...     75, ColumnCreate(name="Approve", statuses=["needInfo", "adjustment"])
... ).id
5

update

update(board_id: int, column_id: int, body: ColumnUpdate) -> Column

Edit a board column from a typed ColumnUpdate body. Returns the updated Column.

Only the fields set on body are sent, so omitted fields stay unchanged.

Parameters:

Name Type Description Default
board_id int

The board's id.

required
column_id int

The column's id.

required
body ColumnUpdate

The fields to change.

required

Returns:

Type Description
Column

The updated column.

Examples:

>>> from ycli.yandex.tracker.columns.models import ColumnUpdate
>>> tracker.columns.update(76, 6, ColumnUpdate(name="Pause")).name
'Pause'

delete

delete(board_id: int, column_id: int) -> None

DELETE /boards/{board_id}/columns/{column_id} — delete a column (204, no body).

Parameters:

Name Type Description Default
board_id int

The board's id.

required
column_id int

The column's id.

required

Examples:

>>> tracker.columns.delete(78, 8)

priorities

PrioritiesClient

PrioritiesClient(*, session: SyncSession)

Bases: Resource

List, create and update issue priorities.

list

list(*, localized: bool | None = None) -> ItemList[Priority]

GET /priorities → priority listing.

Parameters:

Name Type Description Default
localized bool | None

False returns the names in every language; the API's default is the caller's language only.

None

Returns:

Type Description
ItemList[Priority]

The priorities.

Examples:

>>> tracker.priorities.list().root[0].key
'normal'

create

create(body: PriorityCreate) -> Priority

Create a priority from a typed PriorityCreate body. Returns the new Priority.

Parameters:

Name Type Description Default
body PriorityCreate

The new priority's key, localized name and order.

required

Returns:

Type Description
Priority

The created priority.

Examples:

>>> from ycli.yandex.tracker.models import LocalizedName
>>> from ycli.yandex.tracker.priorities.models import PriorityCreate
>>> tracker.priorities.create(
...     PriorityCreate(key="one", name=LocalizedName(ru="Низкий", en="Low"), order=60)
... ).key
'one'

update

update(priority_id: str, body: PriorityUpdate, *, version: int | None = None) -> Priority

Edit priority priority_id from a typed PriorityUpdate body.

version is the current priority version; when set it is sent as ?version= for optimistic locking (the API rejects a stale version with 409).

Parameters:

Name Type Description Default
priority_id str

The priority's key or id.

required
body PriorityUpdate

The fields to change.

required
version int | None

The current priority version, sent as ?version=; None sends none.

None

Returns:

Type Description
Priority

The updated priority.

Examples:

>>> from ycli.yandex.tracker.priorities.models import PriorityUpdate
>>> tracker.priorities.update(
...     "blocker", PriorityUpdate(description="Stops all"), version=7
... ).key
'blocker'

issuetypes

IssueTypesClient

IssueTypesClient(*, session: SyncSession)

Bases: Resource

List, create and update issue types.

list

list() -> ItemList[IssueType]

GET /issuetypes → issue-type listing.

Returns:

Type Description
ItemList[IssueType]

The issue types.

Examples:

>>> tracker.issuetypes.list().root[0].key
'bug'

create

create(body: IssueTypeCreate) -> IssueType

Create an issue type from a typed IssueTypeCreate body. Returns the IssueType.

Parameters:

Name Type Description Default
body IssueTypeCreate

The new issue type's key and localized name.

required

Returns:

Type Description
IssueType

The created issue type.

Examples:

>>> from ycli.yandex.tracker.models import LocalizedName
>>> from ycli.yandex.tracker.issuetypes.models import IssueTypeCreate
>>> tracker.issuetypes.create(
...     IssueTypeCreate(key="client", name=LocalizedName(ru="Клиент", en="Client"))
... ).key
'client'

update

update(issue_type_id: str, body: IssueTypeUpdate, *, version: int | None = None) -> IssueType

Edit issue type issue_type_id from a typed IssueTypeUpdate body.

version is the current issue-type version; when set it is sent as ?version= for optimistic locking (the API rejects a stale version with 409).

Parameters:

Name Type Description Default
issue_type_id str

The issue type's id.

required
body IssueTypeUpdate

The fields to change.

required
version int | None

The current issue-type version, sent as ?version=; None sends none.

None

Returns:

Type Description
IssueType

The updated issue type.

Examples:

>>> from ycli.yandex.tracker.models import LocalizedName
>>> from ycli.yandex.tracker.issuetypes.models import IssueTypeUpdate
>>> tracker.issuetypes.update(
...     "23",
...     IssueTypeUpdate(name=LocalizedName(ru="Покупатель", en="Buyer")),
...     version=2,
... ).key
'client'

linktypes

LinkTypesClient

LinkTypesClient(*, session: SyncSession)

Bases: Resource

List the kinds of links between issues.

list

list() -> ItemList[LinkType]

GET /linktypes → link-type listing.

Returns:

Type Description
ItemList[LinkType]

The link types.

Examples:

>>> tracker.linktypes.list().root[0].id
'relates'

users

UsersClient

UsersClient(*, session: SyncSession)

Bases: Resource

Get one user; list every user over the relative id cursor.

get

get(login_or_id: str, expand: str | None = None) -> User

GET /users/{login_or_id} → one user account.

expand=groups adds the user's groups. For a numeric login use login:<digits>.

Parameters:

Name Type Description Default
login_or_id str

The user's login or numeric id.

required
expand str | None

Extra blocks to include; groups adds the user's groups.

None

Returns:

Type Description
User

The user.

Examples:

>>> tracker.users.get("username", expand="groups").display
'Ivan Ivanov'

list

list(*, limit: int | None = None, next: str | None = None, expand: str | None = None) -> Listing[User]

All organisation users, draining the id=<last uid> relative cursor internally.

Users come back sorted by ascending uid; each next page repeats with id=<uid of the last user seen>. Capped at limit (None = every user).

Parameters:

Name Type Description Default
limit int | None

The most users to return; None returns every user.

None
next str | None

What an earlier call returned as next. The token carries its listing; give what is required again, and nothing else but the limit.

None
expand str | None

Extra blocks to include, as in :meth:get.

None

Returns:

Type Description
Listing[User]

The organisation's users, ascending by uid.

Examples:

>>> [user.uid for user in tracker.users.list(limit=500, expand="groups")]
[1, 2, 3]

statuses

StatusesClient

StatusesClient(*, session: SyncSession)

Bases: Resource

List, create and update issue statuses.

list

list() -> ItemList[Status]

GET /statuses → status listing.

Returns:

Type Description
ItemList[Status]

The statuses.

Examples:

>>> tracker.statuses.list().root[0].key
'open'

create

create(body: StatusCreate) -> Status

Create an issue status from a typed StatusCreate body. Returns the new Status.

Parameters:

Name Type Description Default
body StatusCreate

The new status's key, localized name and type.

required

Returns:

Type Description
Status

The created status.

Examples:

>>> from ycli.yandex.tracker.models import LocalizedName
>>> from ycli.yandex.tracker.statuses.models import StatusCreate
>>> tracker.statuses.create(
...     StatusCreate(
...         key="pause", name=LocalizedName(ru="Пауза", en="Paused"), type="paused"
...     )
... ).key
'pause'

update

update(status_id: str, body: StatusUpdate, *, version: int | None = None) -> Status

Edit status status_id from a typed StatusUpdate body. Returns the Status.

version is the current status version; when set it is sent as ?version= for optimistic locking (the API rejects a stale version with 409).

Parameters:

Name Type Description Default
status_id str

The status's key or id.

required
body StatusUpdate

The fields to change.

required
version int | None

The current status version, sent as ?version=; None sends none.

None

Returns:

Type Description
Status

The updated status.

Examples:

>>> from ycli.yandex.tracker.statuses.models import StatusUpdate
>>> tracker.statuses.update(
...     "29", StatusUpdate(description="Issue is paused"), version=5
... ).version
6

resolutions

ResolutionsClient

ResolutionsClient(*, session: SyncSession)

Bases: Resource

List, create and update issue resolutions.

list

list() -> ItemList[Resolution]

GET /resolutions → resolution listing.

Returns:

Type Description
ItemList[Resolution]

The resolutions.

Examples:

>>> tracker.resolutions.list().root[0].key
'fixed'

create

create(body: ResolutionCreate) -> Resolution

Create a resolution from a typed ResolutionCreate body. Returns the Resolution.

Parameters:

Name Type Description Default
body ResolutionCreate

The new resolution's key and localized name.

required

Returns:

Type Description
Resolution

The created resolution.

Examples:

>>> from ycli.yandex.tracker.models import LocalizedName
>>> from ycli.yandex.tracker.resolutions.models import ResolutionCreate
>>> tracker.resolutions.create(
...     ResolutionCreate(
...         key="wontFix", name=LocalizedName(ru="Отклонено", en="Won't fix")
...     )
... ).key
'wontFix'

update

update(resolution_id: str, body: ResolutionUpdate, *, version: int | None = None) -> Resolution

Edit resolution resolution_id from a typed ResolutionUpdate body.

version is the current resolution version; when set it is sent as ?version= for optimistic locking (the API rejects a stale version with 409).

Parameters:

Name Type Description Default
resolution_id str

The resolution's key or id.

required
body ResolutionUpdate

The fields to change.

required
version int | None

The current resolution version, sent as ?version=; None sends none.

None

Returns:

Type Description
Resolution

The updated resolution.

Examples:

>>> from ycli.yandex.tracker.resolutions.models import ResolutionUpdate
>>> tracker.resolutions.update(
...     "9", ResolutionUpdate(description="Won't be fixed"), version=3
... ).version
4

queues

QueuesClient

QueuesClient(*, session: SyncSession)

Bases: Resource

List (page-paginated), get, create, delete and restore queues; tags, versions, access.

list

list(*, limit: int | None = None, next: str | None = None, expand: str | None = None) -> Listing[Queue]

GET /queues/ → flat ItemList[Queue], draining page/perPage internally.

Capped at limit (None = every queue). The API returns 50 queues per page; this advances the page number up to X-Total-Pages, or until a short page comes back.

Parameters:

Name Type Description Default
limit int | None

The most queues to return; None returns every queue.

None
next str | None

What an earlier call returned as next. The token carries its listing; give what is required again, and nothing else but the limit.

None
expand str | None

The extra blocks to include in each queue, as in :meth:get.

None

Returns:

Type Description
Listing[Queue]

The queues, across all pages.

Examples:

>>> tracker.queues.list(limit=500).collect().items[-1].key
'TAIL'

get

get(queue_id: str, expand: str | None = None) -> Queue

GET /queues/{queue_id} → a single :class:Queue.

queue_id is the queue key (case-sensitive) or numeric id. Pass expand to include extra blocks, e.g. expand="all" (or projects,components,versions,types,team, workflows,fields,issueTypesConfig).

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
expand str | None

Extra blocks to include; None includes none.

None

Returns:

Type Description
Queue

The queue.

Examples:

>>> tracker.queues.get("TEST", expand="all").key
'TEST'

tags_list

tags_list(queue_id: str) -> ItemList[str]

GET /queues/{queue_id}/tags → the queue's tag names as a flat string array.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required

Returns:

Type Description
ItemList[str]

The queue's tag names.

Examples:

>>> tracker.queues.tags_list("TAGQ").root
['tag1', 'tag2']

versions_list

versions_list(queue_id: str) -> ItemList[QueueVersionInfo]

GET /queues/{queue_id}/versions → the queue's versions.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required

Returns:

Type Description
ItemList[QueueVersionInfo]

The queue's versions.

Examples:

>>> tracker.queues.versions_list("VERQ").root[0].name
'v0.1'

fields_list

fields_list(queue_id: str) -> ItemList[QueueField]

GET /queues/{queue_id}/fields → the queue's required/local fields.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required

Returns:

Type Description
ItemList[QueueField]

The queue's fields.

Examples:

>>> tracker.queues.fields_list("FLDQ").root[0].id
'myfield'

create

create(body: QueueCreate) -> Queue

Create a queue from a typed QueueCreate body. Returns the created Queue.

Parameters:

Name Type Description Default
body QueueCreate

The new queue's key, name, lead and defaults.

required

Returns:

Type Description
Queue

The created queue.

Examples:

>>> from ycli.yandex.tracker.queues.models import QueueCreate
>>> new_queue = QueueCreate(
...     key="DESIGN",
...     name="Design",
...     lead="lead-login",
...     default_type="task",
...     default_priority="normal",
...     issue_types_config=[
...         {
...             "issueType": "bug",
...             "workflow": "oicn",
...             "resolutions": ["wontFix", "fixed"],
...         }
...     ],
... )
>>> tracker.queues.create(new_queue).key
'DESIGN'

delete

delete(queue_id: str) -> None

DELETE /queues/{queue_id} — delete a queue (204, empty body).

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required

Examples:

>>> tracker.queues.delete("GONE")

restore

restore(queue_id: str) -> Queue

POST /queues/{queue_id}/_restore — restore a deleted queue (admin only).

Returns the restored Queue.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required

Returns:

Type Description
Queue

The restored queue.

Examples:

>>> tracker.queues.restore("BACK").key
'BACK'

permissions_update

permissions_update(queue_id: str, body: QueuePermissionsUpdate) -> QueuePermissions

Manage queue access from a typed QueuePermissionsUpdate body.

Returns the queue's effective QueuePermissions after the change. A removal is not always the inverse of an addition: taking a user out of read took it out of write too (seen once, 2026-10-06). Adding a member that is there already changes nothing.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
body QueuePermissionsUpdate

The permission changes, per category.

required

Returns:

Type Description
QueuePermissions

The queue's permissions after the change.

Examples:

>>> from ycli.yandex.tracker.queues.models import (
...     QueuePermissionScope,
...     QueuePermissionsUpdate,
... )
>>> change = QueuePermissionsUpdate(create=QueuePermissionScope(roles=["author"]))
>>> tracker.queues.permissions_update("PERM", change).version
11

tags_delete

tags_delete(queue_id: str, body: QueueTagRemove) -> None

Remove a tag from a queue (admin only; 204, empty body).

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
body QueueTagRemove

The tag to remove.

required

Examples:

>>> from ycli.yandex.tracker.queues.models import QueueTagRemove
>>> tracker.queues.tags_delete("TAGGED", QueueTagRemove(tag="obsolete"))

versions_create

versions_create(body: QueueVersionCreate) -> QueueVersionInfo

Create a queue version from a typed QueueVersionCreate body.

Returns the created QueueVersionInfo.

Parameters:

Name Type Description Default
body QueueVersionCreate

The new version's queue and name.

required

Returns:

Type Description
QueueVersionInfo

The created version.

Examples:

>>> from ycli.yandex.tracker.queues.models import QueueVersionCreate
>>> tracker.queues.versions_create(QueueVersionCreate(queue="RELQ", name="v2.0")).name
'v2.0'

versions_get

versions_get(version_id: int, *, fields: str | None = None) -> QueueVersionInfo

GET /versions/{version_id} → one queue version.

fields_list is a comma list of the fields to return (name,dueDate,released, …).

Parameters:

Name Type Description Default
version_id int

The version's id.

required
fields str | None

A comma list of the fields to return; None returns the defaults.

None

Returns:

Type Description
QueueVersionInfo

The version.

Examples:

>>> tracker.queues.versions_get(901, fields="name,dueDate,released").name
'Release 1.0'

versions_update

versions_update(version_id: int, body: QueueVersionUpdate, *, fields: str | None = None) -> QueueVersionInfo

PATCH /versions/{version_id} → change the set fields of a version.

Parameters:

Name Type Description Default
version_id int

The version's id.

required
body QueueVersionUpdate

The fields to change.

required
fields str | None

A comma list of the fields to return; None returns the defaults.

None

Returns:

Type Description
QueueVersionInfo

The updated version.

Examples:

>>> from ycli.yandex.tracker.queues.models import QueueVersionUpdate
>>> tracker.queues.versions_update(
...     903, QueueVersionUpdate(name="Release 1.1"), fields="name,description"
... ).version
2

versions_delete

versions_delete(version_id: int) -> None

DELETE /versions/{version_id} → 204; raises on non-2xx.

Parameters:

Name Type Description Default
version_id int

The version's id.

required

Examples:

>>> tracker.queues.versions_delete(905)

user_permissions_get

user_permissions_get(queue_id: str, user_id: str) -> QueueUserAccess

GET /queues/{queue_id}/permissions/users/{user_id} → what a user may do in a queue.

user_id is a login or a numeric uid.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
user_id str

The user's login or numeric uid.

required

Returns:

Type Description
QueueUserAccess

The user's rights in the queue.

Examples:

>>> tracker.queues.user_permissions_get("PERMQ", "carol").user.display
'Carol'

group_permissions_get

group_permissions_get(queue_id: str, group_id: int) -> QueueGroupAccess

GET /queues/{queue_id}/permissions/groups/{group_id} → what a group may do.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
group_id int

The group's id.

required

Returns:

Type Description
QueueGroupAccess

The group's rights in the queue.

Examples:

>>> tracker.queues.group_permissions_get("PERMG", 77).group.display
'Editors'

localfields

LocalFieldsClient

LocalFieldsClient(*, session: SyncSession)

Bases: Resource

List, get, create and update a queue's local (queue-scoped custom) fields.

list

list(queue_id: str) -> ItemList[LocalField]

GET /queues/{queue_id}/localFields → the queue's local fields.

queue_id is the queue key (case-sensitive) or numeric id. Local fields are custom fields scoped to a single queue; the response is a bare JSON array.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required

Returns:

Type Description
ItemList[LocalField]

The queue's local fields.

Examples:

>>> tracker.localfields.list("ORG").root[0].key
'loc_field_key'

get

get(queue_id: str, field_key: str) -> LocalField

GET /queues/{queue_id}/localFields/{field_key} → one local field.

field_key is the field key returned by :meth:list.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
field_key str

The field's key.

required

Returns:

Type Description
LocalField

The local field.

Examples:

>>> tracker.localfields.get("OPS", "deadline_note").name
'Deadline note'

create

create(queue_id: str, body: FieldCreate) -> LocalField

Create a local field in queue queue_id from a typed FieldCreate body.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
body FieldCreate

The new field's name, id, category and type.

required

Returns:

Type Description
LocalField

The created local field.

Examples:

>>> from ycli.yandex.tracker.models import FieldCreate, LocalizedName
>>> new_field = FieldCreate(
...     name=LocalizedName(ru="Поле", en="Field"),
...     id="loc_new",
...     category="cat-3",
...     type="ru.yandex.startrek.core.fields.StringFieldType",
... )
>>> tracker.localfields.create("DEV", new_field).key
'loc_new'

update

update(queue_id: str, field_key: str, body: LocalFieldUpdate) -> LocalField

Edit local field field_key of queue queue_id from a typed LocalFieldUpdate.

This endpoint has no ?version= optimistic lock; only the fields set on body are sent, so omitted fields stay unchanged.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
field_key str

The field's key.

required
body LocalFieldUpdate

The fields to change.

required

Returns:

Type Description
LocalField

The updated local field.

Examples:

>>> from ycli.yandex.tracker.localfields.models import LocalFieldUpdate
>>> tracker.localfields.update("SUP", "loc_edit", LocalFieldUpdate(order=102)).order
102

fields

FieldsClient

FieldsClient(*, session: SyncSession)

Bases: Resource

List, get, create and update global fields; create and edit their categories.

list

list() -> ItemList[CustomField]

GET /fields → all global fields of the organisation.

Returns:

Type Description
ItemList[CustomField]

The global fields.

Examples:

>>> tracker.fields.list().root[0].id
'ruName'

get

get(field_id: str) -> CustomField

GET /fields/{field_id} → parameters of one issue field.

Parameters:

Name Type Description Default
field_id str

The field's id.

required

Returns:

Type Description
CustomField

The field.

Examples:

>>> tracker.fields.get("enName").id
'enName'

create

create(body: FieldCreate) -> CustomField

Create a global field from a typed FieldCreate body. Returns the CustomField.

A name is unique among the fields: one that is taken answers 422 (measured).

Parameters:

Name Type Description Default
body FieldCreate

The new field's settings.

required

Returns:

Type Description
CustomField

The created field.

Examples:

>>> from ycli.yandex.tracker.models import FieldCreate, LocalizedName
>>> tracker.fields.create(
...     FieldCreate(
...         name=LocalizedName(ru="Поле"),
...         id="myField",
...         category="cat-1",
...         type="ru.yandex.startrek.core.fields.StringFieldType",
...     )
... ).id
'myField'

update

update(field_id: str, body: FieldUpdate, *, version: int | None = None) -> CustomField

Edit field field_id from a typed FieldUpdate body (rename and/or options).

version is the current field version; when set it is sent as ?version= for optimistic locking (the API rejects a stale version).

Parameters:

Name Type Description Default
field_id str

The field's id.

required
body FieldUpdate

The fields to change.

required
version int | None

The field's current version, for optimistic locking.

None

Returns:

Type Description
CustomField

The updated field.

Examples:

>>> from ycli.yandex.tracker.models import LocalizedName
>>> from ycli.yandex.tracker.fields.models import FieldUpdate
>>> tracker.fields.update(
...     "ruName", FieldUpdate(name=LocalizedName(ru="Имя")), version=3
... ).id
'ruName'

categories_create

categories_create(body: FieldCategoryCreate) -> FieldCategoryRecord

Create a field category from a typed FieldCategoryCreate body.

Parameters:

Name Type Description Default
body FieldCategoryCreate

The new category's settings.

required

Returns:

Type Description
FieldCategoryRecord

The created category.

Examples:

>>> from ycli.yandex.tracker.models import LocalizedName
>>> from ycli.yandex.tracker.fields.models import FieldCategoryCreate
>>> tracker.fields.categories_create(
...     FieldCategoryCreate(name=LocalizedName(ru="Своя"), order=400)
... ).id
'604f99'

categories_update

categories_update(category_id: str, body: FieldCategoryUpdate, *, version: int | None = None) -> FieldCategoryRecord

Edit field category category_id from a typed FieldCategoryUpdate body.

version is the current category version; when set it is sent as ?version= for optimistic locking.

Parameters:

Name Type Description Default
category_id str

The category's id.

required
body FieldCategoryUpdate

The fields to change.

required
version int | None

The category's current version, for optimistic locking.

None

Returns:

Type Description
FieldCategoryRecord

The updated category.

Examples:

>>> from ycli.yandex.tracker.fields.models import FieldCategoryUpdate
>>> tracker.fields.categories_update(
...     "604f99", FieldCategoryUpdate(order=500), version=1
... ).version
2

components

ComponentsClient

ComponentsClient(*, session: SyncSession)

Bases: Resource

List, get, create, update and delete queue components; read who may use them.

list

list() -> ItemList[Component]

GET /components → all components created by the organisation's users.

Returns:

Type Description
ItemList[Component]

The components.

Examples:

>>> tracker.components.list().root[0].name
'Backend'

create

create(body: ComponentCreate) -> Component

Create a component from a typed ComponentCreate body. Returns the Component.

Parameters:

Name Type Description Default
body ComponentCreate

The new component's settings.

required

Returns:

Type Description
Component

The created component.

Examples:

>>> from ycli.yandex.tracker.components.models import ComponentCreate
>>> tracker.components.create(ComponentCreate(name="UI", queue="WEB")).id
111175

update

update(component_id: int, body: ComponentUpdate, *, version: int | None = None) -> Component

Edit component component_id from a typed ComponentUpdate body.

version is the current component version; when set it is sent as ?version= for optimistic locking (the API rejects a stale version with 409).

Parameters:

Name Type Description Default
component_id int

The component's id.

required
body ComponentUpdate

The fields to change.

required
version int | None

The component's current version, for optimistic locking.

None

Returns:

Type Description
Component

The updated component.

Examples:

>>> from ycli.yandex.tracker.components.models import ComponentUpdate
>>> tracker.components.update(111175, ComponentUpdate(name="Web UI"), version=4).version
5

list_for_queue

list_for_queue(queue_id: str, *, fields: str | None = None) -> ItemList[Component]

GET /queues/{queue_id}/components → the components of one queue.

fields is a comma list of extra fields (version,description,lead,assignAuto); self, id, name and queue always come back.

Parameters:

Name Type Description Default
queue_id str

The queue's key or id.

required
fields str | None

The extra fields to include, comma-separated.

None

Returns:

Type Description
ItemList[Component]

The queue's components.

Examples:

>>> tracker.components.list_for_queue("COMPQ", fields="version,description").root[
...     0
... ].name
'Frontend'

get

get(component_id: int, *, fields: str | None = None) -> Component

GET /components/{component_id} → one component.

Parameters:

Name Type Description Default
component_id int

The component's id.

required
fields str | None

The extra fields to include, comma-separated.

None

Returns:

Type Description
Component

The component.

Examples:

>>> tracker.components.get(125, fields="name,lead,assignAuto").name
'Backend'

delete

delete(component_id: int) -> None

DELETE /components/{component_id} → 204; raises on non-2xx.

Parameters:

Name Type Description Default
component_id int

The component's id.

required

Examples:

>>> tracker.components.delete(127)

user_permissions_get

user_permissions_get(component_id: int, user_id: str) -> ComponentUserAccess

GET /components/{id}/permissions/users/{user_id} → a user's rights on a component.

user_id is a login or a numeric uid.

Parameters:

Name Type Description Default
component_id int

The component's id.

required
user_id str

The user's login or numeric uid.

required

Returns:

Type Description
ComponentUserAccess

The user's rights on the component.

Examples:

>>> tracker.components.user_permissions_get(128, "dan").user.display
'Dan'

group_permissions_get

group_permissions_get(component_id: int, group_id: int) -> ComponentGroupAccess

GET /components/{id}/permissions/groups/{group_id} → a group's rights on it.

Parameters:

Name Type Description Default
component_id int

The component's id.

required
group_id int

The group's id.

required

Returns:

Type Description
ComponentGroupAccess

The group's rights on the component.

Examples:

>>> tracker.components.group_permissions_get(129, 88).group.display
'Reviewers'

filters

FiltersClient

FiltersClient(*, session: SyncSession)

Bases: Resource

Get, create, update and delete saved issue filters.

get

get(filter_id: str) -> Filter

GET /filters/{filter_id} → parameters of one saved filter.

Parameters:

Name Type Description Default
filter_id str

The filter's id.

required

Returns:

Type Description
Filter

The saved filter.

Examples:

>>> tracker.filters.get("12345").name
'My open issues'

create

create(body: FilterCreate) -> Filter

Create a saved filter from a typed FilterCreate body. Returns the Filter.

Parameters:

Name Type Description Default
body FilterCreate

The new filter's name, query and filter object.

required

Returns:

Type Description
Filter

The created filter.

Examples:

>>> from ycli.yandex.tracker.filters.models import FilterCreate
>>> tracker.filters.create(FilterCreate(name="My open", filter={"status": "open"})).id
12346

update

update(filter_id: str, body: FilterUpdate) -> Filter

Edit filter filter_id from a typed FilterUpdate body. Returns the Filter.

This endpoint has no ?version= optimistic lock; the filter object is replaced wholesale rather than merged.

Parameters:

Name Type Description Default
filter_id str

The filter's id.

required
body FilterUpdate

The fields to change.

required

Returns:

Type Description
Filter

The updated filter.

Examples:

>>> from ycli.yandex.tracker.filters.models import FilterUpdate
>>> tracker.filters.update("12347", FilterUpdate(name="Renamed")).name
'Renamed'

delete

delete(filter_id: str) -> None

DELETE /filters/{filter_id} → 204; raises on non-2xx.

The docs name the /v2/filters/{id} route; the /v3/ one used by every other filter call deletes it too.

Parameters:

Name Type Description Default
filter_id str

The filter's id.

required

Examples:

>>> tracker.filters.delete("12349")

applications

ApplicationsClient

ApplicationsClient(*, session: SyncSession)

Bases: Resource

List the external applications issues can be linked to.

list

list() -> ItemList[Application]

GET /applications → external applications that issues can be linked to.

Returns:

Type Description
ItemList[Application]

The external applications.

Examples:

>>> tracker.applications.list().root[0].id
'my-application'

boards

BoardsClient

BoardsClient(*, session: SyncSession)

Bases: Resource

List (relative-paginated), get, create, update and delete agile boards.

list

list(*, limit: int | None = None, next: str | None = None) -> Listing[Board]

All agile boards in the organisation, draining the id=<last board id> cursor.

/boards/_paginate sorts by ascending board id; each next page repeats with id=<id of the last board seen> until a page comes back empty. Capped at limit (None = every board); a small cap narrows the page to limit rows.

Parameters:

Name Type Description Default
limit int | None

The most boards to return; None returns every board.

None
next str | None

What an earlier call returned as next. The token carries its listing; give what is required again, and nothing else but the limit.

None

Returns:

Type Description
Listing[Board]

The boards, in ascending id order.

Examples:

>>> [board.name for board in tracker.boards.list(limit=500)]
['Alpha', 'Beta', 'Gamma']

get

get(board_id: int) -> Board

GET /boards/{board_id} → a single agile board.

Parameters:

Name Type Description Default
board_id int

The board's id.

required

Returns:

Type Description
Board

The board.

Examples:

>>> tracker.boards.get(31).name
'Kanban'

create

create(body: BoardCreate) -> Board

Create an agile board from a typed BoardCreate body. Returns the new Board.

The endpoint path is literally /liveBoards/ — the older POST /boards/ is deprecated and silently ignores the request body.

Parameters:

Name Type Description Default
body BoardCreate

The new board's settings.

required

Returns:

Type Description
Board

The created board.

Examples:

>>> tracker.boards.create(BoardCreate(name="Release train", owner="alice")).id
41

update

update(board_id: int, body: BoardUpdate) -> Board

Edit an agile board from a typed BoardUpdate body. Returns the updated Board.

Only the fields set on body are sent, so omitted fields stay unchanged.

Parameters:

Name Type Description Default
board_id int

The board's id.

required
body BoardUpdate

The fields to change.

required

Returns:

Type Description
Board

The updated board.

Examples:

>>> tracker.boards.update(51, BoardUpdate(name="Renamed board")).name
'Renamed board'

delete

delete(board_id: int) -> None

DELETE /boards/{board_id} — delete a board (204, empty body).

Parameters:

Name Type Description Default
board_id int

The board's id.

required

Examples:

>>> tracker.boards.delete(61)

sprints

SprintsClient

SprintsClient(*, session: SyncSession)

Bases: Resource

List a board's sprints; get, create, update, delete, start and archive a sprint.

list

list(board_id: int) -> ItemList[Sprint]

GET /boards/{board_id}/sprints → the board's sprint listing.

Parameters:

Name Type Description Default
board_id int

The board's id.

required

Returns:

Type Description
ItemList[Sprint]

The board's sprints.

Examples:

>>> tracker.sprints.list(3).root[0].name
'Sprint 1'

get

get(sprint_id: int) -> Sprint

GET /sprints/{sprint_id} → a single sprint.

Parameters:

Name Type Description Default
sprint_id int

The sprint's id.

required

Returns:

Type Description
Sprint

The sprint.

Examples:

>>> tracker.sprints.get(4402).status
'in_progress'

create

create(body: SprintCreate) -> Sprint

Create a sprint from a typed SprintCreate body. Returns the created Sprint.

Parameters:

Name Type Description Default
body SprintCreate

The new sprint's name, board and dates.

required

Returns:

Type Description
Sprint

The created sprint.

Examples:

>>> from ycli.yandex.tracker.sprints.models import SprintBoardInput, SprintCreate
>>> new_sprint = SprintCreate(
...     name="Sprint 9",
...     board=SprintBoardInput(id="17"),
...     start_date="2026-10-05",
...     end_date="2026-10-19",
... )
>>> tracker.sprints.create(new_sprint).id
4403

update

update(sprint_id: int, body: SprintUpdate, *, version: int | None = None) -> Sprint

Edit a sprint from a typed SprintUpdate body. Returns the updated Sprint.

Only the fields set on body are sent, so omitted fields stay unchanged. version is the sprint's current version, sent as ?version= — the API requires it (or an If-Match header) for optimistic locking and answers 428 without one.

Parameters:

Name Type Description Default
sprint_id int

The sprint's id.

required
body SprintUpdate

The fields to change.

required
version int | None

The sprint's current version, sent as ?version=.

None

Returns:

Type Description
Sprint

The updated sprint.

Examples:

>>> from ycli.yandex.tracker.sprints.models import SprintUpdate
>>> tracker.sprints.update(4404, SprintUpdate(name="Updated"), version=5).name
'Updated'

delete

delete(sprint_id: int) -> None

DELETE /sprints/{sprint_id} — delete a sprint (204, empty body).

Parameters:

Name Type Description Default
sprint_id int

The sprint's id.

required

Examples:

>>> tracker.sprints.delete(4406)

start

start(sprint_id: int, *, version: int | None = None) -> Sprint

POST /sprints/{sprint_id}/_start — start a sprint (status → in_progress).

version is the sprint's current version, sent as ?version= — the API requires it (or an If-Match header) for optimistic locking and answers 428 without one.

Parameters:

Name Type Description Default
sprint_id int

The sprint's id.

required
version int | None

The sprint's current version, sent as ?version=.

None

Returns:

Type Description
Sprint

The started sprint.

Examples:

>>> tracker.sprints.start(4407, version=6).status
'in_progress'

archive

archive(sprint_id: int, *, version: int | None = None) -> Sprint

POST /sprints/{sprint_id}/_archive — archive a sprint (status → archived).

version is the sprint's current version, sent as ?version= — the API requires it (or an If-Match header) for optimistic locking and answers 428 without one.

Parameters:

Name Type Description Default
sprint_id int

The sprint's id.

required
version int | None

The sprint's current version, sent as ?version=.

None

Returns:

Type Description
Sprint

The archived sprint.

Examples:

>>> tracker.sprints.archive(4409, version=7).status
'archived'

attachments

AttachmentsClient

AttachmentsClient(*, session: SyncSession)

Bases: Resource

Issue /attachments — list, get, upload, delete, plus two binary downloads.

list

list(issue_key: str) -> ItemList[Attachment]

GET /issues/{issue_key}/attachments → files attached to the issue (and its comments).

Parameters:

Name Type Description Default
issue_key str

The issue key.

required

Returns:

Type Description
ItemList[Attachment]

The issue's attachments.

Examples:

>>> tracker.attachments.list("JUNE-2").root[0].name
'picture.jpg'

download

download(issue_key: str, file_id: str, filename: str) -> bytes

Download an attachment's raw bytes (a non-2xx answer raises a typed error).

Binary output is CLI/SDK-only — never an MCP payload. In the CLI this feeds a BinaryResult (a file or stdout); the SDK returns the bytes.

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
file_id str

The attachment's id.

required
filename str

The attachment's file name, as it is in the download path.

required

Returns:

Type Description
bytes

The attachment's raw bytes.

Examples:

>>> tracker.attachments.download("JUNE-3", "4159", "report.pdf")[:4]
b'%PDF'

thumbnails_download

thumbnails_download(issue_key: str, file_id: str) -> bytes

Download a graphic attachment's preview-thumbnail bytes (a non-2xx answer raises).

Only graphic files have a thumbnail; CLI/SDK-only, like :meth:download.

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
file_id str

The attachment's id.

required

Returns:

Type Description
bytes

The thumbnail's raw bytes.

Examples:

>>> tracker.attachments.thumbnails_download("JUNE-4", "4160")[:4]
b'\x89PNG'

get

get(issue_key: str, file_id: str) -> Attachment

GET /issues/{issue_key}/attachments/{file_id} → the attachment's metadata.

The raw bytes are :meth:download; this returns name, size, MIME type and uploader.

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
file_id str

The attachment's id.

required

Returns:

Type Description
Attachment

The attachment's metadata.

Examples:

>>> tracker.attachments.get("JUNE-5", "4161").mimetype
'text/plain'

delete

delete(issue_key: str, file_id: str) -> None

DELETE /issues/{issue_key}/attachments/{file_id} → 204; raises on non-2xx.

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
file_id str

The attachment's id.

required

Examples:

>>> tracker.attachments.delete("JUNE-6", "4162")

upload

upload(issue_key: str, *, filename: str, data: bytes, rename_to: str | None = None) -> Attachment

POST /issues/{issue_key}/attachments → attach a file (multipart field file).

filename names the part; rename_to (the ?filename= query) stores the file under another name. Returns the created :class:Attachment.

Parameters:

Name Type Description Default
issue_key str

The issue key.

required
filename str

The multipart part's file name.

required
data bytes

The file's bytes.

required
rename_to str | None

The name to store the file under; None keeps filename.

None

Returns:

Type Description
Attachment

The created attachment.

Examples:

>>> tracker.attachments.upload(
...     "JUNE-7", filename="upload.txt", data=b"attachment bytes", rename_to="kept.txt"
... ).id
'4161'

upload_temp

upload_temp(*, filename: str, data: bytes, rename_to: str | None = None) -> Attachment

POST /attachments → upload a temporary file to attach later, once.

The returned id goes into attachmentIds of an issue or comment body; Tracker accepts it for one attachment only.

Parameters:

Name Type Description Default
filename str

The multipart part's file name.

required
data bytes

The file's bytes.

required
rename_to str | None

The name to store the file under; None keeps filename.

None

Returns:

Type Description
Attachment

The temporary attachment, whose id is the one to attach.

Examples:

>>> tracker.attachments.upload_temp(
...     filename="temp-upload.txt", data=b"temporary bytes", rename_to="scratch.txt"
... ).id
'4170'

import_

import_(issue_key: str, *, filename: str, created_at: str, created_by: str, data: bytes) -> Attachment

Import a file (multipart/form-data) preserving its createdAt / createdBy.

data are the raw file bytes; filename / created_at / created_by become query parameters. Returns the created Attachment.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
filename str

The attachment's file name.

required
created_at str

The source creation time.

required
created_by str

The source author.

required
data bytes

The raw file bytes.

required

Returns:

Type Description
Attachment

The created attachment.

Examples:

>>> tracker.attachments.import_(
...     "JUNE-5",
...     filename="renamed.png",
...     created_at="2022-05-06T07:08:09.000+0000",
...     created_by="16",
...     data=b"PNGDATA",
... ).name
'renamed.png'

import_for_comment

import_for_comment(issue_key: str, comment_id: str, *, filename: str, created_at: str, created_by: str, data: bytes) -> Attachment

Import a file onto a comment, preserving its createdAt / createdBy.

POST /issues/{issue_key}/comments/{comment_id}/attachments/_import (multipart); created_at must fall between the comment's creation and its last update (for a comment never edited, exactly its createdAt), else Tracker answers 422. Returns the created Attachment.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
comment_id str

The comment's id.

required
filename str

The attachment's file name.

required
created_at str

The source creation time.

required
created_by str

The source author.

required
data bytes

The raw file bytes.

required

Returns:

Type Description
Attachment

The created attachment.

Examples:

>>> tracker.attachments.import_for_comment(
...     "JUNE-7",
...     "2238",
...     filename="scan.png",
...     created_at="2024-07-08T09:10:11.000+0000",
...     created_by="18",
...     data=b"PNGDATA",
... ).name
'scan.png'

macros

MacrosClient

MacrosClient(*, session: SyncSession)

Bases: Resource

List, get, create, update and delete a queue's macros.

list

list(queue_id: str) -> ItemList[Macro]

GET /queues/{queue_id}/macros → the queue's macros.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required

Returns:

Type Description
ItemList[Macro]

The queue's macros.

Examples:

>>> tracker.macros.list("TEST").root[0].name
'Close'

get

get(queue_id: str, macro_id: int) -> Macro

GET /queues/{queue_id}/macros/{macro_id} → a single macro.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
macro_id int

The macro's id.

required

Returns:

Type Description
Macro

The macro.

Examples:

>>> tracker.macros.get("OPS", 4).name
'Escalate'

create

create(queue_id: str, body: MacroCreate) -> Macro

Create a macro from a typed MacroCreate body. Returns the created Macro.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
body MacroCreate

The new macro's name, comment text and issue update.

required

Returns:

Type Description
Macro

The created macro.

Examples:

>>> from ycli.yandex.tracker.macros.models import MacroCreate
>>> tracker.macros.create("DEV", MacroCreate(name="Triage", body="Taking a look")).id
5

update

update(queue_id: str, macro_id: int, body: MacroUpdate) -> Macro

Edit a macro from a typed MacroUpdate body. Returns the updated Macro.

Only the fields set on body are sent, so omitted fields stay unchanged.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
macro_id int

The macro's id.

required
body MacroUpdate

The fields to change.

required

Returns:

Type Description
Macro

The updated macro.

Examples:

>>> from ycli.yandex.tracker.macros.models import MacroUpdate
>>> tracker.macros.update("QA", 6, MacroUpdate(name="Renamed")).name
'Renamed'

delete

delete(queue_id: str, macro_id: int) -> None

DELETE /queues/{queue_id}/macros/{macro_id} — delete a macro (204, empty body).

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
macro_id int

The macro's id.

required

Examples:

>>> tracker.macros.delete("SUP", 7)

triggers

TriggersClient

TriggersClient(*, session: SyncSession)

Bases: Resource

List, get, create and update a queue's triggers; read a trigger's webhook log.

list

list(queue_id: str, *, limit: int | None = None, next: str | None = None) -> Listing[Trigger]

GET /queues/{queue_id}/triggers → every trigger of the queue, ascending by id.

Drains the relative cursor (id=<last trigger id>). Capped at limit (None = every trigger); a small cap narrows the page to limit rows.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
limit int | None

The most triggers to return; None returns every trigger.

None
next str | None

What an earlier call returned as next. The token carries its listing; give what is required again, and nothing else but the limit.

None

Returns:

Type Description
Listing[Trigger]

The queue's triggers, ascending by id.

Examples:

>>> [trigger.name for trigger in tracker.triggers.list("LISTQ", limit=500)]
['First', 'Second']

get

get(queue_id: str, trigger_id: int) -> Trigger

GET /queues/{queue_id}/triggers/{trigger_id} → a single trigger.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
trigger_id int

The trigger's id.

required

Returns:

Type Description
Trigger

The trigger.

Examples:

>>> tracker.triggers.get("DESIGN", 16).name
'On comment'

create

create(queue_id: str, body: TriggerCreate) -> Trigger

Create a trigger from a typed TriggerCreate body. Returns the created Trigger.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
body TriggerCreate

The new trigger's name, actions and conditions.

required

Returns:

Type Description
Trigger

The created trigger.

Examples:

>>> from ycli.yandex.tracker.models import AutomationAction
>>> from ycli.yandex.tracker.triggers.models import TriggerCreate
>>> new_trigger = TriggerCreate(
...     name="Reopen on comment",
...     actions=[AutomationAction(type="Transition", status={"key": "open"})],
... )
>>> tracker.triggers.create("ART", new_trigger).id
17

update

update(queue_id: str, trigger_id: int, body: TriggerUpdate, *, version: int | None = None) -> Trigger

Edit a trigger from a typed TriggerUpdate body. Returns the updated Trigger.

Pass version (the trigger's current version) to guard against a concurrent edit; only the fields set on body are sent.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
trigger_id int

The trigger's id.

required
body TriggerUpdate

The fields to change.

required
version int | None

The trigger's current version, sent as ?version=; None sends none.

None

Returns:

Type Description
Trigger

The updated trigger.

Examples:

>>> from ycli.yandex.tracker.triggers.models import TriggerUpdate
>>> tracker.triggers.update(
...     "BIZ", 18, TriggerUpdate(name="Renamed trigger"), version=3
... ).name
'Renamed trigger'

webhook_log_list

webhook_log_list(queue_id: str, trigger_id: int, issue_id: str | None = None, limit: int | None = None, date_from: str | None = None, date_to: str | None = None) -> ItemList[WebhookLogEntry]

GET /queues/{queue_id}/triggers/{trigger_id}/webhooks/log → HTTP-action run logs.

Returns the trigger's Webhook-action execution records (default 10, limit up to 100). Optionally scope to one issue_id or a date_from/date_to window.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required
trigger_id int

The trigger's id.

required
issue_id str | None

Only the runs for this issue.

None
limit int | None

The most records to return (default 10, up to 100).

None
date_from str | None

Only runs from this time on (ISO 8601).

None
date_to str | None

Only runs up to this time (ISO 8601).

None

Returns:

Type Description
ItemList[WebhookLogEntry]

The trigger's Webhook-action execution records.

Examples:

>>> tracker.triggers.webhook_log_list(
...     "DEV",
...     6,
...     issue_id="DEV-5",
...     limit=100,
...     date_from="2026-01-01T00:00:00.000+0300",
...     date_to="2026-02-01T00:00:00.000+0300",
... ).root[0].duration
235

autoactions

AutoactionsClient

AutoactionsClient(*, session: SyncSession)

Bases: Resource

Get and create a queue's autoactions; read their run logs.

get

get(queue_id: str, action_id: int) -> Autoaction

GET /queues/{queue_id}/autoactions/{action_id} → a single autoaction.

Parameters:

Name Type Description Default
queue_id str

The queue's key or id.

required
action_id int

The autoaction's id.

required

Returns:

Type Description
Autoaction

The autoaction.

Examples:

>>> tracker.autoactions.get("DESIGN", 9).name
'Nightly'

create

create(queue_id: str, body: AutoactionCreate) -> Autoaction

Create an autoaction from a typed AutoactionCreate body. Returns the Autoaction.

Parameters:

Name Type Description Default
queue_id str

The queue's key or id.

required
body AutoactionCreate

The new autoaction's settings.

required

Returns:

Type Description
Autoaction

The created autoaction.

Examples:

>>> from ycli.yandex.tracker.autoactions.models import AutoactionCreate
>>> from ycli.yandex.tracker.models import AutomationAction
>>> tracker.autoactions.create(
...     "OPS",
...     AutoactionCreate(
...         name="Stale sweep",
...         query="Status: Open",
...         actions=[AutomationAction(type="Transition")],
...     ),
... ).id
10

logs_list

logs_list(queue_id: str, action_id: int) -> ItemList[AutoactionLogEntry]

GET /queues/{queue_id}/autoactions/{action_id}/logs → per-run summaries.

Parameters:

Name Type Description Default
queue_id str

The queue's key or id.

required
action_id int

The autoaction's id.

required

Returns:

Type Description
ItemList[AutoactionLogEntry]

One summary per run.

Examples:

>>> tracker.autoactions.logs_list("QA", 11).root[0].search_hits
3

logs_get

logs_get(queue_id: str, action_id: int, run_id: str) -> ItemList[AutoactionRunEntry]

GET .../autoactions/{action_id}/logs/{run_id} → per-issue outcomes of one run.

Parameters:

Name Type Description Default
queue_id str

The queue's key or id.

required
action_id int

The autoaction's id.

required
run_id str

The run's id.

required

Returns:

Type Description
ItemList[AutoactionRunEntry]

The outcome for each issue the run touched.

Examples:

>>> tracker.autoactions.logs_get("SUP", 12, "run-2").root[0].status.value
'success'

bulk

BulkClient

BulkClient(*, session: SyncSession)

Bases: Resource

/bulkchange: the status of a bulk change and the issues it failed on.

get

get(bulk_id: str) -> BulkChange

GET /bulkchange/{bulk_id} → the operation's current status (poll this to wait).

Parameters:

Name Type Description Default
bulk_id str

The bulk change's id.

required

Returns:

Type Description
BulkChange

The bulk change with its current status.

Examples:

>>> tracker.bulk.get("4gh").is_terminal
True

issues_list

issues_list(bulk_id: str) -> ItemList[BulkIssueResult]

GET /bulkchange/{bulk_id}/issues → every issue of the change, with how it went.

One record per issue, the ones that went well too: after a change that passed, each reads COMPLETED (measured); a failed one carries its error.

Parameters:

Name Type Description Default
bulk_id str

The bulk change's id.

required

Returns:

Type Description
ItemList[BulkIssueResult]

The per-issue results.

Examples:

>>> tracker.bulk.issues_list("5ij").root[0].issue
'DE-9'

RemoteLinksClient

RemoteLinksClient(*, session: SyncSession)

Bases: Resource

List, create and delete an issue's links to objects in external applications.

list

list(issue_key: str) -> ItemList[RemoteLink]

GET /issues/{issue_key}/remotelinks → the issue's external-app links.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required

Returns:

Type Description
ItemList[RemoteLink]

The issue's external-app links.

Examples:

>>> tracker.remotelinks.list("JUNE-2").root[0].object_key
'TEST-17'

create

create(issue_key: str, body: RemoteLinkCreate, backlink: bool | None = None) -> RemoteLink

POST /issues/{issue_key}/remotelinks?backlink=… — add an external link.

backlink=True asks Tracker to also create the mirror link in the external app.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
body RemoteLinkCreate

The link's relationship, external object key and origin.

required
backlink bool | None

True also creates the mirror link in the external app.

None

Returns:

Type Description
RemoteLink

The created external link.

Examples:

>>> from ycli.yandex.tracker.remotelinks.models import RemoteLinkCreate
>>> tracker.remotelinks.create(
...     "JUNE-3",
...     RemoteLinkCreate.model_validate(
...         {
...             "relationship": "RELATES",
...             "key": "TEST-18",
...             "origin": "ru.yandex.bitbucket",
...         }
...     ),
...     backlink=True,
... ).object_key
'TEST-18'

delete

delete(issue_key: str, link_id: str) -> None

Delete an external link (DELETE …/remotelinks/{link_id} → 204). Raises on non-2xx.

Parameters:

Name Type Description Default
issue_key str

The issue's key.

required
link_id str

The external link's id.

required

Examples:

>>> tracker.remotelinks.delete("JUNE-6", "55")

dashboards

DashboardsClient

DashboardsClient(*, session: SyncSession)

Bases: Resource

/dashboards (create a dashboard, add a cycle-time widget).

create

create(body: DashboardCreate) -> Dashboard

POST /dashboards/ — create a dashboard. Returns the created Dashboard.

Parameters:

Name Type Description Default
body DashboardCreate

The new dashboard's settings.

required

Returns:

Type Description
Dashboard

The created dashboard.

Examples:

>>> from ycli.yandex.tracker.dashboards.models import DashboardCreate
>>> tracker.dashboards.create(
...     DashboardCreate.model_validate({"name": "Team board", "layout": "two-columns"})
... ).id
10

widgets_create_cycle_time

widgets_create_cycle_time(dashboard_id: str, body: CycleTimeWidget) -> Widget

POST /dashboards/{dashboard_id}/widgets/cycleTime — add a cycle-time widget.

Returns the created Widget.

Parameters:

Name Type Description Default
dashboard_id str

The dashboard's id.

required
body CycleTimeWidget

The widget's settings: its description, issue query and statuses.

required

Returns:

Type Description
Widget

The created widget.

Examples:

>>> from ycli.yandex.tracker.dashboards.models import CycleTimeWidget
>>> tracker.dashboards.widgets_create_cycle_time(
...     "11",
...     CycleTimeWidget.model_validate(
...         {"description": "Cycle time", "query": "Queue: DE"}
...     ),
... ).id
123456

entities

EntitiesClient

EntitiesClient(*, session: SyncSession)

Bases: Resource

/entities/{entity_type} and its sub-resources.

create

create(entity_type: str, body: EntityCreate, *, fields: str | None = None) -> Entity

POST /entities/{entity_type} — create an entity from a {fields: …} body.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
body EntityCreate

The new entity, as {"fields": {...}}.

required
fields str | None

The comma-separated entity fields to include in the reply.

None

Returns:

Type Description
Entity

The created entity.

Examples:

>>> from ycli.yandex.tracker.entities.models import EntityCreate
>>> tracker.entities.create(
...     "project", EntityCreate.model_validate({"fields": {"summary": "Q4 launch"}})
... ).id
'655f'

get

get(entity_type: str, entity_id: str, expand: str | None = None, fields: str | None = None) -> Entity

GET /entities/{entity_type}/{entity_id} → a single entity (raises on non-2xx).

fields is a comma-separated selector of extra fields keys (summary, checklistItems, keyResultItems, metricItems, …); expand=attachments embeds attachment metadata.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
expand str | None

The extras to embed, such as attachments.

None
fields str | None

The extra fields keys to include, comma-separated.

None

Returns:

Type Description
Entity

The entity.

Examples:

>>> tracker.entities.get(
...     "goal", "g2", expand="attachments", fields="summary,keyResultItems"
... ).fields.summary
'Ship'

update

update(entity_type: str, entity_id: str, body: EntityUpdate, *, expand: str | None = None, fields: str | None = None) -> Entity

PATCH /entities/{entity_type}/{entity_id} — edit fields/comment/links. Returns it.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
body EntityUpdate

The changes: fields, a comment or links.

required
expand str | None

The extra blocks to include in the reply.

None
fields str | None

The comma-separated entity fields to include in the reply.

None

Returns:

Type Description
Entity

The updated entity.

Examples:

>>> from ycli.yandex.tracker.entities.models import EntityUpdate
>>> tracker.entities.update(
...     "project",
...     "655f04",
...     EntityUpdate.model_validate({"fields": {"summary": "Renamed"}}),
... ).id
'655f04'

delete

delete(entity_type: str, entity_id: str, *, with_board: bool | None = None) -> None

Delete an entity. Pass with_board=True to delete its board too. Raises on non-2xx.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
with_board bool | None

Whether to delete the entity's board too.

None

Examples:

>>> tracker.entities.delete("project", "655f07", with_board=True)

search

search(entity_type: str, body: EntitySearch | None = None, *, fields: str | None = None, limit: int | None = None, next: str | None = None) -> Listing[Entity]

POST /entities/{entity_type}/_search → the matching entities, page by page.

body carries input (substring), filter (field→value), orderBy, orderAsc and rootOnly. fields selects extra fields keys in the results.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
body EntitySearch | None

The search: input, filter, orderBy, orderAsc, rootOnly.

None
fields str | None

The extra fields keys to include, comma-separated.

None
limit int | None

The most entities to return; None returns every one.

None
next str | None

What an earlier call returned as next. The token carries its listing; give what is required again, and nothing else but the limit.

None

Returns:

Type Description
Listing[Entity]

The matching entities.

Examples:

>>> tracker.entities.search(
...     "project", {"input": "Q4", "filter": {"entityStatus": "in_progress"}}
... ).collect().items[0].id
'655f'

events_list

events_list(entity_type: str, entity_id: str, *, limit: int | None = None, next: str | None = None, selected: str | None = None, new_events_on_top: bool | None = None, direction: str | None = None) -> Listing[EntityEvent]

GET …/events/_relative → flat ItemList[EntityEvent], draining from=<id>.

Walks the relative-cursor listing (each page repeats with from = the last event's id) until exhausted or limit events collected. With selected the API builds one window around that event and does not take from, so that window is all there is.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
limit int | None

The most events to return; None returns every event.

None
next str | None

What an earlier call returned as next. The token carries its listing; give what is required again, and nothing else but the limit.

None
selected str | None

The id of the event to build the list around, instead of from the start.

None
new_events_on_top bool | None

Whether to return the newest events first.

None
direction str | None

forward (the API's default) or backward, which inverts new_events_on_top.

None

Returns:

Type Description
Listing[EntityEvent]

The entity's events.

Examples:

>>> [event.id for event in tracker.entities.events_list("project", "655f13")]
['e1', 'e2']

permissions_get

permissions_get(entity_type: str, entity_id: str) -> ExtendedPermissions

GET …/extendedPermissions → access settings (acl + permissionSources).

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required

Returns:

Type Description
ExtendedPermissions

The entity's access settings.

Examples:

>>> tracker.entities.permissions_get("project", "655f15").acl.read.roles
['OWNER']

permissions_update

permissions_update(entity_type: str, entity_id: str, body: PermissionsUpdate) -> ExtendedPermissions

PATCH …/extendedPermissions — set access settings. Returns the new settings.

The acl object accepts only grant / revoke actions, each mapping an access level (READ/WRITE/GRANT) to users/groups/roles.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
body PermissionsUpdate

The acl with its grant and revoke actions.

required

Returns:

Type Description
ExtendedPermissions

The new access settings.

Examples:

>>> from ycli.yandex.tracker.entities.models import PermissionsUpdate
>>> tracker.entities.permissions_update(
...     "portfolio",
...     "pf16",
...     PermissionsUpdate.model_validate(
...         {"acl": {"grant": {"READ": {"users": ["8000000000000002"]}}}}
...     ),
... ).acl.read.users[0].id
'8000000000000002'

permissions_get_direct

permissions_get_direct(entity_type: str, entity_id: str) -> ACL

GET …/permissions → the direct READ / WRITE / GRANT rights, without inheritance.

:meth:permissions_get is the extended view (acl plus where rights are inherited from).

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required

Returns:

Type Description
ACL

The entity's direct rights.

Examples:

>>> tracker.entities.permissions_get_direct("project", "655f17").grant.roles
['AUTHOR', 'OWNER']

permissions_update_direct

permissions_update_direct(entity_type: str, entity_id: str, body: DirectPermissionsUpdate) -> ACL

PATCH …/permissions — grant and revoke direct rights. Returns the resulting rights.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
body DirectPermissionsUpdate

The rights to grant and to revoke.

required

Returns:

Type Description
ACL

The resulting direct rights.

Examples:

>>> from ycli.yandex.tracker.entities.models import ACLInput, ACLPrincipalsInput
>>> grant = ACLInput(read=ACLPrincipalsInput(users=["ann"]))
>>> update = DirectPermissionsUpdate(grant=grant)
>>> tracker.entities.permissions_update_direct("goal", "g18", update).read.users[
...     0
... ].display
'Ann'

update_bulk

update_bulk(entity_type: str, body: BulkChangeUpdate) -> BulkChangeOperation

POST …/bulkchange/_update — mass-edit entities (async). Returns the operation.

The response is a handle whose status starts at CREATED; poll :meth:bulk_get with id until it reaches a terminal status.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
body BulkChangeUpdate

The entities to change (metaEntities) and the values to set.

required

Returns:

Type Description
BulkChangeOperation

The started bulk-change operation.

Examples:

>>> from ycli.yandex.tracker.entities.models import BulkChangeUpdate
>>> tracker.entities.update_bulk(
...     "project",
...     BulkChangeUpdate.model_validate(
...         {"metaEntities": ["655f17"], "values": {"comment": "Handed over"}}
...     ),
... ).status
'CREATED'

bulk_get

bulk_get(bulk_id: str) -> BulkChangeOperation

GET /bulkchange/{bulk_id} → the current bulk-change operation status.

Parameters:

Name Type Description Default
bulk_id str

The bulk-change operation's id.

required

Returns:

Type Description
BulkChangeOperation

The operation with its current status.

Examples:

>>> tracker.entities.bulk_get("658").status
'COMPLETE'

reports_create

reports_create(body: ReportCreate) -> Entity

POST /entities/report/ — build an issue report from a {fields: …} body.

The body carries the report name plus export parameters (type/format, the issue filter and the column fields); the response is the created report entity.

Parameters:

Name Type Description Default
body ReportCreate

The report, as {"fields": {...}}.

required

Returns:

Type Description
Entity

The created report entity.

Examples:

>>> from ycli.yandex.tracker.entities.models import ReportCreate
>>> tracker.entities.reports_create(
...     ReportCreate.model_validate(
...         {
...             "fields": {
...                 "summary": "Support export",
...                 "parameters": {
...                     "type": "issueFilterExport",
...                     "format": "csv",
...                     "filter": {"query": "Queue: SUPPORT"},
...                     "fields": ["key", "summary", "assignee"],
...                 },
...             }
...         }
...     )
... ).entity_type
'report'

comments_list

comments_list(entity_type: str, entity_id: str, expand: str | None = None) -> ItemList[Comment]

GET …/comments → all comments on the entity.

expand embeds extras (html, attachments, reactions, or all).

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
expand str | None

The extras to embed.

None

Returns:

Type Description
ItemList[Comment]

The entity's comments.

Examples:

>>> tracker.entities.comments_list("project", "655f20").root[0].text
'Готово'

comments_list_relative

comments_list_relative(entity_type: str, entity_id: str, *, limit: int | None = None, next: str | None = None) -> Listing[Comment]

GET …/comments/_relative → flat ItemList[Comment], draining from=<longId>.

The paginated twin of :meth:comments_list; walks the relative-cursor listing until exhausted or limit comments collected.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
limit int | None

The most comments to return; None returns every comment.

None
next str | None

What an earlier call returned as next. The token carries its listing; give what is required again, and nothing else but the limit.

None

Returns:

Type Description
Listing[Comment]

The entity's comments.

Examples:

>>> [
...     c.id
...     for c in tracker.entities.comments_list_relative("portfolio", "pf22", limit=10)
...     .collect()
...     .items
... ]
[31, 32]

comments_get

comments_get(entity_type: str, entity_id: str, comment_id: str, expand: str | None = None) -> Comment

GET …/comments/{comment_id} → a single comment.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
comment_id str

The comment's id.

required
expand str | None

The extras to embed.

None

Returns:

Type Description
Comment

The comment.

Examples:

>>> tracker.entities.comments_get("project", "655f23", "23").text
'hi'

comments_create

comments_create(entity_type: str, entity_id: str, body: CommentCreate, *, expand: str | None = None, is_add_to_followers: bool | None = None, notify: bool | None = None, notify_author: bool | None = None) -> Comment

POST …/comments — add a comment. Returns the created comment.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
body CommentCreate

The new comment: its text and optional summonees.

required
expand str | None

The extra blocks to include in the reply.

None
is_add_to_followers bool | None

Whether to add the comment's author to the followers; None leaves the API's default (it adds).

None
notify bool | None

Whether to notify the users in the entity's fields; None leaves the API's default (it notifies).

None
notify_author bool | None

Whether to notify the author of the change; None leaves the API's default (it does not).

None

Returns:

Type Description
Comment

The created comment.

Examples:

>>> from ycli.yandex.tracker.models import CommentCreate
>>> tracker.entities.comments_create(
...     "project", "655f25", CommentCreate.model_validate({"text": "Готово"})
... ).id
22

comments_update

comments_update(entity_type: str, entity_id: str, comment_id: str, body: CommentUpdate, *, expand: str | None = None, is_add_to_followers: bool | None = None, notify: bool | None = None, notify_author: bool | None = None) -> Comment

PATCH …/comments/{comment_id} — edit a comment. Returns the updated comment.

The live v3 API only accepts the per-comment route (a PATCH on the …/comments collection answers 405), so the comment id travels in the path, not the body.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
comment_id str

The comment's id.

required
body CommentUpdate

The comment fields to change.

required
expand str | None

The extra blocks to include in the reply.

None
is_add_to_followers bool | None

Whether to add the comment's author to the followers; None leaves the API's default (it adds).

None
notify bool | None

Whether to notify the users in the entity's fields; None leaves the API's default (it notifies).

None
notify_author bool | None

Whether to notify the author of the change; None leaves the API's default (it does not).

None

Returns:

Type Description
Comment

The updated comment.

Examples:

>>> from ycli.yandex.tracker.entities.models import CommentUpdate
>>> tracker.entities.comments_update(
...     "goal", "g27", "27", CommentUpdate.model_validate({"text": "Fixed typo"})
... ).text
'Fixed typo'

comments_delete

comments_delete(entity_type: str, entity_id: str, comment_id: str, *, notify: bool | None = None, notify_author: bool | None = None) -> None

Delete a comment from an entity. Raises on non-2xx.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
comment_id str

The comment's id.

required
notify bool | None

Whether to notify the users in the entity's fields; None leaves the API's default (it notifies).

None
notify_author bool | None

Whether to notify the author of the change; None leaves the API's default (it does not).

None

Examples:

>>> tracker.entities.comments_delete("portfolio", "pf28", "28")

checklists_create

checklists_create(entity_type: str, entity_id: str, body: ItemList[ChecklistItemInput], *, expand: str | None = None, fields: str | None = None, notify: bool | None = None, notify_author: bool | None = None) -> Entity

POST …/checklistItems — add items (body is a JSON array). Returns the entity.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
body ItemList[ChecklistItemInput]

The items to add.

required
expand str | None

The extra blocks to include in the reply.

None
fields str | None

The comma-separated entity fields to include in the reply.

None
notify bool | None

Whether to notify the users in the entity's fields; None leaves the API's default (it notifies).

None
notify_author bool | None

Whether to notify the author of the change; None leaves the API's default (it does not).

None

Returns:

Type Description
Entity

The updated entity.

Examples:

>>> from ycli.yandex.tracker.entities.models import ChecklistItemInput
>>> from ycli.yandex.models import ItemList
>>> tracker.entities.checklists_create(
...     "project",
...     "655f29",
...     ItemList[ChecklistItemInput].model_validate(
...         [{"text": "Draft"}, {"text": "Review"}]
...     ),
... ).id
'655f29'

checklists_update

checklists_update(entity_type: str, entity_id: str, body: ItemList[ChecklistItemInput], *, expand: str | None = None, fields: str | None = None, notify: bool | None = None, notify_author: bool | None = None) -> Entity

PATCH …/checklistItems — replace items (body is a JSON array of {id, …}).

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
body ItemList[ChecklistItemInput]

The items to replace, each with its id.

required
expand str | None

The extra blocks to include in the reply.

None
fields str | None

The comma-separated entity fields to include in the reply.

None
notify bool | None

Whether to notify the users in the entity's fields; None leaves the API's default (it notifies).

None
notify_author bool | None

Whether to notify the author of the change; None leaves the API's default (it does not).

None

Returns:

Type Description
Entity

The updated entity.

Examples:

>>> from ycli.yandex.tracker.entities.models import ChecklistItemInput
>>> from ycli.yandex.models import ItemList
>>> tracker.entities.checklists_update(
...     "goal",
...     "g30",
...     ItemList[ChecklistItemInput].model_validate(
...         [{"id": "5f", "text": "Renamed"}, {"id": "6a", "text": "Second"}]
...     ),
... ).id
'g30'

checklists_items_update

checklists_items_update(entity_type: str, entity_id: str, item_id: str, body: ChecklistItemInput, *, expand: str | None = None, fields: str | None = None, notify: bool | None = None, notify_author: bool | None = None) -> Entity

PATCH …/checklistItems/{item_id} — edit one item. Returns the entity.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
item_id str

The checklist item's id.

required
body ChecklistItemInput

The item fields to change.

required
expand str | None

The extra blocks to include in the reply.

None
fields str | None

The comma-separated entity fields to include in the reply.

None
notify bool | None

Whether to notify the users in the entity's fields; None leaves the API's default (it notifies).

None
notify_author bool | None

Whether to notify the author of the change; None leaves the API's default (it does not).

None

Returns:

Type Description
Entity

The updated entity.

Examples:

>>> from ycli.yandex.tracker.entities.models import ChecklistItemInput
>>> tracker.entities.checklists_items_update(
...     "portfolio",
...     "pf32",
...     "1f",
...     ChecklistItemInput.model_validate({"text": "Sign off", "checked": True}),
... ).id
'pf32'

checklists_delete

checklists_delete(entity_type: str, entity_id: str, *, expand: str | None = None, fields: str | None = None, notify: bool | None = None, notify_author: bool | None = None) -> Entity

DELETE …/checklistItems — clear the whole checklist. Returns the entity.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
expand str | None

The extra blocks to include in the reply.

None
fields str | None

The comma-separated entity fields to include in the reply.

None
notify bool | None

Whether to notify the users in the entity's fields; None leaves the API's default (it notifies).

None
notify_author bool | None

Whether to notify the author of the change; None leaves the API's default (it does not).

None

Returns:

Type Description
Entity

The updated entity.

Examples:

>>> tracker.entities.checklists_delete("project", "655f34").id
'655f34'

checklists_items_delete

checklists_items_delete(entity_type: str, entity_id: str, item_id: str, *, expand: str | None = None, fields: str | None = None, notify: bool | None = None, notify_author: bool | None = None) -> Entity

DELETE …/checklistItems/{item_id} — remove one item. Returns the entity.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
item_id str

The checklist item's id.

required
expand str | None

The extra blocks to include in the reply.

None
fields str | None

The comma-separated entity fields to include in the reply.

None
notify bool | None

Whether to notify the users in the entity's fields; None leaves the API's default (it notifies).

None
notify_author bool | None

Whether to notify the author of the change; None leaves the API's default (it does not).

None

Returns:

Type Description
Entity

The updated entity.

Examples:

>>> tracker.entities.checklists_items_delete("goal", "g35", "3f").id
'g35'

checklists_move

checklists_move(entity_type: str, entity_id: str, item_id: str, body: ChecklistMove, *, expand: str | None = None, fields: str | None = None, notify: bool | None = None, notify_author: bool | None = None) -> Entity

POST …/checklistItems/{item_id}/_move — reorder an item. Returns the entity.

body is {"before": "<item id>"}.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
item_id str

The checklist item's id.

required
body ChecklistMove

The new position, as {"before": "<item id>"}.

required
expand str | None

The extra blocks to include in the reply.

None
fields str | None

The comma-separated entity fields to include in the reply.

None
notify bool | None

Whether to notify the users in the entity's fields; None leaves the API's default (it notifies).

None
notify_author bool | None

Whether to notify the author of the change; None leaves the API's default (it does not).

None

Returns:

Type Description
Entity

The updated entity.

Examples:

>>> from ycli.yandex.tracker.entities.models import ChecklistMove
>>> tracker.entities.checklists_move(
...     "portfolio", "pf36", "4f", ChecklistMove.model_validate({"before": "5a"})
... ).id
'pf36'
links_list(entity_type: str, entity_id: str, fields: str | None = None) -> ItemList[Link]

GET …/links → the entity's links to other entities.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
fields str | None

The extra link fields to include, comma-separated.

None

Returns:

Type Description
ItemList[Link]

The entity's links.

Examples:

>>> tracker.entities.links_list("project", "655f38").root[0].type
'relates'
links_create(entity_type: str, entity_id: str, body: LinkInput) -> None

Create a link (body is {relationship, entity}). Raises on non-2xx.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
body LinkInput

The link, as {"relationship": ..., "entity": ...}.

required

Examples:

>>> from ycli.yandex.tracker.entities.models import LinkInput
>>> tracker.entities.links_create(
...     "portfolio",
...     "pf40",
...     LinkInput.model_validate({"relationship": "depends on", "entity": "pf41"}),
... )
links_delete(entity_type: str, entity_id: str, right: str) -> None

Delete the link to entity right. Raises on non-2xx.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
right str

The id of the linked entity.

required

Examples:

>>> tracker.entities.links_delete("goal", "g42", "g43")

attachments_list

attachments_list(entity_type: str, entity_id: str) -> ItemList[Attachment]

GET …/attachments → files attached to the entity (metadata only).

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required

Returns:

Type Description
ItemList[Attachment]

The entity's attachments.

Examples:

>>> tracker.entities.attachments_list("project", "655f44").root[0].name
'Shops.csv'

attachments_get

attachments_get(entity_type: str, entity_id: str, file_id: str) -> Attachment

GET …/attachments/{file_id} → one attachment's metadata (name, size, download URL).

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
file_id str

The attachment's id.

required

Returns:

Type Description
Attachment

The attachment's metadata.

Examples:

>>> tracker.entities.attachments_get("goal", "g45", "45").name
'flowers.jpg'

attachments_download

attachments_download(file_id: str, filename: str) -> bytes

Download an attachment's raw bytes (a non-2xx answer raises a typed error).

Binary output is CLI/SDK-only — never an MCP payload. file_id and filename come from :meth:attachments_list / :meth:attachments_get (the id and name fields).

Parameters:

Name Type Description Default
file_id str

The attachment's id.

required
filename str

The attachment's file name.

required

Returns:

Type Description
bytes

The attachment's raw bytes.

Examples:

>>> tracker.entities.attachments_download("46", "flowers.jpg")[:4]
b'\xff\xd8\xff\xe0'

attachments_attach

attachments_attach(entity_type: str, entity_id: str, temp_file_id: str, *, expand: str | None = None, fields: str | None = None, notify: bool | None = None, notify_author: bool | None = None) -> Entity

POST …/attachments/{temp_file_id} — attach a previously uploaded temp file.

Returns the updated entity. temp_file_id is the id of a file uploaded to the temp attachments endpoint.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
temp_file_id str

The id of the uploaded temporary file.

required
expand str | None

The extra blocks to include in the reply.

None
fields str | None

The comma-separated entity fields to include in the reply.

None
notify bool | None

Whether to notify the users in the entity's fields; None leaves the API's default (it notifies).

None
notify_author bool | None

Whether to notify the author of the change; None leaves the API's default (it does not).

None

Returns:

Type Description
Entity

The updated entity.

Examples:

>>> tracker.entities.attachments_attach("portfolio", "pf47", "tmp47").id
'pf47'

attachments_delete

attachments_delete(entity_type: str, entity_id: str, file_id: str) -> None

Detach a file from an entity. Raises on non-2xx.

The live API answers with an empty body.

Parameters:

Name Type Description Default
entity_type str

The entity type (project, portfolio or goal).

required
entity_id str

The entity's id.

required
file_id str

The attachment's id.

required

Examples:

>>> tracker.entities.attachments_delete("project", "655f48", "48")

workflows

WorkflowsClient

WorkflowsClient(*, session: SyncSession)

Bases: Resource

List, get, create, update and delete workflows; read the workflows of a queue.

list

list() -> ItemList[Workflow]

GET /workflows → every workflow of the organization except deleted ones.

Returns:

Type Description
ItemList[Workflow]

The workflows.

Examples:

>>> tracker.workflows.list().root[0].name
'Design'

get

get(workflow_id: str) -> Workflow

GET /workflows/{workflow_id} → one workflow with its steps and actions.

Parameters:

Name Type Description Default
workflow_id str

The workflow's id.

required

Returns:

Type Description
Workflow

The workflow.

Examples:

>>> tracker.workflows.get("W21").version
1

list_for_queue

list_for_queue(queue_id: str) -> QueueWorkflows

GET /queues/{queue_id}/workflows → workflow id → the issue types that use it.

Parameters:

Name Type Description Default
queue_id str

The queue's key or numeric id.

required

Returns:

Type Description
QueueWorkflows

The queue's workflows, each with the issue types that use it.

Examples:

>>> tracker.workflows.list_for_queue("WFQ").root["dev"][0].key
'task'

create

create(body: WorkflowCreate) -> Workflow

POST /workflows → create a workflow from a typed WorkflowCreate body.

Parameters:

Name Type Description Default
body WorkflowCreate

The new workflow's name, initial action and steps.

required

Returns:

Type Description
Workflow

The created workflow.

Examples:

>>> from ycli.yandex.tracker.models import LocalizedName
>>> from ycli.yandex.tracker.workflows.models import (
...     WorkflowActionInput,
...     WorkflowCreate,
...     WorkflowStepInput,
... )
>>> new_workflow = WorkflowCreate(
...     id="design-flow",
...     name="Design",
...     initial_action=WorkflowActionInput(
...         name=LocalizedName(ru="Открыть", en="Open"), target="open"
...     ),
...     steps=[WorkflowStepInput(status="open")],
... )
>>> tracker.workflows.create(new_workflow).id
'design-flow'

update

update(workflow_id: str, body: WorkflowUpdate, *, version: int) -> Workflow

PATCH /workflows/{workflow_id}?version= → change the set fields of a workflow.

version is the workflow's current version (the API answers 412/428 without a matching one); the reply carries the incremented version.

Parameters:

Name Type Description Default
workflow_id str

The workflow's id.

required
body WorkflowUpdate

The fields to change.

required
version int

The workflow's current version, sent as ?version=.

required

Returns:

Type Description
Workflow

The updated workflow.

Examples:

>>> from ycli.yandex.tracker.workflows.models import WorkflowUpdate
>>> tracker.workflows.update(
...     "W21", WorkflowUpdate(name="QA process"), version=3
... ).version
4

actions_update

actions_update(workflow_id: str, status: str, action_id: str, body: WorkflowActionUpdate, *, version: int) -> Workflow

PATCH /workflows/{id}/steps/{status}/actions/{action_id}?version= → edit one action.

status is the key of the step the action leaves. Returns the whole workflow.

Parameters:

Name Type Description Default
workflow_id str

The workflow's id.

required
status str

The key of the step the action leaves.

required
action_id str

The action's id.

required
body WorkflowActionUpdate

The fields to change.

required
version int

The workflow's current version, sent as ?version=.

required

Returns:

Type Description
Workflow

The whole updated workflow.

Examples:

>>> from ycli.yandex.tracker.models import LocalizedName
>>> from ycli.yandex.tracker.workflows.models import WorkflowActionUpdate
>>> action = WorkflowActionUpdate(
...     name=LocalizedName(ru="Завершить", en="Complete"), target="closed"
... )
>>> tracker.workflows.actions_update(
...     "W23", "inProgress", "close", action, version=2
... ).version
3

delete

delete(workflow_id: str) -> None

DELETE /workflows/{workflow_id} → 204; raises on non-2xx.

Parameters:

Name Type Description Default
workflow_id str

The workflow's id.

required

Examples:

>>> tracker.workflows.delete("W24")

projects

ProjectsClient

ProjectsClient(*, session: SyncSession)

Bases: Resource

List, get, create, update and delete projects; list a project's queues.

list

list(*, expand: str | None = None) -> ItemList[Project]

GET /projects → every project of the organization.

expand="queues" adds each project's queues.

Parameters:

Name Type Description Default
expand str | None

Extra blocks to include; "queues" adds each project's queues.

None

Returns:

Type Description
ItemList[Project]

Every project.

Examples:

>>> tracker.projects.list(expand="queues").root[0].name
'Project'

get

get(project_id: int, *, expand: str | None = None) -> Project

GET /projects/{project_id} → one project.

Parameters:

Name Type Description Default
project_id int

The project's id.

required
expand str | None

Extra blocks to include, as in :meth:list.

None

Returns:

Type Description
Project

The project.

Examples:

>>> tracker.projects.get(21, expand="queues").version
1

queues_list

queues_list(project_id: int, *, expand: str | None = None) -> ItemList[Queue]

GET /projects/{project_id}/queues → the queues whose issues are in the project.

expand takes the same blocks as :meth:QueuesClient.get (all, components, …).

Parameters:

Name Type Description Default
project_id int

The project's id.

required
expand str | None

Extra queue blocks to include.

None

Returns:

Type Description
ItemList[Queue]

The project's queues.

Examples:

>>> tracker.projects.queues_list(23, expand="components,versions").root[0].key
'ORG'

create

create(body: ProjectCreate) -> Project

POST /projects → create a project from a typed ProjectCreate body.

Projects v3 is the legacy API (entities replace it): the test organization accepted queues but bound no queue, so queues of the new project came back empty, the same as for a body without it.

Parameters:

Name Type Description Default
body ProjectCreate

The new project's name and optional fields.

required

Returns:

Type Description
Project

The created project.

Examples:

>>> from ycli.yandex.tracker.projects.models import ProjectCreate
>>> tracker.projects.create(ProjectCreate(name="Launch", queues="LAUNCH")).id
'9'

update

update(project_id: int, body: ProjectUpdate, *, version: int, expand: str | None = None) -> Project

PUT /projects/{project_id}?version= → change the set fields of a project.

version is the project's current version; body.queues is required.

Parameters:

Name Type Description Default
project_id int

The project's id.

required
body ProjectUpdate

The fields to change; queues is required.

required
version int

The project's current version.

required
expand str | None

Extra blocks to include, as in :meth:list.

None

Returns:

Type Description
Project

The updated project.

Examples:

>>> from ycli.yandex.tracker.projects.models import ProjectUpdate
>>> body = ProjectUpdate(queues="EDITQ", name="Renamed")
>>> tracker.projects.update(31, body, version=5, expand="queues").version
6

delete

delete(project_id: int) -> None

DELETE /projects/{project_id} → 204; raises on non-2xx.

Parameters:

Name Type Description Default
project_id int

The project's id.

required

Examples:

>>> tracker.projects.delete(33)

gaps

GapsClient

GapsClient(*, session: SyncSession)

Bases: Resource

Create, search and delete employee absences (vacations, illness, trips, duty, …).

create

create(body: GapsCreate) -> GapCreated

POST /gaps → create up to 100 absences from a typed GapsCreate body.

Needs Tracker administrator rights. Returns the absences actually saved.

Parameters:

Name Type Description Default
body GapsCreate

The absences to create.

required

Returns:

Type Description
GapCreated

The absences actually saved.

Examples:

>>> from ycli.yandex.tracker.gaps.models import GapInput, GapsCreate, GapWorkflow
>>> gap = GapInput(
...     user="ann",
...     workflow="vacation",
...     date_from="2026-07-01T00:00:00.000Z",
...     date_to="2026-07-15T00:00:00.000Z",
... )
>>> tracker.gaps.create(GapsCreate(gaps=[gap])).gaps[0].id
'68340a1f2b4c1a3d5e7f9011'

search

search(users: Sequence[str], *, date_from: str | None = None, date_to: str | None = None, limit: int | None = None, next: str | None = None) -> Listing[UserGaps]

POST /gaps/_search (a read) → each user with the absences that overlap a window.

users are up to 100 logins or ids; the window is date_from to date_to (ISO 8601; the start defaults to now, the end must be after the start). Pages of users are joined; capped at limit users (None = all). Needs administrator rights.

Parameters:

Name Type Description Default
users Sequence[str]

The logins or ids of the users to look up.

required
date_from str | None

Window start (ISO 8601); defaults to now.

None
date_to str | None

Window end (ISO 8601); must be after the start.

None
limit int | None

The most users to return; None returns all.

None
next str | None

What an earlier call returned as next. The token carries its listing; give what is required again, and nothing else but the limit.

None

Returns:

Type Description
Listing[UserGaps]

Each user with the absences that overlap the window.

Examples:

>>> found = tracker.gaps.search(
...     ["ann", "bob"],
...     date_from="2026-07-01T00:00:00.000Z",
...     date_to="2026-08-31T23:59:59.999Z",
... )
>>> [(user.user.login, len(user.gaps)) for user in found]
[('ann', 1), ('bob', 0)]

delete

delete(gap_ids: Sequence[str]) -> None

DELETE /gaps?gapIds=… → delete absences by id (up to 100); unknown ids are ignored.

Parameters:

Name Type Description Default
gap_ids Sequence[str]

The ids of the absences to delete.

required

Examples:

>>> tracker.gaps.delete(["68340a1f2b4c1a3d5e7f9011", "68340a1f2b4c1a3d5e7f9012"])