Jira Integration#

Interact with Atlassian Jira Cloud via REST API v3.

Authentication#

Use Basic Auth with email and API token:

Required Environment Variables:

bash

JIRA_EMAIL=your_email@example.com
JIRA_API_TOKEN=your_api_token
JIRA_DOMAIN=your_domain  # e.g. "yourcompany" for yourcompany.atlassian.net

Credentials:

• Email: $JIRA_EMAIL
• API Token: $JIRA_API_TOKEN
• Domain: https://$JIRA_DOMAIN.atlassian.net

Base URL:

text

https://$JIRA_DOMAIN.atlassian.net/rest/api/3

Jira Software (Agile) Base URL:

text

https://$JIRA_DOMAIN.atlassian.net/rest/agile/1.0

Generate API Token:

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Label it (e.g., "nanobot")
4. Copy the token

Common Headers#

text

Content-Type: application/json
Accept: application/json
Authorization: Basic base64(email:token)

---

Complete API Reference#

Total API Summary#

CategoryCountTotal Endpoints122Total Schemas64Jira Software (Agile)51 endpointsBuilds API9 endpointsDeployments API7 endpointsDevInfo API7 endpointsDevOps Components7 endpointsFeature Flags6 endpointsOperations11 endpointsRemote Links5 endpointsSecurity13 endpoints

---

Jira Software (Agile) API#

Boards#

Get All Boards

text

GET /rest/agile/1.0/board

Returns all boards visible to the user.

Create Board

text

POST /rest/agile/1.0/board

Body:

json

{
  "name": "Sprint Board",
  "type": "scrum",
  "filterId": 12345,
  "location": {
    "type": "project",
    "projectKeyOrId": "PROJ"
  }
}

Get Board by ID

text

GET /rest/agile/1.0/board/{boardId}

Delete Board

text

DELETE /rest/agile/1.0/board/{boardId}

Get Board Configuration

text

GET /rest/agile/1.0/board/{boardId}/configuration

Returns board configuration including column config, estimation type, and ranking info.

Get Issues for Board

text

GET /rest/agile/1.0/board/{boardId}/issue

Query params: startAt, maxResults, jql, validateQuery, fields, expand

Move Issues to Board

text

POST /rest/agile/1.0/board/{boardId}/issue

Body:

json

{
  "issues": ["PROJ-1", "PROJ-2"],
  "rankBeforeIssue": "PROJ-3",
  "rankAfterIssue": "PROJ-4",
  "rankCustomFieldId": 10001
}

Get Backlog Issues

text

GET /rest/agile/1.0/board/{boardId}/backlog

Move Issues to Backlog

text

POST /rest/agile/1.0/backlog/{boardId}/issue

Body:

json

{
  "issues": ["PROJ-1", "PROJ-2"]
}

---

Sprints#

Get All Sprints

text

GET /rest/agile/1.0/board/{boardId}/sprint

Create Sprint

text

POST /rest/agile/1.0/sprint

Body:

json

{
  "name": "Sprint 1",
  "originBoardId": 1,
  "startDate": "2024-01-15T00:00:00.000Z",
  "endDate": "2024-01-29T00:00:00.000Z",
  "goal": "Sprint 1 goal"
}

Get Sprint

text

GET /rest/agile/1.0/sprint/{sprintId}

Update Sprint (Full)

text

PUT /rest/agile/1.0/sprint/{sprintId}

Body:

json

{
  "name": "Updated Sprint Name",
  "startDate": "2024-01-15T00:00:00.000Z",
  "endDate": "2024-01-29T00:00:00.000Z",
  "goal": "Updated goal",
  "state": "active"
}

Partially Update Sprint

text

POST /rest/agile/1.0/sprint/{sprintId}

Body:

json

{
  "name": "Updated Name",
  "goal": "Updated goal",
  "state": "closed"
}

Delete Sprint

text

DELETE /rest/agile/1.0/sprint/{sprintId}

Get Issues for Sprint

text

GET /rest/agile/1.0/sprint/{sprintId}/issue

Move Issues to Sprint

text

POST /rest/agile/1.0/sprint/{sprintId}/issue

