Jira API

Use the Jira Cloud REST API via direct curl calls to manage issues, projects, and workflows.

Official docs: https://developer.atlassian.com/cloud/jira/platform/rest/v3/

---

When to Use

Use this skill when you need to:

• Create issues in Jira projects
• Search issues using JQL (Jira Query Language)
• Update issues (status, assignee, priority, etc.)
• Get issue details and comments
• List projects and their metadata
• Transition issues through workflow states
• Add comments to issues

---

Prerequisites

1. Go to Atlassian Account Settings
2. Click Create API token
3. Copy the generated token (you won't see it again)

export JIRA_DOMAIN="mycompany" # e.g., "mycompany" or "mycompany.atlassian.net"
export JIRA_EMAIL="you@example.com" # Your Atlassian account email
export JIRA_API_TOKEN="your-api-token" # API token from step 2

Rate Limits

Jira Cloud has rate limits that vary by endpoint. For most REST API calls, expect limits around 100-500 requests per minute.

---

Important: When using $VAR in a command that pipes to another command, wrap the command containing $VAR in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.

bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .

How to Use

All examples below assume JIRA_DOMAIN, JIRA_EMAIL, and JIRA_API_TOKEN are set.

Base URL: https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3

Note: ${JIRA_DOMAIN%.atlassian.net} strips the suffix if present, so both mycompany and mycompany.atlassian.net work.

---

1. Get Current User

Verify your authentication:

bash -c 'curl -s -X GET "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/myself" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json"' | jq '{accountId, emailAddress, displayName, active}

---

2. List Projects

Get all projects you have access to:

bash -c 'curl -s -X GET "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/project" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json"' | jq '.[] | {id, key, name}

---

3. Get Project Details

Get details for a specific project:

PROJECT_KEY="PROJ"

bash -c 'curl -s -X GET "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/project/${PROJECT_KEY}" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json"' | jq '{id, key, name, projectTypeKey, lead: .lead.displayName}

---

4. Get Issue Types for Project

List available issue types (Task, Bug, Story, etc.):

PROJECT_KEY="PROJ"

bash -c 'curl -s -X GET "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/project/${PROJECT_KEY}" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json"' | jq '.issueTypes[] | {id, name, subtask}

---

5. Search Issues with JQL

Search issues using Jira Query Language:

bash -c 'curl -s -G "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/search/jql" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --data-urlencode "jql=project = PROJ AND status != Done ORDER BY created DESC" --data-urlencode "maxResults=10" --data-urlencode "fields=key,summary,status,assignee,priority"' | jq '.issues[] | {key, summary: .fields.summary, status: .fields.status.name, assignee: .fields.assignee.displayName, priority: .fields.priority.name}

Common JQL examples:

• project = PROJ - Issues in project
• assignee = currentUser() - Your issues
• status = "In Progress" - By status
• created >= -7d - Created in last 7 days
• labels = bug - By label
• priority = High - By priority

---

6. Get Issue Details

Get full details of an issue:

ISSUE_KEY="PROJ-123"

bash -c 'curl -s -X GET "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json"' | jq '{key, summary: .fields.summary, status: .fields.status.name, assignee: .fields.assignee.displayName, priority: .fields.priority.name, created: .fields.created, updated: .fields.updated}

---

7. Create Issue

Create a new issue (API v3 uses Atlassian Document Format for description):

bash -c 'curl -s -X POST "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --header "Content-Type: application/json" -d '"'"'{
  "fields": {
  "project": {"key": "PROJ"},
  "summary": "Bug: Login button not responding",
  "description": {
  "type": "doc",
  "version": 1,
  "content": [
  {
  "type": "paragraph",
  "content": [
  {"type": "text", "text": "The login button on the mobile app is not responding when tapped."}
  ]
  }
  ]
  },
  "issuetype": {"name": "Bug"}
  }
}'"'"' | jq '"'"'{id, key, self}'"'"''

---

8. Create Issue with Priority and Labels

Create issue with additional fields:

