Jira

Jira Integration Skill

This skill enables direct interaction with Jira Cloud via REST API v3 and JQL queries.

Prerequisites

Set these environment variables (or in .env file):

JIRA_DOMAIN=company.atlassian.net
JIRA_EMAIL=user@company.com
JIRA_API_TOKEN=your-api-token

Generate API tokens at: <https://id.atlassian.com/manage-profile/security/api-tokens>

Core Workflows

1. Get Issue Details

To retrieve issue information:

python scripts/jira_api.py GET /issue/PROJ-123

With specific fields:

python scripts/jira_api.py GET "/issue/PROJ-123?fields=summary,status,assignee"

2. Search with JQL

To search issues using JQL:

python scripts/jira_api.py GET /search --query "jql=project=AOP AND status='In Progress'&maxResults=20"

Common JQL patterns - see references/jql-reference.md:

• My open issues: assignee = currentUser() AND resolution = Unresolved
• Recent updates: updated >= -1d ORDER BY updated DESC
• Sprint work: sprint in openSprints() AND assignee = currentUser()

3. Create Issue

To create a new issue, use ADF format for description (see references/adf-format.md):

python scripts/jira_api.py POST /issue --data '{
  "fields": {
    "project": { "key": "PROJ" },
    "issuetype": { "name": "Task" },
    "summary": "Issue title",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [{ "type": "text", "text": "Description here" }]
        }
      ]
    }
  }
}'

4. Update Issue

To update fields on an existing issue:

python scripts/jira_api.py PUT /issue/PROJ-123 --data '{
  "fields": {
    "summary": "Updated title",
    "labels": ["label1", "label2"]
  }
}'

5. Add Comment

To add a comment (requires ADF format):

python scripts/jira_api.py POST /issue/PROJ-123/comment --data '{
  "body": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "Comment text here" }]
      }
    ]
  }
}'

6. Transition Issue Status

First, get available transitions:

python scripts/jira_api.py GET /issue/PROJ-123/transitions

Then transition to new status:

python scripts/jira_api.py POST /issue/PROJ-123/transitions --data '{
  "transition": { "id": "21" }
}'

7. Assign Issue

To assign an issue:

# Get user account ID first
python scripts/jira_api.py GET "/user/search?query=username"

# Then assign
python scripts/jira_api.py PUT /issue/PROJ-123/assignee --data '{
  "accountId": "user-account-id"
}'

To unassign:

python scripts/jira_api.py PUT /issue/PROJ-123/assignee --data '{"accountId": null}'

Direct curl Usage

For quick operations without the helper script:

JIRA_DOMAIN="company.atlassian.net"
AUTH=$(echo -n "$JIRA_EMAIL:$JIRA_API_TOKEN" | base64)

curl -s "https://$JIRA_DOMAIN/rest/api/3/issue/PROJ-123" \
  -H "Authorization: Basic $AUTH" \
  -H "Content-Type: application/json"

Reference Files

• `references/api-endpoints.md` - Complete REST API v3 endpoint reference
• `references/jql-reference.md` - JQL operators, functions, fields, and patterns
• `references/adf-format.md` - Atlassian Document Format for rich text fields

Common Patterns

Bulk Operations

To get multiple issues efficiently:

python scripts/jira_api.py GET /search --query "jql=key in (PROJ-1,PROJ-2,PROJ-3)"

Get Project Info

To list projects or get project details:

python scripts/jira_api.py GET /project
python scripts/jira_api.py GET /project/PROJ

Get Available Issue Types

python scripts/jira_api.py GET "/project/PROJ?expand=issueTypes"

Error Handling

Common error codes:

• 400: Bad request - check JSON syntax and field names
• 401: Unauthorized - verify credentials
• 403: Forbidden - check user permissions
• 404: Not found - verify issue key exists
• 429: Rate limited - wait and retry

For field validation errors, Jira returns detailed error messages indicating which fields are invalid.

Atlassian Document Format (ADF) Reference

Jira Cloud API v3 uses ADF for rich text fields like description and comment.body.

Basic Structure

Every ADF document has this structure:

{
  "type": "doc",
  "version": 1,
  "content": [
    // Array of block nodes
  ]
}

Block Nodes

Paragraph

{
  "type": "paragraph",
  "content": [
    { "type": "text", "text": "Plain text here" }
  ]
}

Heading

{
  "type": "heading",
  "attrs": { "level": 2 },
  "content": [
    { "type": "text", "text": "Heading Text" }
  ]
}

