Back to Details

jira

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Jira API

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/
通过直接调用
curl
来使用Jira Cloud REST API，以管理问题、项目和工作流。
官方文档：
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
在以下场景中可以使用该技能：
  • 在Jira项目中创建问题
  • 使用JQL（Jira查询语言）搜索问题
  • 更新问题（状态、经办人、优先级等）
  • 获取问题详情和评论
  • 列出项目及其元数据
  • 变更问题的工作流状态
  • 为问题添加评论

Prerequisites

前置条件

  1. Go to Atlassian Account Settings
  2. Click Create API token
  3. 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
  1. 前往Atlassian账户设置
  2. 点击创建API令牌
  3. 复制生成的令牌（之后无法再查看）
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'
Jira Cloud的各端点速率限制不同。对于大多数REST API调用，速率限制约为每分钟100-500次请求。
重要提示： 当在包含管道的命令中使用
$VAR
时，需将包含
$VAR
的命令用
bash -c '...'
包裹。由于Claude Code的一个bug，直接使用管道时环境变量会被静默清除。
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.
以下所有示例均假设已设置
JIRA_DOMAIN
、
JIRA_EMAIL
和
JIRA_API_TOKEN
环境变量。
基础URL：
https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3
注意：
${JIRA_DOMAIN%.atlassian.net}
会移除后缀（如果存在），因此
mycompany
和
mycompany.atlassian.net
两种格式均适用。

1. Get Current User

1. 获取当前用户

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"'
验证你的身份认证：
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

2. 列出项目

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"'
获取你有权限访问的所有项目：
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

3. 获取项目详情

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"'
获取特定项目的详细信息：
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

4. 获取项目的问题类型

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"'
列出可用的问题类型（任务、Bug、用户故事等）：
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

5. 使用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
使用Jira查询语言搜索问题：
将以下内容写入
/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"]
}
然后运行：
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}''
常见JQL示例：
  • project = PROJ
    - 项目中的问题
  • assignee = currentUser()
    - 你负责的问题
  • status = "In Progress"
    - 按状态筛选（进行中）
  • status NOT IN (Done, Closed)
    - 排除已完成/关闭的问题
  • created >= -7d
    - 近7天创建的问题
  • labels = bug
    - 按标签筛选（Bug）
  • priority = High
    - 按优先级筛选（高）

6. Get Issue Details

6. 获取问题详情

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"'
获取某个问题的完整信息：
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

7. 创建问题

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'
创建新问题（API v3使用Atlassian文档格式（ADF）处理描述字段）：
将以下内容写入
/tmp/jira_request.json
：
json
{
  "fields": {
    "project": {"key": "PROJ"},
    "summary": "Bug: 登录按钮无响应",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {"type": "text", "text": "移动端应用的登录按钮点击后无响应。"}
          ]
        }
      ]
    },
    "issuetype": {"name": "Bug"}
  }
}
然后运行：
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

8. 创建带优先级和标签的问题

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'
创建包含额外字段的问题：
将以下内容写入
/tmp/jira_request.json
：
json
{
  "fields": {
    "project": {"key": "PROJ"},
    "summary": "实现用户认证功能",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {"type": "text", "text": "为移动端应用添加OAuth2认证流程。"}
          ]
        }
      ]
    },
    "issuetype": {"name": "Story"},
    "priority": {"name": "High"},
    "labels": ["backend", "security"]
  }
}
然后运行：
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

9. 更新问题

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.
更新现有问题：
bash
ISSUE_KEY="PROJ-123"
将以下内容写入
/tmp/jira_request.json
：
json
{
  "fields": {
    "summary": "更新：iOS端登录按钮无响应",
    "priority": {"name": "Highest"},
    "labels": ["bug", "ios", "urgent"]
  }
}
然后运行：
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'
成功时返回204 No Content。

10. Get Available Transitions

10. 获取可用的状态转换

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"'
获取某个问题可进行的状态转换：
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)

11. 转换问题状态

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.
将问题切换到不同的状态：
bash
ISSUE_KEY="PROJ-123"
TRANSITION_ID="31" # 从状态转换端点获取
将以下内容写入
/tmp/jira_request.json
：
json
{
  "transition": {
    "id": "<your-transition-id>"
  }
}
然后运行：
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'
成功时返回204 No Content。

12. Add Comment

12. 添加评论

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'
为问题添加评论：
bash
ISSUE_KEY="PROJ-123"
将以下内容写入
/tmp/jira_request.json
：
json
{
  "body": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [
          {"type": "text", "text": "已完成调查并找到根本原因，正在修复中。"}
        ]
      }
    ]
  }
}
然后运行：
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

13. 获取问题评论

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"'
列出某个问题的所有评论：
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

14. 分配问题

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'
将问题分配给某个用户：
bash
ISSUE_KEY="PROJ-123"
ACCOUNT_ID="5b10ac8d82e05b22cc7d4ef5" # 从/rest/api/3/user/search获取
将以下内容写入
/tmp/jira_request.json
：
json
{
  "accountId": "<your-account-id>"
}
然后运行：
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

15. 搜索用户

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"'
通过邮箱或姓名查找用户：
将以下内容写入
/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

16. 删除问题

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.
删除问题（请谨慎操作）：
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}"'
成功时返回204 No Content。

Atlassian Document Format (ADF)

Atlassian文档格式（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')"}]
  }
  ]
}
Jira API v3使用ADF格式处理富文本字段，如
description
和
comment.body
。基本结构如下：
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

注意事项

  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
  1. 复杂查询使用JQL：JQL功能强大，可通过任意字段组合筛选问题
  2. 先检查状态转换：变更状态前，先获取该问题可用的状态转换选项
  3. 处理分页：对于大型结果集，使用
    startAt
    和
    maxResults
    参数
  4. 使用账户ID：Jira Cloud使用账户ID（而非用户名）来关联用户
  5. 富文本使用ADF：API v3要求描述和评论字段使用Atlassian文档格式
  6. 速率限制处理：如果收到429响应，请实现指数退避策略