# youtrack-rest

> Interage com o YouTrack via REST API para operações que o MCP oficial não cobre, como boards, sprints, relatórios de tempo, anexos e comandos em lote. Requer YOUTRACK_BASE_URL e token.

- Skill: `pwdev-solucoes/youtrack-rest` (Agent Skill)
- Install (CLI): `npx skillmds add pwdev-solucoes/youtrack-rest`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pwdev-solucoes/youtrack-rest/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity, Integrations & APIs, REST & GraphQL APIs, Task Management
- Tags: Agile Boards, Attachments, Batch Commands, Rest Api, Sprints, Time Tracking, Youtrack
- Author: pwdev-solucoes (https://skillmd.com/u/pwdev-solucoes)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/pwdev-solucoes/youtrack-rest

---


# YouTrack REST (fallback)

Você cobre o que o MCP oficial não expõe, chamando a REST API direto.

## Ferramenta única

**Todo acesso REST passa por `${CLAUDE_PLUGIN_ROOT}/scripts/yt-api.sh`**:

```sh
yt-api.sh GET  "/api/agiles?fields=id,name&\$top=50"
yt-api.sh POST "/api/commands" '{"query":"State Fixed","issues":[{"idReadable":"PROJ-1"}]}'
```

**Proibido** montar `curl` com `$YOUTRACK_TOKEN` inline — um erro de citação ou
`set -x` vazaria o token no transcript. O helper monta o header internamente.

## Degradação

Sem config (`check-setup.sh` acusa ausência): não execute. Entregue o comando
modelo com placeholder e aponte `/pwdev-youtrack:init`. Env var nova exige
reiniciar a sessão.

## Convenções da API

- `fields=` **obrigatório** — sem ele a resposta vem só com `id`. Seleção
  aninhada: `fields=id,name,sprints(id,name)`.
- Paginação `$top`/`$skip` em toda lista (padrão do servidor é ~42 itens).
- Boards e sprints usam **ID interno** (`105-2`) — liste primeiro para obter;
  issues aceitam ID legível (`PROJ-123`).
- Erros: 401 token · 403 permissão · 404 ID interno vs legível · 400 `fields=`
  ou JSON malformado.

## Receitas por intenção

| Intenção | Caminho |
|---|---|
| Listar boards | `GET /api/agiles?fields=id,name,projects(shortName)` |
| Sprints de um board | `GET /api/agiles/{id}/sprints?fields=id,name,start,finish,archived` |
| Issues de um sprint | busca `Board <nome>: {<sprint>}` (REST ou MCP `search_issues`) |
| Mover issue para sprint | `POST /api/commands` query `Board <nome> <sprint>` |
| Comando em lote | `POST /api/commands` com várias issues |
| Work items (leitura) | `GET /api/issues/{id}/timeTracking/workItems?fields=...` |
| Anexos | `GET/POST /api/issues/{id}/attachments` (upload multipart) |

Receitas completas com exemplos prontos:
`${CLAUDE_PLUGIN_ROOT}/references/rest-api.md`.

## Regras

- **Mutação (`POST`/`DELETE`) só com o comando à vista e confirmação** —
  especialmente `/api/commands`, que altera várias issues de uma vez.
- Leitura (`GET`) roda livre.
- Não substitua o MCP no que o MCP cobre (issues CRUD, comentários, artigos,
  log_work) — ver skill `youtrack`.
- Datas de work item são epoch ms UTC — converta antes de exibir.

## Limites

- Não administra a instância (usuários, permissões, workflows)
- Não deleta boards nem sprints
- Não faz upload de arquivo sem o usuário indicar o caminho explicitamente

## Skills relacionadas

`youtrack` — dia a dia de issues via MCP oficial