Levels: 1-6

Bullet List

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

Ordered List

{
  "type": "orderedList",
  "content": [
    {
      "type": "listItem",
      "content": [
        {
          "type": "paragraph",
          "content": [{ "type": "text", "text": "Step 1" }]
        }
      ]
    }
  ]
}

Code Block

{
  "type": "codeBlock",
  "attrs": { "language": "python" },
  "content": [
    { "type": "text", "text": "def hello():\n    print('Hello')" }
  ]
}

Blockquote

{
  "type": "blockquote",
  "content": [
    {
      "type": "paragraph",
      "content": [{ "type": "text", "text": "Quoted text" }]
    }
  ]
}

Rule (Horizontal Line)

{
  "type": "rule"
}

Inline Formatting (Marks)

Add marks array to text nodes for formatting:

Bold

{
  "type": "text",
  "text": "Bold text",
  "marks": [{ "type": "strong" }]
}

Italic

{
  "type": "text",
  "text": "Italic text",
  "marks": [{ "type": "em" }]
}

Code (Inline)

{
  "type": "text",
  "text": "code snippet",
  "marks": [{ "type": "code" }]
}

Link

{
  "type": "text",
  "text": "Click here",
  "marks": [
    {
      "type": "link",
      "attrs": { "href": "https://example.com" }
    }
  ]
}

Combined Marks

{
  "type": "text",
  "text": "Bold and italic",
  "marks": [
    { "type": "strong" },
    { "type": "em" }
  ]
}

Special Nodes

Mention User

{
  "type": "mention",
  "attrs": {
    "id": "account-id-here",
    "text": "@username"
  }
}

Emoji

{
  "type": "emoji",
  "attrs": {
    "shortName": ":thumbsup:",
    "text": "thumbs up"
  }
}

Hard Break (Line Break)

{
  "type": "hardBreak"
}

Complete Examples

Simple Comment

{
  "body": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "This is a comment." }
        ]
      }
    ]
  }
}

Issue Description with Formatting

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [{ "type": "text", "text": "Summary" }]
    },
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "This issue tracks " },
        { "type": "text", "text": "important", "marks": [{ "type": "strong" }] },
        { "type": "text", "text": " changes." }
      ]
    },
    {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [{ "type": "text", "text": "Steps" }]
    },
    {
      "type": "orderedList",
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [{ "type": "text", "text": "First step" }]
            }
          ]
        },
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [{ "type": "text", "text": "Second step" }]
            }
          ]
        }
      ]
    }
  ]
}

Tips

1. Always wrap text in paragraph nodes for block content 2. The version must be 1 3. Empty content arrays are invalid - omit the field or include content 4. Test complex ADF in Jira's editor first, then inspect the API response

Jira REST API v3 Endpoints Reference

Base URL: https://{domain}.atlassian.net/rest/api/3

Authentication

All requests require Basic Auth with email and API token:

AUTH=$(echo -n "email@example.com:API_TOKEN" | base64)
curl -H "Authorization: Basic $AUTH" -H "Content-Type: application/json" ...

Issue Operations

Get Issue

GET /issue/{issueIdOrKey}

Query params: fields, expand (changelog, transitions, renderedFields)

Create Issue

POST /issue

{
  "fields": {
    "project": { "key": "PROJ" },
    "issuetype": { "name": "Task" },
    "summary": "Issue title",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [{ "type": "text", "text": "Description text" }]
        }
      ]
    },
    "assignee": { "accountId": "user-account-id" },
    "labels": ["label1", "label2"],
    "priority": { "name": "High" }
  }
}

Update Issue

PUT /issue/{issueIdOrKey}

Same body format as create, only include fields to update.

Delete Issue

DELETE /issue/{issueIdOrKey}

Add Comment

POST /issue/{issueIdOrKey}/comment

{
  "body": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "Comment text" }]
      }
    ]
  }
}

Get Transitions

GET /issue/{issueIdOrKey}/transitions

Returns available status transitions for the issue.

Transition Issue

POST /issue/{issueIdOrKey}/transitions

{
  "transition": { "id": "21" }
}

Assign Issue

PUT /issue/{issueIdOrKey}/assignee

{ "accountId": "user-account-id" }

To unassign: { "accountId": null }

Add Labels

PUT /issue/{issueIdOrKey}

{
  "update": {
    "labels": [
      { "add": "new-label" }
    ]
  }
}

