Yandex Tracker

Skill and helper script for working with Yandex Tracker through the public REST API.

Repository Contents

• SKILL.md defines the skill behavior, routing rules, and documentation workflow.
• scripts/tracker_api.py is a stdlib-only CLI for authenticated Tracker API requests.
• scripts/tracker_scenario.py runs reusable JSON-described API scenarios with variables, saved outputs, and assertions.
• scripts/tracker_typed_ops.py provides guarded typed operations for common project, portfolio, board, and bulk-search workflows.
• examples/ contains ready-to-run scenario files.
• references/tracker-api.md summarizes the core API contract and common pitfalls.
• references/documentation-pages.md maps API task areas to the local API reference index.
• references/recommended-api-scenarios.md contains the recommended operating scenarios for API integrations.
• references/support-docs-index.md maps product and UI questions to the current locally captured support-doc hierarchy.
• references/tracker-docs-site-map.md is the full Playwright-generated site map of the Tracker documentation menu.

Requirements

• Python 3.11+
• A Yandex Tracker token:
  • TRACKER_TOKEN or TRACKER_OAUTH_TOKEN
  • TRACKER_IAM_TOKEN
• Exactly one organization header source:
  • TRACKER_TRACKER_ORG_ID or TRACKER_ORG_ID
  • TRACKER_CLOUD_ORG_ID

Quick Start

Inspect the current user:

TRACKER_TOKEN=... TRACKER_TRACKER_ORG_ID=... ./scripts/tracker_api.py /myself

Fetch an issue:

TRACKER_TOKEN=... TRACKER_TRACKER_ORG_ID=... ./scripts/tracker_api.py /issues/TEST-1

Search issues:

TRACKER_TOKEN=... TRACKER_TRACKER_ORG_ID=... ./scripts/tracker_api.py /issues/_search \
  --method POST \
  --data '{"filter":{"queue":"TEST"}}'

Send query parameters and print headers:

TRACKER_TOKEN=... TRACKER_TRACKER_ORG_ID=... ./scripts/tracker_api.py /queues \
  --query perPage=100 \
  --include-status

tracker_api.py

The helper script:

• uses https://api.tracker.yandex.net/v3 by default
• sends Authorization and exactly one organization header
• supports --method, --query, --data, --data-file, --header, --raw, and --include-status
• pretty-prints JSON responses by default
• exits non-zero on HTTP errors and still prints the error body

tracker_scenario.py

Use the scenario runner when a task is better expressed as a repeatable workflow than as one-off curl commands.

What it supports:

• scenario file in JSON
• {{var}} substitution from environment, scenario vars, and --var key=value
• multiple sequential steps
• per-step request method, path, query, headers, body, or body_file
• status assertions and simple JSON-path-like assertions
• saving response values into variables for later steps
• conditional cleanup steps via when

Example:

TRACKER_TOKEN=... TRACKER_ORG_ID=... ./scripts/tracker_scenario.py \
  examples/entities-project-in-portfolio.json \
  --var portfolio_id=123456 \
  --var project_summary="Infrastructure rollout" \
  --var delete_after_create=true

Minimal scenario shape:

{
  "name": "Example scenario",
  "vars": {
    "issue_key": "TEST-1"
  },
  "steps": [
    {
      "name": "Read issue",
      "request": {
        "method": "GET",
        "path": "/issues/{{issue_key}}"
      },
      "expect": {
        "status": 200,
        "json": {
          "$.key": "TEST-1"
        }
      }
    }
  ]
}

Recommended starter scenarios:

• examples/bootstrap-discovery.json for auth, org, and queue reachability checks
• examples/issues-search-and-read.json for safe issue selection through POST search
• examples/issue-transition-check.json for read-before-transition workflow checks
• examples/entities-project-in-portfolio.json for the locally validated Entities API create flow

tracker_typed_ops.py

Use the typed helper when an operation has known Tracker-specific sharp edges. Mutating commands are dry-run by default; pass --execute only after inspecting the printed request. Mutation commands also write a local JSON report under reports/ with created, updated, deleted, skipped, and failed items.

Supported commands:

• create-portfolio: creates POST /entities/portfolio with business data under fields.
• create-project: creates POST /entities/project with fields.summary, optional fields.description, and optional fields.parentEntity; warns that Tracker may create a project board as a product-side effect.
• attach-issue-to-project: patches an issue with {"project":{"id":"<shortId>"}}; this expects the project shortId, not the entity id.
• list-boards-filtered: fetches /boards with optional query parameters, filters by exact name, prefix, or substring, and prints only selected fields such as id,name,createdAt.
• delete-board: deletes one board only when its current name exactly matches --name-exact; dry-run unless --execute is passed.
• read-entity-expanded: reads /entities/<type>/<id> and tries an entity _search fallback when the direct read only returns wrapper metadata.
• verify-issue-project-links: checks that an issue is attached to the expected project short id.
• verify-no-boards-by-prefix: fails if any board still matches a prefix.
• search-pages: POSTs to a _search endpoint with perPage, detects repeated pages, and stops instead of looping indefinitely.

Examples:

TRACKER_TOKEN=... TRACKER_ORG_ID=... ./scripts/tracker_typed_ops.py create-project \
  --summary "SDK launch" \
  --parent-entity 123456

TRACKER_TOKEN=... TRACKER_ORG_ID=... ./scripts/tracker_typed_ops.py --execute attach-issue-to-project \
  --issue DEV-1 \
  --project-short-id 28

TRACKER_TOKEN=... TRACKER_ORG_ID=... ./scripts/tracker_typed_ops.py list-boards-filtered \
  --name-prefix "Доска проекта запуск SDK" \
  --fields id,name,createdAt

Documentation Workflow

Use only the local markdown references:

1. Read references/tracker-api.md for API mechanics, headers, and update semantics.
2. Read references/documentation-pages.md to find the exact API family or method area.
3. Read references/support-docs-index.md for product behavior and UI workflows.
4. Use references/tracker-docs-site-map.md when you need the full documentation tree or need to verify exact menu placement.
5. If something seems missing, search the local .md files in references/ instead of using the live Tracker site.

Notes

• Status changes in Tracker are transitions, not ordinary issue field updates.
• Complex searches usually go through POST-based search endpoints.
• Attachments often require a temporary upload step before linking them to an issue or comment.
• API permissions match the rights of the represented user.
• Complex fields such as project, epic, and sprint often require nested object payloads rather than simple strings or numbers.
• For mass updates, validate one object first, then roll out in small batches with read-after-write verification.
• Links and dependencies are managed through dedicated /links endpoints and removed by link id, not by patching the issue body.
• Not every board supports sprint APIs; verify board capabilities before automating sprint assignment.
• Entity id and project shortId are different. Use the entity id for /entities/project/<id> and fields.parentEntity; use the project shortId for the issue project.id field.
• GET /entities/portfolio/<id> may return only wrapper metadata. Use an expanded entity read/search flow when business fields such as summary, description, or parentEntity matter.
• Creating a project entity can create a Tracker board as a product-side effect. Check boards by prefix after bulk project creation when this matters.
• Prefer stdlib-only tooling in this repository over external Python dependencies such as requests.

License

MIT. See LICENSE.