> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira

> Give agents authenticated access to the Jira Cloud REST API.

The `@guildai-services/guildai~jira` package provides agents with access to the Jira Cloud REST API through Guild's OAuth 2.0 integration.

## Authentication

* **Type:** OAuth 2.0 (Atlassian Cloud)
* **Token expiration:** 1 hour (auto-refreshed)
* **Refresh token expiration:** 90 days
* **Note:** Only Jira Cloud is supported — not Jira Server or Data Center

### Setup

<Steps>
  <Step title="Open Credentials">Go to **Credentials** in Guild.</Step>
  <Step title="Connect Jira">Click **Jira** and authorize access through Atlassian.</Step>
  <Step title="Grant access">Select your Jira site. Guild automatically retrieves your Cloud ID.</Step>
</Steps>

## Usage

```typescript theme={null}
import { jiraTools } from "@guildai-services/guildai~jira"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that manages Jira issues",
  tools: { ...jiraTools },
})
```

### Selecting specific tools

Agents perform better with fewer tools. Use `pick()` to include only what your agent needs. Tools are named with the `jira_` prefix — for example, `get_issue` becomes `jira_get_issue`.

```typescript theme={null}
import { jiraTools } from "@guildai-services/guildai~jira"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that triages Jira bugs",
  tools: {
    ...pick(jiraTools, [
      "jira_search_and_reconsile_issues_using_jql",
      "jira_get_issue",
      "jira_edit_issue",
      "jira_add_comment",
    ]),
  },
})
```

## API endpoints