Link Issues

POST /issueLink

{
  "type": { "name": "Blocks" },
  "inwardIssue": { "key": "PROJ-123" },
  "outwardIssue": { "key": "PROJ-456" }
}

Search

Search with JQL

GET /search?jql={jql}&maxResults=50&startAt=0

Or POST for complex queries:

POST /search

{
  "jql": "project = PROJ AND status = 'In Progress'",
  "startAt": 0,
  "maxResults": 50,
  "fields": ["summary", "status", "assignee"]
}

Project Operations

List Projects

GET /project

Get Project

GET /project/{projectIdOrKey}

Query params: expand (issueTypes, lead, description)

Get Project Issue Types

GET /project/{projectIdOrKey}/statuses

User Operations

Get Current User

GET /myself

Search Users

GET /user/search?query={query}

Get User by Account ID

GET /user?accountId={accountId}

Common Response Codes

JQL (Jira Query Language) Reference

JQL is used to search for issues in Jira. Queries follow the pattern: field operator value [AND/OR field operator value]

Operators

Common Fields

Issue Fields

• project - Project key (e.g., "AOP")
• issuetype - Issue type (Task, Bug, Story, Epic)
• status - Current status
• summary - Issue title (text search with ~)
• description - Issue description (text search with ~)
• priority - Priority level
• resolution - Resolution status
• labels - Issue labels

People Fields

• assignee - Assigned user
• reporter - Issue creator
• creator - Same as reporter
• watcher - Users watching

Date Fields

• created - Creation date
• updated - Last update date
• duedate - Due date
• resolved - Resolution date
• lastViewed - Last viewed date

Agile Fields

• sprint - Sprint name or ID
• fixVersion - Fix version
• affectedVersion - Affected version
• component - Component name
• epic - Epic link (for stories)
• parent - Parent issue (for subtasks)

Functions

User Functions

• currentUser() - Logged-in user
• membersOf("group") - Members of a group

Date Functions

• now() - Current timestamp
• startOfDay() - Start of today
• endOfDay() - End of today
• startOfWeek() - Start of current week
• endOfWeek() - End of current week
• startOfMonth() - Start of current month
• endOfMonth() - End of current month
• startOfYear() - Start of current year
• endOfYear() - End of current year

Sprint Functions

• openSprints() - Active sprints
• closedSprints() - Completed sprints
• futureSprints() - Planned sprints

Other Functions

• issueHistory() - Issues in history
• linkedIssues(KEY) - Issues linked to KEY
• votedIssues() - Issues you voted for
• watchedIssues() - Issues you're watching

Relative Dates

Use relative time with +/- and units:

• 1d - 1 day
• 1w - 1 week
• 1m - 1 month (note: not minutes)
• 1y - 1 year
• 1h - 1 hour

Examples:

• -7d - 7 days ago
• -2w - 2 weeks ago
• +1d - 1 day from now

Common JQL Patterns

My Open Issues

assignee = currentUser() AND resolution = Unresolved ORDER BY priority DESC

Issues Updated Recently

updated >= -1d ORDER BY updated DESC

Bugs in Current Sprint

issuetype = Bug AND sprint in openSprints()

Unassigned Issues in Project

project = AOP AND assignee IS EMPTY AND status != Done

Issues Due This Week

duedate >= startOfWeek() AND duedate <= endOfWeek()

High Priority Blockers

priority = Highest AND status != Done AND issuetype = Bug

My Team's Work

assignee IN membersOf("my-team") AND sprint in openSprints()

Recently Created by Me

reporter = currentUser() AND created >= -7d

Issues Changed Status Today

status CHANGED AFTER startOfDay()

Text Search

summary ~ "login" OR description ~ "authentication"

Complex Query

project = AOP
AND issuetype IN (Bug, Task)
AND status NOT IN (Done, Closed)
AND (assignee = currentUser() OR assignee IS EMPTY)
ORDER BY priority DESC, created ASC

ORDER BY

Sort results with ORDER BY:

• ORDER BY created DESC - Newest first
• ORDER BY priority DESC, updated DESC - By priority, then update date
• ORDER BY rank ASC - Board ranking order

Tips

1. Quote values with spaces: status = "In Progress" 2. Field names are case-insensitive 3. Use parentheses for complex logic: (A OR B) AND C 4. Escape special chars with backslash: summary ~ "test\-case" 5. Empty check: field IS EMPTY not field = ""