> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/jira.md).

# Jira

Jira is a project management tool that provides ticketing/issue management.

* Knowledge base source

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector | Authentication |
| --------- | -------------- |
| Jira      | OAuth sign-in  |

#### Jira

Connect to Jira to access your projects and issues.

**Set up in Jira**

1. When the Atlassian authorization window opens, sign in to your Atlassian account.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Jira**.
2. Select **Connect**, sign in to the provider account, and review the requested access. Complete authorization to return to StackAI.
3. Complete the fields marked for use after sign-in, such as the business or account selection.
4. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required                 | What to enter                                                  |
| ------------- | ------------------------ | -------------------------------------------------------------- |
| Jira Site     | Optional / as applicable | The Atlassian Cloud site to use. Select this after signing in. |
| Site URL      | Optional / as applicable | The URL of your Jira site. Select this after signing in.       |
| Site Name     | Optional / as applicable | The name of your Jira site. Select this after signing in.      |

**Provider documentation:** [Setup reference](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/).

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **Jira** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Create Issue

Create a new issue in Jira

**Inputs**

| Field             | Type            | Required | Description                                                                                                                                                         |
| ----------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Project ID or Key | select (string) | Yes      | The ID (numeric, e.g., '10000') or key (alphanumeric, e.g., 'PROJ') of the Jira project where the issue will be created. Options load from the selected connection. |
| Issue Type ID     | select (string) | Yes      | The ID of the issue type (e.g., Bug, Task, Story). Options are loaded from the selected project. Options load from the selected connection.                         |
| Summary           | string          | Yes      | A concise summary or title for the Jira issue.                                                                                                                      |
| Description       | string          | Yes      | A detailed description of the issue (supports Atlassian Document Format).                                                                                           |
| Assignee ID       | string          | No       | The account ID of the user to assign this issue to. Optional; leave empty to leave unassigned.                                                                      |
| Parent Key        | string          | No       | The key of the parent issue (only for subtasks). Optional; leave empty for regular issues.                                                                          |
| Priority ID       | string          | No       | The ID of the priority level for this issue (e.g., 1=Highest, 3=Medium, 5=Lowest).                                                                                  |
| Labels            | array           | No       | A list of labels to attach to this issue (comma-separated).                                                                                                         |
| Due Date          | string          | No       | The due date for this issue (format: YYYY-MM-DD).                                                                                                                   |
| Component IDs     | array           | No       | A list of component IDs to associate with this issue (comma-separated).                                                                                             |
| Custom Fields     | object          | No       | A JSON object containing custom field key-value pairs.                                                                                                              |

**Outputs**

| Field     | Type   | Description                                                                |
| --------- | ------ | -------------------------------------------------------------------------- |
| Issue Key | string | The key of the created issue.                                              |
| Issue ID  | string | The ID of the created issue.                                               |
| Issue URL | string | The URL of the created issue.                                              |
| Summary   | string | The summary of the created issue.                                          |
| Status    | string | The status of the created issue.                                           |
| Message   | string | Message to be displayed to the user if the issue was created successfully. |

#### Add Issue Attachment

Add one or more file attachments to a Jira issue

**Inputs**

| Field           | Type   | Required | Description                                            |
| --------------- | ------ | -------- | ------------------------------------------------------ |
| Issue ID or Key | string | Yes      | The ID or key of the Jira issue to add attachments to. |
| File URL        | string | Yes      | The URL of the file to attach to the Jira issue.       |

**Outputs**

| Field               | Type   | Description                                                              |
| ------------------- | ------ | ------------------------------------------------------------------------ |
| Issue ID or Key     | string | The ID or key of the Jira issue that was attached to.                    |
| Issue URL           | string | The URL of the Jira issue that was attached to.                          |
| Attachment ID       | string | The ID of the created attachment.                                        |
| Attachment Filename | string | The filename of the created attachment.                                  |
| Attachment URL      | string | The URL of the created attachment.                                       |
| Message             | string | A message indicating the success or failure of the attachment operation. |

#### Add Issue Comment

Add a comment to a Jira issue

**Inputs**

| Field           | Type     | Required | Description                                          |
| --------------- | -------- | -------- | ---------------------------------------------------- |
| Issue ID or Key | string   | Yes      | The ID of the Jira issue to add a comment to.        |
| Comment Text    | textarea | Yes      | The text content of the comment to add to the issue. |

**Outputs**

