# Jira

> Manage Jira issues including creating, searching, commenting, and transitioning issues using the Jira Cloud REST API v3.

Source: https://cotera.co/docs/reference/tools/individual-tools/jira

---

**Authentication Type:** API Key (Basic Auth)
**Description:** Manage Jira issues including creating, searching, commenting, and transitioning issues using the Jira Cloud REST API v3.

***

## Authentication

To authenticate, you'll need your Atlassian account credentials:

1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens) and create a new API token
2. Note your Atlassian account email address
3. Note your Jira domain (e.g., `yourcompany` from `yourcompany.atlassian.net`)

You'll need to provide:

* **email**: Your Atlassian account email
* **apiToken**: Your Atlassian API token
* **domain**: Your Jira domain (e.g., `yourcompany`)

***

## Issues

Operations for managing Jira issues.

### Create Issue

Create a new issue in a Jira project. Supports setting the issue type, description, assignee, priority, and labels.

**Operation Type:** Mutation (Write)

**Parameters:**

* **projectKey** `string` (required): The project key (e.g., "PROJ", "ENG")
* **summary** `string` (required): The issue summary/title
* **issueType** `string` (default: "Task"): The issue type name (e.g., "Task", "Bug", "Story", "Epic")
* **description** `string` (nullable): Plain text description of the issue
* **assigneeAccountId** `string` (nullable): The Atlassian account ID of the assignee
* **priority** `string` (nullable): Priority name (e.g., "Highest", "High", "Medium", "Low", "Lowest")
* **labels** `string[]` (default: \[]): Labels to apply to the issue

**Returns:**

* **id** `string`: The issue ID
* **key** `string`: The issue key (e.g., "PROJ-123")
* **url** `string`: The web URL of the created issue

**Example Usage:**

```json
{
  "projectKey": "ENG",
  "summary": "Fix login page timeout error",
  "issueType": "Bug",
  "description": "Users are experiencing timeout errors when attempting to log in during peak hours.",
  "assigneeAccountId": null,
  "priority": "High",
  "labels": ["frontend", "auth"]
}
```

### Get Issue

Retrieve detailed information about a specific Jira issue including its status, assignee, description, and metadata.

**Operation Type:** Query (Read)

**Parameters:**

* **issueIdOrKey** `string` (required): The issue ID or key (e.g., "PROJ-123" or "10001")

**Returns:**

* **id** `string`: The issue ID
* **key** `string`: The issue key
* **summary** `string`: The issue summary
* **description** `string` (nullable): Plain text description
* **status** `string`: Current status name
* **statusCategory** `string`: Status category (To Do, In Progress, Done)
* **assignee** `string` (nullable): Assignee display name
* **assigneeAccountId** `string` (nullable): Assignee account ID
* **reporter** `string` (nullable): Reporter display name
* **priority** `string` (nullable): Priority name
* **issueType** `string`: Issue type name
* **labels** `string[]`: Labels
* **created** `string`: Created timestamp
* **updated** `string`: Last updated timestamp
* **url** `string`: Web URL of the issue

**Example Usage:**

```json
{
  "issueIdOrKey": "ENG-456"
}
```

### Search Issues

Search for issues using JQL (Jira Query Language) with configurable fields and pagination.

**Operation Type:** Query (Read)

**Parameters:**

* **jql** `string` (required): JQL query string (e.g., `project = PROJ AND status = 'In Progress'`)
* **fields** `string[]` (default: \["summary", "status", "assignee", "priority", "issuetype", "created", "updated"]): Fields to return
* **maxResults** `number` (default: 50): Maximum number of results (max 100)

**Returns:**

* **issues** `array of objects`: Matching issues
  * **id** `string`: The issue ID
  * **key** `string`: The issue key
  * **summary** `string`: The issue summary
  * **status** `string`: Current status name
  * **assignee** `string` (nullable): Assignee display name
  * **priority** `string` (nullable): Priority name
  * **issueType** `string`: Issue type name
  * **created** `string`: Created timestamp
  * **updated** `string`: Last updated timestamp
* **total** `number`: Total number of matching issues

**Example Usage:**

```json
{
  "jql": "project = ENG AND status = 'In Progress' AND assignee = currentUser()",
  "fields": ["summary", "status", "assignee", "priority", "issuetype", "created", "updated"],
  "maxResults": 25
}
```

***

## Comments

Operations for managing comments on Jira issues.

### Add Comment

Add a comment to a Jira issue.

**Operation Type:** Mutation (Write)

**Parameters:**

* **issueIdOrKey** `string` (required): The issue ID or key (e.g., "PROJ-123")
* **body** `string` (required): The comment text

**Returns:**

* **id** `string`: The comment ID
* **author** `string` (nullable): Author display name
* **created** `string`: Created timestamp

**Example Usage:**

```json
{
  "issueIdOrKey": "ENG-456",
  "body": "Deployed the fix to staging. Ready for QA review."
}
```

***

## Transitions

Operations for transitioning Jira issues between statuses.

### Transition Issue

Transition a Jira issue to a new status. If no transition is specified, returns the list of available transitions without executing any change.

**Operation Type:** Mutation (Write)

**Parameters:**

* **issueIdOrKey** `string` (required): The issue ID or key (e.g., "PROJ-123")
* **transitionId** `string` (nullable): The transition ID to execute. If null, returns available transitions without executing.
* **transitionName** `string` (nullable): The transition name to execute (e.g., "In Progress", "Done"). Used if transitionId is null.

**Returns:**

* **success** `boolean`: Whether the transition was executed (false if only listing transitions)
* **availableTransitions** `array of objects`: Available transitions for this issue
  * **id** `string`: The transition ID
  * **name** `string`: The transition name
  * **toStatus** `string`: The target status name

**Example Usage:**

List available transitions:

```json
{
  "issueIdOrKey": "ENG-456",
  "transitionId": null,
  "transitionName": null
}
```

Transition by name:

```json
{
  "issueIdOrKey": "ENG-456",
  "transitionId": null,
  "transitionName": "Done"
}
```

***

## Common Use Cases

**Issue Tracking & Management:**

* Create issues for bugs, tasks, and stories with detailed descriptions and labels
* Search across projects using JQL to find issues by status, assignee, or priority
* Get full issue details including status, assignee, and description for reporting

**Workflow Automation:**

* Transition issues through workflow stages as work progresses
* Add comments to issues to log updates, decisions, or automated notifications
* Search for stale issues using JQL date queries and transition or comment on them

**Cross-Tool Integration:**

* Create Jira issues from customer support tickets or CRM data
* Search for issues related to specific customers or projects
* Add comments to issues with context from other tools like Slack or Confluence