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

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

bash

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
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq '.field'

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

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"'

2. List Projects

Get all projects you have access to:

bash

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"'

3. Get Project Details

Get details for a specific project:

bash

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"'

4. Get Issue Types for Project

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

bash

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"'

5. Search Issues with JQL

Search issues using Jira Query Language:

Write to

/tmp/jira_request.json

json

{
  "jql": "project = PROJ AND status NOT IN (Done) ORDER BY created DESC",
  "maxResults": 10,
  "fields": ["key", "summary", "status", "assignee", "priority"]
}

Then run:

bash

bash -c 'curl -s -X POST "https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3/search/jql" -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" --header "Accept: application/json" --header "Content-Type: application/json" -d @/tmp/jira_request.json' | 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
```
status NOT IN (Done, Closed)
```
- Exclude statuses
```
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:

bash

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"'

7. Create Issue

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

Write to

/tmp/jira_request.json

json

{
  "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"}
  }
}

Then run:

bash

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 @/tmp/jira_request.json'

8. Create Issue with Priority and Labels

Create issue with additional fields:

Write to

/tmp/jira_request.json

json

{
  "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"]
  }
}

Then run:

bash

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 @/tmp/jira_request.json'

9. Update Issue

Update an existing issue:

bash

ISSUE_KEY="PROJ-123"

Write to

/tmp/jira_request.json

json

{
  "fields": {
    "summary": "Updated: Login button not responding on iOS",
    "priority": {"name": "Highest"},
    "labels": ["bug", "ios", "urgent"]
  }
}

Then run:

bash

bash -c '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 @/tmp/jira_request.json'

Returns 204 No Content on success.

10. Get Available Transitions

Get possible status transitions for an issue:

bash

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"'

11. Transition Issue (Change Status)

Move issue to a different status:

bash

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

Write to

/tmp/jira_request.json

json

{
  "transition": {
    "id": "<your-transition-id>"
  }
}

Then run:

bash

bash -c '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 @/tmp/jira_request.json'

Returns 204 No Content on success.

12. Add Comment

Add a comment to an issue:

bash

ISSUE_KEY="PROJ-123"

Write to

/tmp/jira_request.json

json

{
  "body": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [
          {"type": "text", "text": "Investigated and found the root cause. Working on a fix."}
        ]
      }
    ]
  }
}

Then run:

bash

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 @/tmp/jira_request.json'

13. Get Issue Comments

List all comments on an issue:

bash

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"'

14. Assign Issue

Assign an issue to a user:

bash

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

Write to

/tmp/jira_request.json

json

{
  "accountId": "<your-account-id>"
}

Then run:

bash

bash -c '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 @/tmp/jira_request.json'

15. Search Users

Find users by email or name:

Write to

/tmp/jira_search.txt

john

bash

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@/tmp/jira_search.txt"'

16. Delete Issue

Delete an issue (use with caution):

bash

ISSUE_KEY="PROJ-123"

bash -c '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:

json

{
  "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

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

jira

NPX Install

Tags

SKILL.md Content

Jira API

When to Use

Prerequisites

Rate Limits

How to Use

1. Get Current User

2. List Projects

3. Get Project Details

4. Get Issue Types for Project

5. Search Issues with JQL

6. Get Issue Details

7. Create Issue

8. Create Issue with Priority and Labels

9. Update Issue

10. Get Available Transitions

11. Transition Issue (Change Status)

12. Add Comment

13. Get Issue Comments

14. Assign Issue

15. Search Users

16. Delete Issue

Atlassian Document Format (ADF)

Guidelines