# Jira

Lets an agent read and manage Jira Cloud issues, sprints, and boards.

## What it can do

| Method | What it does |
| --- | --- |
| `jira_list_projects` | List Jira projects accessible to the user. Call this first to discover project keys before searching issues or users. |
| `jira_search` | Search Jira with JQL. Returns issues, total, issue_keys. Use keys with jira_get_issue. |
| `jira_get_issue` | Get one issue by key (PROJ-123). |
| `jira_create_issue` | Create issue with optional priority (Highest/High/Medium/Low/Lowest), due_date (YYYY-MM-DD), labels, and assignee_account_id. |
| `jira_add_comment` | Add plain-text comment to issue. |
| `jira_edit_issue` | Edit issue fields: summary, description, priority, due_date, labels. Only provided fields are updated, others stay unchanged. |
| `jira_get_transitions` | List status transitions; use id in jira_transition_issue. |
| `jira_transition_issue` | Change status; transition_id from jira_get_transitions. |
| `jira_search_users` | Search users assignable to a project. Paginates through ALL users. Returns display_name, account_id, email (if visible). If multiple users match the query, all are returned - check display_name to pick the right one. … |
| `jira_list_boards` | List Jira Software agile boards; filter by project_key_or_id. |
| `jira_list_sprints` | List sprints on a board; state can be future / active / closed. |
| `jira_add_issues_to_sprint` | Add a list of issues to a sprint by sprint_id. |
| `jira_assign_to_sprint` | Add one issue to a sprint (sprint cannot be set via jira_edit_issue). |
| `jira_batch_assign_sprint` | Bulk-add issues to a sprint (same endpoint as jira_add_issues_to_sprint). |
| `jira_get_active_sprints` | Active sprints on a board only. |
| `jira_move_issues_to_backlog` | Move issues back to the board's backlog. |
| `jira_remove_issues_from_sprint` | Remove issues from a sprint. |
| `jira_list_issue_link_types` | List issue link type names - use them in jira_create_issue_link.link_type_name. |
| `jira_create_issue_link` | Link two issues; first call jira_list_issue_link_types for the type name. |
| `jira_assign_issue` | Assign an assignee only (account_id from jira_search_users, or email). |

## How to get credentials

1. Go to
   [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
2. **Create API token**, name it, copy the value.
3. Note your Jira domain - it's the part before `.atlassian.net`
   in your Jira URL (e.g. `yourcompany`).

## Fields to fill in FlyMyAI

| FlyMyAI field | Where it comes from |
| --- | --- |
| `JIRA_DOMAIN` | `yourcompany.atlassian.net` (no `https://`) |
| `JIRA_EMAIL` | Your Atlassian account email |
| `JIRA_API_TOKEN` | Atlassian → Security → API tokens |
| `JIRA_PROJECT_KEY` *(optional)* | e.g. `SCRUM` - used as default for JQL |

## Troubleshooting

- **401** - email doesn't match the token owner, or the token was
  deleted.
- **`jira_edit_issue` fails to assign** - use `jira_assign_issue`
  instead; `edit` doesn't accept assignee.
- **Sprint actions fail on a team-managed project** - team-managed
  Scrum projects need the agile endpoints; some classic-only
  parameters aren't accepted.

## Links

- [Atlassian API tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
- [Jira Cloud REST API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/)