Body:

json

{
  "issues": ["PROJ-1", "PROJ-2"]
}

Swap Sprint

text

POST /rest/agile/1.0/sprint/{sprintId}/swap

Body:

json

{
  "sprintToSwapWith": 5
}

---

Epics#

Get Epics for Board

text

GET /rest/agile/1.0/board/{boardId}/epic

Get Epic

text

GET /rest/agile/1.0/epic/{epicIdOrKey}

Partially Update Epic

text

POST /rest/agile/1.0/epic/{epicIdOrKey}

Body:

json

{
  "name": "Epic Name",
  "summary": "Epic summary",
  "color": "color_1",
  "done": false
}

Get Issues for Epic

text

GET /rest/agile/1.0/epic/{epicIdOrKey}/issue

Move Issues to Epic

text

POST /rest/agile/1.0/epic/{epicIdOrKey}/issue

Body:

json

{
  "issues": ["PROJ-1", "PROJ-2"]
}

Rank Epics

text

PUT /rest/agile/1.0/epic/{epicIdOrKey}/rank

Body:

json

{
  "rankBeforeEpic": "EPIC-2",
  "rankAfterEpic": "EPIC-3",
  "rankCustomFieldId": 10001
}

Get Issues Without Epic

text

GET /rest/agile/1.0/epic/none/issue

Remove Issues from Epic

text

POST /rest/agile/1.0/epic/none/issue

Body:

json

{
  "issues": ["PROJ-1", "PROJ-2"]
}

---

Issue Ranking#

Rank Issues

text

PUT /rest/agile/1.0/issue/rank

Body:

json

{
  "issues": ["PROJ-1", "PROJ-2"],
  "rankAfterIssue": "PROJ-3",
  "rankBeforeIssue": "PROJ-4",
  "rankCustomFieldId": 10001
}

Get Agile Issue

text

GET /rest/agile/1.0/issue/{issueIdOrKey}

Returns issue with Agile fields (sprint, closedSprints, flagged, epic).

Get Issue Estimation

text

GET /rest/agile/1.0/issue/{issueIdOrKey}/estimation?boardId={boardId}

Estimate Issue

text

PUT /rest/agile/1.0/issue/{issueIdOrKey}/estimation

Body:

json

{
  "boardId": 1,
  "value": "3h"
}

Accepts formats: "1w", "2d", "3h", "20m" or number (minutes).

---

Jira Platform API#

Issues (CRUD Operations)#

Get Issue

text

GET /rest/api/3/issue/{issueIdOrKey}

Query params: fields, expand, properties, updateHistory Examples:

• GET /rest/api/3/issue/PROJ-123
• GET /rest/api/3/issue/PROJ-123?fields=summary,status,assignee
• GET /rest/api/3/issue/PROJ-123?expand=changelog

Create Issue

text

POST /rest/api/3/issue

Body:

json

{
  "fields": {
    "project": { "key": "PROJECT_KEY" },
    "summary": "Issue title",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        { "type": "paragraph", "content": [{ "type": "text", "text": "Description" }] }
      ]
    },
    "issuetype": { "name": "Task" },
    "priority": { "id": "3" },
    "assignee": { "accountId": "USER_ACCOUNT_ID" }
  }
}

Edit Issue

text

PUT /rest/api/3/issue/{issueIdOrKey}

Body:

json

{
  "fields": {
    "summary": "Updated summary",
    "description": { ... }
  },
  "update": {
    "labels": [
      { "add": "bugfix" },
      { "remove": "blocker" }
    ]
  }
}

Delete Issue

text

DELETE /rest/api/3/issue/{issueIdOrKey}?deleteSubtasks=true

Assign Issue

text

PUT /rest/api/3/issue/{issueIdOrKey}/assignee

Body:

json

{
  "accountId": "USER_ACCOUNT_ID"
}

Use "accountId": "-1" for default assignee, null for unassigned.

---

Search (JQL)#

Search Issues

text

GET /rest/api/3/search?jql={jql}&startAt={offset}&maxResults={limit}&fields={fields}

Query params: jql, startAt, maxResults, fields, expand, properties Examples:

