Agent skill

jira

Jira API for issue tracking. Use when user mentions "Jira", "create ticket", "Jira issue", "sprint", or asks about Atlassian project management.

View SKILL.md on GitHub Repository
Stars 50
Forks 8

Install this agent skill to your Project

npx add-skill https://github.com/vm0-ai/vm0-skills/tree/main/jira

SKILL.md

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)
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.

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
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

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

2. List Projects

Get all projects you have access to:

bash
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

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

3. Get Project Details

Get details for a specific project:

bash
PROJECT_KEY="PROJ"
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/project/${PROJECT_KEY}" -u "$(printenv JIRA_EMAIL):$(printenv 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"
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/project/${PROJECT_KEY}" -u "$(printenv JIRA_EMAIL):$(printenv 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
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/search/jql" -u "$(printenv JIRA_EMAIL):$(printenv 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"
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/issue/${ISSUE_KEY}" -u "$(printenv JIRA_EMAIL):$(printenv 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
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/issue" -u "$(printenv JIRA_EMAIL):$(printenv 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
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/issue" -u "$(printenv JIRA_EMAIL):$(printenv 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
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

curl -s -X PUT "${JIRA_BASE}/issue/${ISSUE_KEY}" -u "$(printenv JIRA_EMAIL):$(printenv 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"
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/issue/${ISSUE_KEY}/transitions" -u "$(printenv JIRA_EMAIL):$(printenv 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
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/issue/${ISSUE_KEY}/transitions" -u "$(printenv JIRA_EMAIL):$(printenv 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
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

curl -s -X POST "${JIRA_BASE}/issue/${ISSUE_KEY}/comment" -u "$(printenv JIRA_EMAIL):$(printenv 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"
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

curl -s -X GET "${JIRA_BASE}/issue/${ISSUE_KEY}/comment" -u "$(printenv JIRA_EMAIL):$(printenv 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
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

curl -s -X PUT "${JIRA_BASE}/issue/${ISSUE_KEY}/assignee" -u "$(printenv JIRA_EMAIL):$(printenv 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
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

curl -s -G "${JIRA_BASE}/user/search" -u "$(printenv JIRA_EMAIL):$(printenv 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"
JIRA_BASE="https://$(printenv JIRA_DOMAIN | sed 's/\.atlassian\.net$//').atlassian.net/rest/api/3"

curl -s -X DELETE "${JIRA_BASE}/issue/${ISSUE_KEY}" -u "$(printenv JIRA_EMAIL):$(printenv 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

  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

Didn't find tool you were looking for?

Be as detailed as possible for better results