jira

name	jira
description	Create, search, and manage Jira issues and sprints via the Atlassian REST API
homepage	https://developer.atlassian.com/cloud/jira/platform/rest/v3/
metadata	{"openclaw":{"emoji":"🔶","requires":{"env":["JIRA_TOKEN","JIRA_BASEURL"]},"primaryEnv":"JIRA_TOKEN"}}

Jira

Interact with Jira Cloud to create, search, update, and transition issues, manage sprints, and add comments using the Atlassian REST API v3.

Authentication

All requests use HTTP Basic Auth. Encode $JIRA_EMAIL:$JIRA_TOKEN as the credential pair. The base URL points to your Jira Cloud instance (e.g. https://yourteam.atlassian.net).

Common headers for every request:

-u "$JIRA_EMAIL:$JIRA_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

Common Operations

Search Issues (JQL)

Use JQL to find issues. The fields parameter limits response size.

curl -s -X GET \
  "$JIRA_BASEURL/rest/api/3/search?jql=project%3DENG%20AND%20status%3D%22In%20Progress%22&maxResults=20&fields=key,summary,status,assignee,priority" \
  -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  -H "Accept: application/json"

Key response fields: issues[].key, issues[].fields.summary, issues[].fields.status.name, issues[].fields.assignee.displayName, total.

Useful JQL examples:

• assignee = currentUser() AND resolution = Unresolved
• project = ENG AND sprint in openSprints()
• labels = bug AND priority = High AND updated >= -7d
• text ~ "search term"

Get Issue by Key

curl -s -X GET \
  "$JIRA_BASEURL/rest/api/3/issue/ENG-123?fields=summary,description,status,assignee,priority,labels,comment" \
  -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  -H "Accept: application/json"

Key response fields: fields.summary, fields.description.content (ADF format), fields.status.name, fields.priority.name, fields.comment.comments[].

Create Issue

curl -s -X POST \
  "$JIRA_BASEURL/rest/api/3/issue" \
  -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "fields": {
      "project": { "key": "ENG" },
      "summary": "Implement user authentication flow",
      "description": {
        "type": "doc",
        "version": 1,
        "content": [
          {
            "type": "paragraph",
            "content": [{ "type": "text", "text": "Description here" }]
          }
        ]
      },
      "issuetype": { "name": "Task" },
      "priority": { "name": "Medium" },
      "labels": ["backend"]
    }
  }'

Response: key (e.g. "ENG-456"), id, self.

Issue types: Bug, Task, Story, Epic, Sub-task. Priorities: Highest, High, Medium, Low, Lowest.

Update Issue

curl -s -X PUT \
  "$JIRA_BASEURL/rest/api/3/issue/ENG-123" \
  -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "summary": "Updated summary",
      "labels": ["backend", "urgent"],
      "priority": { "name": "High" }
    }
  }'

Returns 204 No Content on success.

Transition Issue (Change Status)

First, get available transitions:

curl -s -X GET \
  "$JIRA_BASEURL/rest/api/3/issue/ENG-123/transitions" \
  -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  -H "Accept: application/json"

Then apply a transition by ID:

curl -s -X POST \
  "$JIRA_BASEURL/rest/api/3/issue/ENG-123/transitions" \
  -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "transition": { "id": "31" } }'

Common transition names: To Do, In Progress, In Review, Done. Always fetch transitions first since IDs vary per project workflow.

Assign Issue

curl -s -X PUT \
  "$JIRA_BASEURL/rest/api/3/issue/ENG-123/assignee" \
  -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "accountId": "5b10ac8d82e05b22cc7d4ef5" }'

To find a user's accountId, search users:

curl -s -X GET \
  "$JIRA_BASEURL/rest/api/3/user/search?query=[e-mail]" \
  -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  -H "Accept: application/json"

Add Comment

curl -s -X POST \
  "$JIRA_BASEURL/rest/api/3/issue/ENG-123/comment" \
  -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [{ "type": "text", "text": "Deployed to staging. Ready for QA." }]
        }
      ]
    }
  }'

Get Board Sprints

curl -s -X GET \
  "$JIRA_BASEURL/rest/agile/1.0/board/1/sprint?state=active,future&maxResults=10" \
  -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  -H "Accept: application/json"

Key response fields: values[].id, values[].name, values[].state, values[].startDate, values[].endDate.

Get Sprint Issues

curl -s -X GET \
  "$JIRA_BASEURL/rest/agile/1.0/sprint/42/issue?fields=key,summary,status,assignee,priority&maxResults=50" \
  -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  -H "Accept: application/json"

Tips

• Description format: Jira API v3 uses Atlassian Document Format (ADF), not plain text. Wrap text in doc > paragraph > text nodes as shown above.
• Pagination: Use startAt and maxResults query params. Check total in response.
• Rate limits: Jira Cloud allows ~100 requests per 10 seconds. Batch reads with JQL rather than fetching individually.
• Agile endpoints: Sprint and board operations use /rest/agile/1.0/ not /rest/api/3/.
• Field discovery: To find custom field IDs, use GET /rest/api/3/field and search by name.
• Bulk operations: For moving multiple issues to a sprint, use POST /rest/agile/1.0/sprint/{sprintId}/issue with a body of {"issues": ["ENG-1", "ENG-2"]}.