jira（Jira 项目管理）

Troubleshooting

If requests fail, run zero doctor check-connector --env-name JIRA_API_TOKEN or zero doctor check-connector --url https://your-domain.atlassian.net/rest/api/3/myself --method GET

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:

JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/myself" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json"

2. List Projects

Get all projects you have access to:

JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/project" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json"

3. Get Project Details

Get details for a specific project:

PROJECT_KEY="PROJ"
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/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.):

PROJECT_KEY="PROJ"
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/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:

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

Then run:

JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/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:

ISSUE_KEY="PROJ-123"
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/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:

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

JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/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:

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

JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/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:

ISSUE_KEY="PROJ-123"

Write to /tmp/jira_request.json:

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

Then run:

JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X PUT "${JIRA_BASE}/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:

ISSUE_KEY="PROJ-123"
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/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:

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

Write to /tmp/jira_request.json:

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

Then run:

JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/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:

ISSUE_KEY="PROJ-123"

Write to /tmp/jira_request.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:

JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/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:

ISSUE_KEY="PROJ-123"
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/issue/${ISSUE_KEY}/comment" -u "$JIRA_EMAIL:$JIRA_API_TOKEN" --header "Accept: application/json"

14. Assign Issue

Assign an issue to a user:

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

Write to /tmp/jira_request.json:

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

Then run:

JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X PUT "${JIRA_BASE}/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

JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -G "${JIRA_BASE}/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):

ISSUE_KEY="PROJ-123"
JIRA_BASE="https://${JIRA_DOMAIN%.atlassian.net}.atlassian.net/rest/api/3"

curl -s -X DELETE "${JIRA_BASE}/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