Jira

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

Open Credentials

Go to Credentials in Guild.

Connect Jira

Click Jira and authorize access through Atlassian.

Grant access

Select your Jira site. Guild automatically retrieves your Cloud ID.

Usage

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.

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

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`

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`

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}`

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`

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`

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}`

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`

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`

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. The optional label_added field narrows a trigger to newly added labels. Set it to a non-empty list of label names, and the trigger fires only when one of them is newly added — on issue creation, when the issue carries the label, and on issue update, when the label appears in the change. Label matching is case-sensitive, unlike project.

{
  "project": "ENG",
  "label_added": ["needs-triage"]
}

Setting label_added also restricts the trigger to issue events: comment events never fire while it is set.

Limitations

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

Overview

Code & CI/CD

Communication

Project management

Testing

Productivity

Monitoring & observability

Data

Customer support

Sales & finance

Authentication

Setup

Usage

Selecting specific tools

API endpoints

Webhook events

Limitations

​Authentication

​Setup

​Usage

​Selecting specific tools

​API endpoints

​Webhook events

​Limitations

Authentication

Setup

Usage

Selecting specific tools

API endpoints

Webhook events

Limitations