ITSM & DevOpsv1.0Updated 2026-03-04Free

Jira

Project tracking with REST API v3, JQL queries, automation rules, and workflow management

Gives Claude Code expertise in Jira REST API v3, JQL (Jira Query Language), issue management, workflow configuration, automation rules, custom fields, and bulk operations. Covers Cloud and Data Center differences.

Use case: Jira API automation, JQL queries, issue creation and bulk updates, workflow configuration, sprint management, custom field operations, reporting

Download

§ The skill file

name: jira

description: Use when working with Jira REST API, JQL queries, issue management, workflows, sprints, or automation rules. Covers Jira Cloud v3 API, authentication, bulk operations, and custom fields.

# Jira Skill

Quick Start

Authentication (Jira Cloud)

bash

# API Token auth (email:token as Basic Auth)
curl -u "email@example.com:API_TOKEN" \
  "https://your-domain.atlassian.net/rest/api/3/myself" | jq .

# Or as header
echo -n "email@example.com:API_TOKEN" | base64
curl -H "Authorization: Basic BASE64_STRING" "https://your-domain.atlassian.net/rest/api/3/myself"

Base URL

https://{your-domain}.atlassian.net/rest/api/3/

Quick Queries

bash

# Search issues with JQL
curl -u user:token "https://domain.atlassian.net/rest/api/3/search?jql=project=PROJ+AND+status!=Done&maxResults=10" | jq '.issues[].key'

# Get single issue
curl -u user:token "https://domain.atlassian.net/rest/api/3/issue/PROJ-123" | jq '{key, summary: .fields.summary, status: .fields.status.name}'

API Reference

Issue Endpoints

Method	Endpoint	Description
POST	`/rest/api/3/issue`	Create issue
GET	`/rest/api/3/issue/{issueKey}`	Get issue
PUT	`/rest/api/3/issue/{issueKey}`	Update issue
DELETE	`/rest/api/3/issue/{issueKey}`	Delete issue
POST	`/rest/api/3/issue/{issueKey}/transitions`	Transition issue (change status)
GET	`/rest/api/3/search`	JQL search
POST	`/rest/api/3/issue/bulk`	Bulk create

Create Issue

json

{
  "fields": {
    "project": {"key": "PROJ"},
    "issuetype": {"name": "Bug"},
    "summary": "Login page returns 500 error",
    "description": {
      "type": "doc", "version": 1,
      "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Steps to reproduce..."}]}]
    },
    "priority": {"name": "High"},
    "assignee": {"accountId": "5b10a2844c20165700ede21g"},
    "labels": ["backend", "critical"],
    "components": [{"name": "Authentication"}]
  }
}

Transition Issue

bash

# Get available transitions
curl -u user:token "https://domain.atlassian.net/rest/api/3/issue/PROJ-123/transitions"

# Execute transition (e.g., move to "Done")
curl -u user:token -X POST "https://domain.atlassian.net/rest/api/3/issue/PROJ-123/transitions" \
  -H "Content-Type: application/json" \
  -d '{"transition": {"id": "31"}}'

JQL (Jira Query Language)

# Basic queries
project = PROJ AND status = "In Progress"
assignee = currentUser() AND resolution = Unresolved
priority in (High, Critical) AND created >= -7d

# Sprint queries
sprint in openSprints() AND assignee = currentUser()
sprint = "Sprint 42" AND status != Done

# Text search
summary ~ "login error" OR description ~ "authentication"
text ~ "payment failed"

# Date queries
created >= "2026-01-01" AND created <= "2026-03-31"
updated >= startOfWeek()
due <= endOfDay()

# Complex
project = PROJ AND issuetype = Bug AND priority = High AND status changed to "In Progress" after startOfWeek() AND assignee in membersOf("dev-team")

# Ordering
ORDER BY priority DESC, created ASC

Sprint Endpoints

bash

# List boards
GET /rest/agile/1.0/board

# Get sprints for a board
GET /rest/agile/1.0/board/{boardId}/sprint

# Get issues in sprint
GET /rest/agile/1.0/sprint/{sprintId}/issue

# Move issue to sprint
POST /rest/agile/1.0/sprint/{sprintId}/issue
Body: {"issues": ["PROJ-123", "PROJ-124"]}

Common Patterns

Bulk Update with JQL

python

import requests
from requests.auth import HTTPBasicAuth

auth = HTTPBasicAuth("email@example.com", "API_TOKEN")
base = "https://domain.atlassian.net"

# Search for issues
resp = requests.get(f"{base}/rest/api/3/search",
    auth=auth,
    params={"jql": "project=PROJ AND labels=needs-triage", "maxResults": 50})
issues = resp.json()["issues"]

# Update each issue
for issue in issues:
    requests.put(f"{base}/rest/api/3/issue/{issue['key']}",
        auth=auth,
        json={"fields": {"labels": ["triaged"]}})

Webhooks

bash

POST /rest/api/3/webhook
{
  "url": "https://myapp.com/jira-webhook",
  "webhooks": [{
    "events": ["jira:issue_created", "jira:issue_updated"],
    "jqlFilter": "project = PROJ"
  }]
}

Best Practices

API tokens over passwords: Use API tokens (generate at id.atlassian.com). Tokens can be revoked independently.
Pagination: Use startAt and maxResults (max 100 per request). Total count in response.total.
Field filtering: Use fields=summary,status,assignee to reduce response size. Use expand for additional data.
Rate limiting: Jira Cloud limits vary by endpoint. Check X-RateLimit-* headers. Implement exponential backoff on 429 responses.
JQL performance: Use indexed fields (project, status, priority, assignee) in JQL. Avoid text ~ on large instances (full-text search is slow).
Atlassian Document Format: Jira Cloud v3 uses ADF for description/comments (structured JSON, not markdown). Use the ADF builder or convert from markdown.
Automation rules: For common workflows (auto-assign, status transitions, notifications), use Jira's built-in automation rules instead of API scripts. Less maintenance, no API rate limits.

§ Sources

https://developer.atlassian.com/cloud/jira/platform/rest/v3/ ↗https://support.atlassian.com/jira-service-management-cloud/docs/use-advanced-search-with-jql/ ↗https://developer.atlassian.com/cloud/jira/platform/ ↗https://support.atlassian.com/jira-software-cloud/ ↗