bash -c 'curl -s -X POST "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --header "Content-Type: application/json" -d '"'"'{
  "fields": {
  "project": {"key": "PROJ"},
  "summary": "Implement user authentication",
  "description": {
  "type": "doc",
  "version": 1,
  "content": [
  {
  "type": "paragraph",
  "content": [
  {"type": "text", "text": "Add OAuth2 authentication flow for the mobile app."}
  ]
  }
  ]
  },
  "issuetype": {"name": "Story"},
  "priority": {"name": "High"},
  "labels": ["backend", "security"]
  }
}'"'"' | jq '"'"'{id, key, self}'"'"''

---

9. Update Issue

Update an existing issue:

ISSUE_KEY="PROJ-123"

curl -s -X PUT "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --header "Content-Type: application/json" -d '{
  "fields": {
  "summary": "Updated: Login button not responding on iOS",
  "priority": {"name": "Highest"},
  "labels": ["bug", "ios", "urgent"]
  }
  }'

Returns 204 No Content on success.

---

10. Get Available Transitions

Get possible status transitions for an issue:

ISSUE_KEY="PROJ-123"

bash -c 'curl -s -X GET "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}/transitions" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json"' | jq '.transitions[] | {id, name, to: .to.name}

---

11. Transition Issue (Change Status)

Move issue to a different status:

ISSUE_KEY="PROJ-123"
TRANSITION_ID="31" # Get from transitions endpoint

curl -s -X POST "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}/transitions" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --header "Content-Type: application/json" -d "{\"transition\": {\"id\": \"${TRANSITION_ID}\"}}"

Returns 204 No Content on success.

---

12. Add Comment

Add a comment to an issue:

ISSUE_KEY="PROJ-123"

bash -c 'curl -s -X POST "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}/comment" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --header "Content-Type: application/json" -d '"'"'{
  "body": {
  "type": "doc",
  "version": 1,
  "content": [
  {
  "type": "paragraph",
  "content": [
  {"type": "text", "text": "Investigated and found the root cause. Working on a fix."}
  ]
  }
  ]
  }
}'"'"' | jq '"'"'{id, created, author: .author.displayName}'"'"''

---

13. Get Issue Comments

List all comments on an issue:

ISSUE_KEY="PROJ-123"

bash -c 'curl -s -X GET "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}/comment" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json"' | jq '.comments[] | {id, author: .author.displayName, created, body: .body.content[0].content[0].text}

---

14. Assign Issue

Assign an issue to a user:

ISSUE_KEY="PROJ-123"
ACCOUNT_ID="5b10ac8d82e05b22cc7d4ef5" # Get from /rest/api/3/user/search

curl -s -X PUT "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}/assignee" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --header "Content-Type: application/json" -d "{\"accountId\": \"${ACCOUNT_ID}\"}"

---

15. Search Users

Find users by email or name:

bash -c 'curl -s -G "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/user/search" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --data-urlencode "query=john"' | jq '.[] | {accountId, displayName, emailAddress}

---

16. Delete Issue

Delete an issue (use with caution):

ISSUE_KEY="PROJ-123"

curl -s -X DELETE "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/issue/${ISSUE_KEY}" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}"

Returns 204 No Content on success.

---

Atlassian Document Format (ADF)

Jira API v3 uses ADF for rich text fields like description and comment.body. Basic structure:

{
  "type": "doc",
  "version": 1,
  "content": [
  {
  "type": "paragraph",
  "content": [
  {"type": "text", "text": "Plain text"},
  {"type": "text", "text": "Bold text", "marks": [{"type": "strong"}]},
  {"type": "text", "text": "Code", "marks": [{"type": "code"}]}
  ]
  },
  {
  "type": "bulletList",
  "content": [
  {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Item 1"}]}]},
  {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Item 2"}]}]}
  ]
  },
  {
  "type": "codeBlock",
  "attrs": {"language": "python"},
  "content": [{"type": "text", "text": "print('hello')"}]
  }
  ]
}

---

Guidelines

1. Use JQL for complex queries: JQL is powerful for filtering issues by any field combination
2. Check transitions first: Before changing status, get available transitions for the issue
3. Handle pagination: Use startAt and maxResults for large result sets
4. Use account IDs: Jira Cloud uses account IDs (not usernames) for user references
5. ADF for rich text: API v3 requires Atlassian Document Format for description and comments
6. Rate limiting: Implement exponential backoff if you receive 429 responses