| Field           | Type   | Description                                                |
| --------------- | ------ | ---------------------------------------------------------- |
| Jira Comment ID | string | The ID of the comment that was added to the issue.         |
| Jira Issue URL  | string | The URL of the Jira issue that was commented on.           |
| Message         | string | A message indicating the success or failure of the action. |

#### Link Jira Issues

Create a link between two Jira issues with an optional comment

**Inputs**

| Field                | Type     | Required | Description                                                                         |
| -------------------- | -------- | -------- | ----------------------------------------------------------------------------------- |
| From Issue ID or Key | string   | Yes      | The ID or key of the source issue in the link relationship.                         |
| To Issue ID or Key   | string   | Yes      | The ID or key of the target issue in the link relationship.                         |
| Link Type            | string   | Yes      | The type of link relationship between the issues (e.g., Duplicate, Block, Relates). |
| Comment Text         | textarea | No       | Optional comment to add to the source issue about the link.                         |

**Outputs**

| Field              | Type   | Description                                            |
| ------------------ | ------ | ------------------------------------------------------ |
| Outward Jira Issue | object | The outward Jira issue that was linked.                |
| Inward Jira Issue  | object | The inward Jira issue that was linked.                 |
| Jira Link Type     | string | The type of link relationship between the issues.      |
| Operation Message  | string | A message describing the result of the link operation. |

#### Create User

Create a new user in Jira with email and product access

**Inputs**

| Field         | Type            | Required | Description                                                                                                                                |
| ------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Jira Site     | select (string) | Yes      | The Jira site where you want to create the user. Options are loaded from the connected account. Options load from the selected connection. |
| Email Address | string          | Yes      | The email address of the user to create in Jira.                                                                                           |
| Display Name  | string          | No       | The display name of the user to create in Jira.                                                                                            |
| Username      | string          | No       | The username of the user to create in Jira.                                                                                                |

**Outputs**

| Field     | Type   | Description                        |
| --------- | ------ | ---------------------------------- |
| User ID   | string | The ID of the created Jira user.   |
| User Name | string | The name of the created Jira user. |
| User URL  | string | The URL of the created Jira user.  |

#### Get Issue

Retrieve details for a Jira issue

**Inputs**

| Field                     | Type    | Required | Description                                                                               |
| ------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------- |
| Issue ID or Key           | string  | Yes      | The ID or key of the Jira issue to retrieve.                                              |
| Fields to Include         | string  | No       | Comma-separated list of fields to return (defaults to all fields).                        |
| Expand Options            | string  | No       | Additional information to include in the response.                                        |
| Update History            | boolean | No       | Whether to update the user's recently viewed project list.                                |
| Custom Field IDs          | string  | No       | A comma-separated list of custom field IDs to extract from the issue.                     |
| Include All Custom Fields | boolean | No       | Whether to include all custom fields for exploration (WARNING: creates very long output). |

**Outputs**

| Field           | Type   | Description                                                                          |
| --------------- | ------ | ------------------------------------------------------------------------------------ |
| Issue ID or Key | string | The ID or key of the Jira issue.                                                     |
| Issue           | object | The details of the Jira issue.                                                       |
| Changelog       | array  | The field change history of the Jira issue (requires 'changelog' in Expand Options). |
| Expanded Data   | object | The data returned for the requested Expand Options, keyed by option name.            |

#### Get Issue Comments

Retrieve comments for a Jira issue

**Inputs**

| Field                | Type    | Required | Description                                                           |
| -------------------- | ------- | -------- | --------------------------------------------------------------------- |
| Jira Issue ID or Key | string  | Yes      | The ID or key of the Jira issue to retrieve comments for.             |
| Start At             | integer | No       | The index of the first comment to return (pagination). Defaults to 0. |
| Max Results          | integer | No       | The maximum number of comments to return. Defaults to 100.            |
| Order By             | string  | No       | Sort order for comments (created, -created, +created).                |
| Expand               | string  | No       | Additional information to include in the response.                    |

**Outputs**

| Field           | Type   | Description                      |
| --------------- | ------ | -------------------------------- |
| Issue ID or Key | string | The ID or key of the Jira issue. |
| Comments        | array  | The comments for the Jira issue. |

#### Get Project

Get a specific Jira project by its ID or key

**Inputs**

| Field             | Type            | Required | Description                                                                   |
| ----------------- | --------------- | -------- | ----------------------------------------------------------------------------- |
| Project ID or Key | select (string) | Yes      | The ID or key of the Jira project. Options load from the selected connection. |
| Expand            | string          | No       | Additional information to include in the response.                            |

**Outputs**