<AccordionGroup>
  <Accordion title="Projects">
    | Operation                | Method | Path                                              |
    | ------------------------ | ------ | ------------------------------------------------- |
    | `get_all_projects`       | GET    | `/rest/api/3/project`                             |
    | `create_project`         | POST   | `/rest/api/3/project`                             |
    | `get_project`            | GET    | `/rest/api/3/project/{projectIdOrKey}`            |
    | `update_project`         | PUT    | `/rest/api/3/project/{projectIdOrKey}`            |
    | `delete_project`         | DELETE | `/rest/api/3/project/{projectIdOrKey}`            |
    | `get_project_components` | GET    | `/rest/api/3/project/{projectIdOrKey}/components` |
    | `get_all_statuses`       | GET    | `/rest/api/3/project/{projectIdOrKey}/statuses`   |
    | `get_project_versions`   | GET    | `/rest/api/3/project/{projectIdOrKey}/versions`   |
  </Accordion>

  <Accordion title="Issues">
    | Operation         | Method | Path                                           |
    | ----------------- | ------ | ---------------------------------------------- |
    | `create_issue`    | POST   | `/rest/api/3/issue`                            |
    | `get_issue`       | GET    | `/rest/api/3/issue/{issueIdOrKey}`             |
    | `edit_issue`      | PUT    | `/rest/api/3/issue/{issueIdOrKey}`             |
    | `delete_issue`    | DELETE | `/rest/api/3/issue/{issueIdOrKey}`             |
    | `add_attachment`  | POST   | `/rest/api/3/issue/{issueIdOrKey}/attachments` |
    | `get_change_logs` | GET    | `/rest/api/3/issue/{issueIdOrKey}/changelog`   |
    | `get_transitions` | GET    | `/rest/api/3/issue/{issueIdOrKey}/transitions` |
    | `do_transition`   | POST   | `/rest/api/3/issue/{issueIdOrKey}/transitions` |
  </Accordion>

  <Accordion title="Comments">
    | Operation        | Method | Path                                            |
    | ---------------- | ------ | ----------------------------------------------- |
    | `get_comments`   | GET    | `/rest/api/3/issue/{issueIdOrKey}/comment`      |
    | `add_comment`    | POST   | `/rest/api/3/issue/{issueIdOrKey}/comment`      |
    | `get_comment`    | GET    | `/rest/api/3/issue/{issueIdOrKey}/comment/{id}` |
    | `update_comment` | PUT    | `/rest/api/3/issue/{issueIdOrKey}/comment/{id}` |
    | `delete_comment` | DELETE | `/rest/api/3/issue/{issueIdOrKey}/comment/{id}` |
  </Accordion>

  <Accordion title="Search">
    | Operation                                    | Method | Path                     |
    | -------------------------------------------- | ------ | ------------------------ |
    | `search_and_reconsile_issues_using_jql`      | GET    | `/rest/api/3/search/jql` |
    | `search_and_reconsile_issues_using_jql_post` | POST   | `/rest/api/3/search/jql` |
  </Accordion>

  <Accordion title="Issue links & types">
    | Operation                     | Method | Path                             |
    | ----------------------------- | ------ | -------------------------------- |
    | `link_issues`                 | POST   | `/rest/api/3/issueLink`          |
    | `get_issue_link`              | GET    | `/rest/api/3/issueLink/{linkId}` |
    | `delete_issue_link`           | DELETE | `/rest/api/3/issueLink/{linkId}` |
    | `get_issue_all_types`         | GET    | `/rest/api/3/issuetype`          |
    | `create_issue_type`           | POST   | `/rest/api/3/issuetype`          |
    | `get_issue_types_for_project` | GET    | `/rest/api/3/issuetype/project`  |
  </Accordion>

  <Accordion title="Worklogs">
    | Operation            | Method | Path                                            |
    | -------------------- | ------ | ----------------------------------------------- |
    | `get_issue_worklogs` | GET    | `/rest/api/3/issue/{issueIdOrKey}/worklog`      |
    | `add_worklog`        | POST   | `/rest/api/3/issue/{issueIdOrKey}/worklog`      |
    | `get_issue_worklog`  | GET    | `/rest/api/3/issue/{issueIdOrKey}/worklog/{id}` |
    | `update_worklog`     | PUT    | `/rest/api/3/issue/{issueIdOrKey}/worklog/{id}` |
    | `delete_worklog`     | DELETE | `/rest/api/3/issue/{issueIdOrKey}/worklog/{id}` |
  </Accordion>

  <Accordion title="Users & permissions">
    | Operation               | Method | Path                                 |
    | ----------------------- | ------ | ------------------------------------ |
    | `get_user`              | GET    | `/rest/api/3/user`                   |
    | `create_user`           | POST   | `/rest/api/3/user`                   |
    | `remove_user`           | DELETE | `/rest/api/3/user`                   |
    | `find_assignable_users` | GET    | `/rest/api/3/user/assignable/search` |
    | `find_users`            | GET    | `/rest/api/3/user/search`            |
    | `get_current_user`      | GET    | `/rest/api/3/myself`                 |
    | `get_all_permissions`   | GET    | `/rest/api/3/permissions`            |
    | `get_my_permissions`    | GET    | `/rest/api/3/mypermissions`          |
  </Accordion>

  <Accordion title="Fields, statuses & priorities">
    | Operation             | Method | Path                            |
    | --------------------- | ------ | ------------------------------- |
    | `get_fields`          | GET    | `/rest/api/3/field`             |
    | `create_custom_field` | POST   | `/rest/api/3/field`             |
    | `get_priorities`      | GET    | `/rest/api/3/priority`          |
    | `create_priority`     | POST   | `/rest/api/3/priority`          |
    | `get_statuses`        | GET    | `/rest/api/3/status`            |
    | `get_status`          | GET    | `/rest/api/3/status/{idOrName}` |
    | `get_server_info`     | GET    | `/rest/api/3/serverInfo`        |
  </Accordion>
</AccordionGroup>

## Webhook events

Jira uses a credential-scoped webhook model — one webhook is registered per credential set, and Guild routes events to matching triggers.

| Resource  | Action    | Jira event           |
| --------- | --------- | -------------------- |
| `issue`   | `created` | `jira:issue_created` |
| `issue`   | `updated` | `jira:issue_updated` |
| `issue`   | `deleted` | `jira:issue_deleted` |
| `comment` | `created` | `comment_created`    |
| `comment` | `updated` | `comment_updated`    |
| `comment` | `deleted` | `comment_deleted`    |

Events can be filtered by project using the `project` field in the service config. Guild handles webhook re-registration automatically — Jira dynamic webhooks expire after 30 days.

## Limitations

* OAuth refresh tokens expire after 90 days of inactivity
* Only Jira Cloud is supported (not Jira Server or Data Center)