Skip to main content
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

1

Open Credentials

Go to Credentials in Guild.
2

Connect Jira

Click Jira and authorize access through Atlassian.
3

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

OperationMethodPath
get_all_projectsGET/rest/api/3/project
create_projectPOST/rest/api/3/project
get_projectGET/rest/api/3/project/{projectIdOrKey}
update_projectPUT/rest/api/3/project/{projectIdOrKey}
delete_projectDELETE/rest/api/3/project/{projectIdOrKey}
get_project_componentsGET/rest/api/3/project/{projectIdOrKey}/components
get_all_statusesGET/rest/api/3/project/{projectIdOrKey}/statuses
get_project_versionsGET/rest/api/3/project/{projectIdOrKey}/versions
OperationMethodPath
create_issuePOST/rest/api/3/issue
get_issueGET/rest/api/3/issue/{issueIdOrKey}
edit_issuePUT/rest/api/3/issue/{issueIdOrKey}
delete_issueDELETE/rest/api/3/issue/{issueIdOrKey}
add_attachmentPOST/rest/api/3/issue/{issueIdOrKey}/attachments
get_change_logsGET/rest/api/3/issue/{issueIdOrKey}/changelog
get_transitionsGET/rest/api/3/issue/{issueIdOrKey}/transitions
do_transitionPOST/rest/api/3/issue/{issueIdOrKey}/transitions
OperationMethodPath
get_commentsGET/rest/api/3/issue/{issueIdOrKey}/comment
add_commentPOST/rest/api/3/issue/{issueIdOrKey}/comment
get_commentGET/rest/api/3/issue/{issueIdOrKey}/comment/{id}
update_commentPUT/rest/api/3/issue/{issueIdOrKey}/comment/{id}
delete_commentDELETE/rest/api/3/issue/{issueIdOrKey}/comment/{id}
OperationMethodPath
get_issue_worklogGET/rest/api/3/issue/{issueIdOrKey}/worklog
add_worklogPOST/rest/api/3/issue/{issueIdOrKey}/worklog
get_worklogGET/rest/api/3/issue/{issueIdOrKey}/worklog/{id}
update_worklogPUT/rest/api/3/issue/{issueIdOrKey}/worklog/{id}
delete_worklogDELETE/rest/api/3/issue/{issueIdOrKey}/worklog/{id}
OperationMethodPath
get_userGET/rest/api/3/user
create_userPOST/rest/api/3/user
remove_userDELETE/rest/api/3/user
find_assignable_usersGET/rest/api/3/user/assignable/search
find_usersGET/rest/api/3/user/search
get_current_userGET/rest/api/3/myself
get_all_permissionsGET/rest/api/3/permissions
get_my_permissionsGET/rest/api/3/mypermissions
OperationMethodPath
get_fieldsGET/rest/api/3/field
create_custom_fieldPOST/rest/api/3/field
get_prioritiesGET/rest/api/3/priority
create_priorityPOST/rest/api/3/priority
get_statusesGET/rest/api/3/status
get_statusGET/rest/api/3/status/{idOrName}
get_server_infoGET/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.
ResourceActionJira event
issuecreatedjira:issue_created
issueupdatedjira:issue_updated
issuedeletedjira:issue_deleted
commentcreatedcomment_created
commentupdatedcomment_updated
commentdeletedcomment_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)