| Field               | Type   | Description                          |
| ------------------- | ------ | ------------------------------------ |
| Project ID          | string | The ID of the Jira project.          |
| Project Key         | string | The key of the Jira project.         |
| Project Name        | string | The name of the Jira project.        |
| Project Category    | object | The category of the Jira project.    |
| Project Description | string | The description of the Jira project. |
| Project Lead        | string | The lead of the Jira project.        |
| Project Issue Types | array  | The issue types of the Jira project. |
| Project URL         | string | The URL of the Jira project.         |
| Project Keys        | array  | The keys of the Jira project.        |

#### List Projects

Search and list Jira projects with filtering options

**Inputs**

| Field          | Type    | Required | Description                                                           |
| -------------- | ------- | -------- | --------------------------------------------------------------------- |
| Start At       | integer | No       | The index of the first project to return (pagination). Defaults to 0. |
| Max Results    | integer | No       | The maximum number of projects to return. Defaults to 50.             |
| Order By       | string  | No       | Field to sort results by (prefix with - or + for direction).          |
| Query          | string  | No       | Text search for matching project name or key.                         |
| Project Type   | string  | No       | Filter by project type (comma-separated).                             |
| Project Status | string  | No       | Filter by project status (comma-separated).                           |
| Expand         | string  | No       | Additional information to include in the response.                    |

**Outputs**

| Field          | Type    | Description                               |
| -------------- | ------- | ----------------------------------------- |
| Total Projects | number  | The total number of projects.             |
| Start At       | number  | The index of the first project to return. |
| Max Results    | number  | The maximum number of projects to return. |
| Is Last        | boolean | Whether this is the last page of results. |
| Projects       | array   | A list of Jira projects.                  |

#### Search Tickets with JQL

Search for Jira tickets using JQL or get recent tickets

**Inputs**

| Field             | Type   | Required | Description                                                                        |
| ----------------- | ------ | -------- | ---------------------------------------------------------------------------------- |
| JQL Query         | string | No       | Jira Query Language (JQL) query to search for issues.                              |
| Results Requested | string | No       | Number of issues to return (number or 'ALL' for all matching issues). Default: 50. |
| Order By          | string | No       | Field to order results by (e.g., 'created DESC', 'updated ASC').                   |
| Fields to Include | array  | No       | Fields to include in the response.                                                 |

**Outputs**

| Field            | Type   | Description                                                             |
| ---------------- | ------ | ----------------------------------------------------------------------- |
| Issues           | array  | List of Jira issues matching the search criteria.                       |
| Total Count      | number | Total number of issues matching the search (may be more than returned). |
| Results Returned | number | Number of issues returned in this response.                             |
| Message          | string | Summary message about the search results.                               |

#### Search Users

Search for users in Jira that can be mentioned in tickets

**Inputs**

| Field        | Type            | Required | Description                                                                                                                                 |
| ------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Jira Site    | select (string) | Yes      | The Jira site where you want to search for users. Options are loaded from the connected account. Options load from the selected connection. |
| Search Query | string          | Yes      | Search term to find users by name, email, or username.                                                                                      |
| Max Results  | integer         | No       | The maximum number of users to return. Defaults to 50.                                                                                      |

**Outputs**

| Field         | Type   | Description                        |
| ------------- | ------ | ---------------------------------- |
| Users         | array  | List of users found in the search. |
| Total Results | number | Total number of users found.       |

#### Update Issue

Update an existing Jira issue's fields and properties

**Inputs**

| Field                | Type     | Required | Description                                               |
| -------------------- | -------- | -------- | --------------------------------------------------------- |
| Issue ID or Key      | string   | Yes      | The ID or key of the Jira issue to update.                |
| Summary              | string   | No       | New summary (title) for the issue.                        |
| Description          | textarea | No       | New description for the issue.                            |
| Add Labels           | string   | No       | Comma-separated list of labels to add to the issue.       |
| Remove Labels        | string   | No       | Comma-separated list of labels to remove from the issue.  |
| Assignee             | string   | No       | Account ID of the user to assign the issue to.            |
| Priority             | string   | No       | ID of the priority to set for the issue.                  |
| Custom Fields        | string   | No       | JSON string of custom fields to update.                   |
| Notify Users         | boolean  | No       | Whether to send email notifications about the update.     |
| Return Updated Issue | boolean  | No       | Whether to return the full updated issue in the response. |

**Outputs**

| Field    | Type   | Description                                                     |
| -------- | ------ | --------------------------------------------------------------- |
| Issue ID | string | The ID of the Jira issue.                                       |
| Issue    | dict   | The updated Jira issue, Only returned if return\_issue is true. |
| Message  | string | A message indicating the success or failure of the update.      |