• GET /rest/api/3/search?jql=project=PMG ORDER BY created DESC
• GET /rest/api/3/search?jql=assignee=currentUser()&maxResults=50

---

Issue Operations#

Get Transitions

text

GET /rest/api/3/issue/{issueIdOrKey}/transitions

Transition Issue

text

POST /rest/api/3/issue/{issueIdOrKey}/transitions

Body:

json

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

Add Comment

text

POST /rest/api/3/issue/{issueIdOrKey}/comment

Body:

json

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

Send Notification

text

POST /rest/api/3/issue/{issueIdOrKey}/notify

Body:

json

{
  "subject": "Subject",
  "textBody": "Body text",
  "to": { "reporter": true },
  "restrict": { "group": { "name": "jira-software-users" } }
}

---

Issue Metadata#

Get Create Issue Metadata

text

GET /rest/api/3/issue/createmeta?projectKeys={project}&issuetypeNames={type}

Get Edit Metadata

text

GET /rest/api/3/issue/{issueIdOrKey}/editmeta

Get Create Metadata for Project

text

GET /rest/api/3/issue/createmeta/{projectIdOrKey}/issuetypes

Get Create Metadata for Project & Issue Type

text

GET /rest/api/3/issue/createmeta/{projectIdOrKey}/issuetypes/{issueTypeId}

---

Bulk Operations#

Bulk Create Issues (up to 50)

text

POST /rest/api/3/issue/bulk

Body:

json

{
  "issueUpdates": [
    { "fields": { "project": { "key": "PROJ" }, "summary": "...", "issuetype": { "name": "Task" } } },
    { "fields": { "project": { "key": "PROJ" }, "summary": "...", "issuetype": { "name": "Bug" } } }
  ]
}

Bulk Fetch Issues (up to 100)

text

POST /rest/api/3/issue/bulkfetch

Body:

json

{
  "issueIdsOrKeys": ["PROJ-1", "PROJ-2", "10005"],
  "fields": ["summary", "project", "status", "assignee"],
  "properties": []
}

Bulk Fetch Changelogs

text

POST /rest/api/3/changelog/bulkfetch

Body:

json

{
  "issueIdsOrKeys": ["PROJ-1", "PROJ-2"],
  "fieldIds": ["status", "assignee"],
  "maxResults": 100
}

Get Changelogs

text

GET /rest/api/3/issue/{issueIdOrKey}/changelog?startAt=0&maxResults=50

Get Changelogs by IDs

text

POST /rest/api/3/issue/{issueIdOrKey}/changelog/list

Body:

json

{
  "changelogIds": [10001, 10002]
}

---

Projects#

Get Projects

text

GET /rest/api/3/project

Get Project

text

GET /rest/api/3/project/{projectIdOrKey}

---

Users#

Get User

text

GET /rest/api/3/user?accountId={accountId}

Get Current User (Myself)

text

GET /rest/api/3/myself

Search Users

text

GET /rest/api/3/user/search?query={query}&maxResults={limit}

---

Issue Events#

Get Events (Admin)

text

GET /rest/api/3/events

---

DevOps Integration APIs#

Build Information API#

Submit Build Data

text

POST /rest/builds/0.1/bulk

Note: Requires Connect JWT token or OAuth token for on-premise integration.

Get Build by Key

text

GET /rest/builds/0.1/pipelines/{pipelineId}/builds/{buildNumber}

---

Error Handling#

StatusMeaning400Bad request or malformed data401Invalid credentials or expired token403Permission denied404Resource not found409Conflict429Rate limited - wait and retry500Internal server error

---

Notes#

• JQL (Jira Query Language): Use JQL for powerful issue search and filtering
• Issue IDs vs Keys: Use PROJ-123 format for keys, numeric ID for direct lookups
• Transition IDs: Get available transitions first via GET /rest/api/3/issue/{key}/transitions
• Account IDs: Jira Cloud uses account IDs for users - get them via the users API
• Bulk Operations: Use bulk endpoints for efficiency when creating/fetching multiple issues
• Expand: Use ?expand=changelog on issue GET to retrieve full change history