#### List Issue Types

List all available Jira issue types or filter by project

**Inputs**

| Field             | Type            | Required | Description                                                                                                                                                                                                  |
| ----------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Project ID or Key | select (string) | No       | The ID (numeric, e.g., '10000') or key (alphanumeric, e.g., 'PROJ') of the Jira project to filter issue types. If not provided, all issue types will be returned. Options load from the selected connection. |

**Outputs**

| Field       | Type  | Description                 |
| ----------- | ----- | --------------------------- |
| Issue Types | array | A list of Jira issue types. |

#### Get Issue Subtasks

Get all subtasks for a specific Jira issue

**Inputs**

| Field                  | Type   | Required | Description                                                                            |
| ---------------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| Parent Issue ID or Key | string | Yes      | The ID or key of the parent issue to get subtasks for.                                 |
| Results Requested      | string | No       | Number of subtasks to return (number or 'ALL' for all matching subtasks). Default: 50. |
| Order By               | string | No       | Field to order results by (e.g., 'created DESC', 'updated ASC').                       |
| Fields to Include      | array  | No       | Fields to include in the response.                                                     |

**Outputs**

| Field            | Type   | Description                                         |
| ---------------- | ------ | --------------------------------------------------- |
| Subtasks         | array  | List of Jira subtasks matching the search criteria. |
| Total Count      | number | Total number of subtasks found.                     |
| Results Returned | number | Number of subtasks returned in this response.       |
| Message          | string | Summary message about the search results.           |

#### Create Project

Create a new Jira project

**Inputs**

| Field                | Type            | Required | Description                                                                                                |
| -------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| Project Key          | string          | Yes      | Unique project key, used as the prefix of issue keys.                                                      |
| Project Name         | string          | Yes      | The name of the project.                                                                                   |
| Project Type         | select (string) | Yes      | The type of project, which defines its features. Available values: Software, Service Management, Business. |
| Project Lead         | select (string) | Yes      | Select the project lead or enter their account ID. Options load from the selected connection.              |
| Description          | textarea        | No       | A brief description of the project.                                                                        |
| Project Template Key | string          | No       | Template used to create the project.                                                                       |
| Default Assignee     | select (string) | No       | Default assignee for new issues in the project. Available values: Project Lead, Unassigned.                |
| Project Info URL     | string          | No       | A link to information about the project.                                                                   |
| Category ID          | integer         | No       | The ID of the project's category.                                                                          |

**Outputs**

| Field       | Type   | Description                                       |
| ----------- | ------ | ------------------------------------------------- |
| Project ID  | string | The ID of the created Jira project.               |
| Project Key | string | The key of the created Jira project.              |
| Project URL | string | The URL of the created Jira project.              |
| Message     | string | A message indicating the result of the operation. |

#### Update Project

Update an existing Jira project's details

**Inputs**

| Field                   | Type            | Required | Description                                                                                 |
| ----------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------- |
| Project ID or Key       | select (string) | Yes      | The ID or key of the Jira project to update. Options load from the selected connection.     |
| Project Name            | string          | No       | New name for the project.                                                                   |
| Project Key             | string          | No       | New project key.                                                                            |
| Description             | textarea        | No       | New description for the project.                                                            |
| Project Lead Account ID | string          | No       | Account ID of the new project lead.                                                         |
| Default Assignee        | select (string) | No       | Default assignee for new issues in the project. Available values: Project Lead, Unassigned. |
| Project Info URL        | string          | No       | A link to information about the project.                                                    |
| Category ID             | integer         | No       | The ID of the project's category.                                                           |
| Expand                  | string          | No       | Additional information to include in the response.                                          |

**Outputs**

| Field               | Type   | Description                          |
| ------------------- | ------ | ------------------------------------ |
| Project ID          | string | The ID of the Jira project.          |
| Project Key         | string | The key of the Jira project.         |
| Project Name        | string | The name of the Jira project.        |
| Project Category    | object | The category of the Jira project.    |
| Project Description | string | The description of the Jira project. |
| Project Lead        | string | The lead of the Jira project.        |
| Project Issue Types | array  | The issue types of the Jira project. |
| Project URL         | string | The URL of the Jira project.         |
| Project Keys        | array  | The keys of the Jira project.        |

### Important behavior

If an operation is denied, check the connection’s granted permissions and the account’s access in the provider. Reauthorize the connection when it needs additional permissions.

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/jira.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
