Page History

Beginners guide

Info
This documentation refers to Jira Data Center only.

Jira REST APIs

Jira has REST APIs and Java APis that you can use to interact with Jira. For example, you may want to integrate your existing application with Jira or write a script to get information from Jira. For more information, check out our reference documentation:

Authentication

The following authentication methods are supported for the Jira REST APIs:

Recommended:
- OAuth 2.0 - This method provides APIs to allow external services to access resources on a user's behalf with the OAuth 2.0 protocol. This protocol is not compatible with Oauth 1.0a.
- Personal access token (PAT) - This method incorporates the user account in the access token. It is a safe alternative to using username and password for authentication with various services.
Other:
- OAuth 1.0a - This method provides APIs to allow external services to access resources on a user's behalf with the OAuth 1.0 protocol. This protocol is deprecated.
- Basic HTTP - This method is only recommended for tools like scripts or bots. It is easier to implement but much less secure.

Jira uses cookie-based authentication in the browser, so you can call the REST API from Javascript on the page and rely on the authentication the browser has established. To reproduce the behavior of the Jira log-in page, you can POST to the /auth/1/session resource. You can use it, for example, to display authentication error messages to users.

API Calls:

Backlog

Expand

title	Update issues to move them to the backlog

POST /rest/agile/1.0/backlog/issue

Move issues to the backlog. This operation is equivalent to remove future and active sprints from a given set of issues. At most 50 issues may be moved at once.

Request

Body parameters

issues

Array<string>

Unique items:

Status


title	TRUE

Example

Expand

title	cURL

Code Block
curl --request POST \ --url 'http://{baseurl}/rest/agile/1.0/backlog/issue' \ --user 'email@example.com:<api_token>' \ --header 'Content-Type: application/json'

Expand

title	Node.js

Node.js

Code Block

// This code sample uses the 'node-fetch' library:
// https://www.npmjs.com/package/node-fetch
const fetch = require('node-fetch');

fetch('http://{baseurl}/rest/agile/1.0/backlog/issue', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${Buffer.from(
      'email@example.com:<api_token>'
    ).toString('base64')}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => {
    console.log(
      `Response: ${response.status} ${response.statusText}`
    );
    return response.text();
  })
  .then(text => console.log(text))
  .catch(err => console.error(err));

Expand

title	Python

Code Block

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth

url = "http://{baseurl}/rest/agile/1.0/backlog/issue"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Content-Type": "application/json"
}

response = requests.request(
   "POST",
   url,
   headers=headers,
   auth=auth
)

print(response.text)

Boards

Expand

title	Boards

Expand

title	Get all boards

GET /rest/agile/1.0/board

Returns all boards. This only includes boards that the user has permission to view.

Request

Query parameters

maxResults

integer
Format: int32

name

string

projectKeyOrId

string

type

StringList

startAt

integer
Format: int64

Example

Code Block
curl --request GET \ --url 'http://{baseurl}/rest/agile/1.0/board' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'

Code Block

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/agile/1.0/board"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "GET",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

Status

colour	Green
title	200

Returns the requested boards, at the specified page of the results.

Status

colour	Yellow
title	400

Returned if the request is invalid.

A schema has not been defined for this response code.

Status


colour	Yellow
title	401

Returned if the user is not logged in.

A schema has not been defined for this response code.

Expand

title	Create a new board

POST /rest/agile/1.0/board

Creates a new board. Board name, type and filter Id is required.

name - Must be less than 255 characters.
type - Valid values: scrum, kanban
filterId - Id of a filter that the user has permissions to view. Note, if the user does not have the 'Create shared objects' permission and tries to create a shared board, a private board will be created instead (remember that board sharing depends on the filter sharing). Note:
If you want to create a new project with an associated board, use the JIRA platform REST API. For more information, see the Create project method. The projectTypeKey for software boards must be 'software' and the projectTemplateKey must be either com.pyxis.greenhopper.jira:gh-kanban-template or com.pyxis.greenhopper.jira:gh-scrum-template.
You can create a filter using the JIRA REST API. For more information, see the Create filter method.
If you do not ORDER BY the Rank field for the filter of your board, you will not be able to reorder issues on the board.

Request

Body parameters

filterId

integer

Format: int64

name

string

type

string

Code Block
curl --request POST \ --url 'http://{baseurl}/rest/agile/1.0/board' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json'

Code Block

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/agile/1.0/board"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json",
  "Content-Type": "application/json"
}

response = requests.request(
   "POST",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

Expand

title	Get a single board

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

Returns a single board, for a given board Id.

Request

Path parameters

boardId Required

integer
Format: int64

Example

Code Block
curl --request GET \ --url 'http://{baseurl}/rest/agile/1.0/board/{boardId}' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'

Code Block

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/agile/1.0/board/{boardId}"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "GET",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

Expand

title	Get all issues from the board's backlog

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

Returns all issues from a board's backlog, for a given board Id.

Request

Path parameters

boardId Required

integer
Format: int64

Query parameters

expand

string

jql

string

maxResults

integer
Format: int32

validateQuery

boolean

fields

Array<StringList>

startAt

integer
Format: int64

Example

Code Block
curl --request GET \ --url 'http://{baseurl}/rest/agile/1.0/board/{boardId}/backlog' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'

Expand

title	Get all epics from the board

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

Returns all epics from the board, for the given board Id. This only includes epics that the user has permission to view. Note, if the user does not have permission to view the board, no epics will be returned at all.

Request

Path parameters

boardId Required

integer
Format: int64

Query parameters

maxResults

integer
Format: int32

done

string

startAt

integer
Format: int64

Example

Code Block
curl --request GET \ --url 'http://{baseurl}/rest/agile/1.0/board/{boardId}/epic' \ --user 'email@example.com:<api_token>' \ --header 'Accept: application/json'

Code Block

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/agile/1.0/board/{boardId}/epic"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "GET",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

Expand

title	Get all issues without an epic

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

Returns all issues that do not belong to any epic on a board, for a given board Id.

Request

Path parameters

boardId Required

integer
Format: int64

Query parameters

expand

string

jql

string

maxResults

integer
Format: int32

validateQuery

boolean

fields

Array<StringList>

startAt

integer
Format: int64

Example

Code Block

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/agile/1.0/board/{boardId}/epic/none/issue"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "GET",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

Expand

title	Get all issues for a specific epic

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

Returns all issues that belong to an epic on the board, for the given epic Id and the board Id.

Request

Path parameters

epicId Required

integer
Format: int64

boardId Required

integer
Format: int64

Query parameters

expand

string

jql

string

maxResults

integer
Format: int32

validateQuery

boolean

fields

Array<StringList>

startAt

integer
Format: int64

Example

Code Block

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/agile/1.0/board/{boardId}/epic/{epicId}/issue"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "GET",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

Expand

title	Get all issues from a board

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

Returns all issues from a board, for a given board Id. This only includes issues that the user has permission to view. Note, if the user does not have permission to view the board, no issues will be returned at all. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank.

Request

Path parameters

boardId Required

integer
Format: int64

Query parameters

expand

string

jql

string

maxResults

integer
Format: int32

validateQuery

boolean

fields

Array<StringList>

startAt

integer
Format: int64

Example

Code Block

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/agile/1.0/board/{boardId}/issue"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "GET",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

Expand

title	Get all issues for a sprint

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

Get all issues you have access to that belong to the sprint from the board. Issue returned from this resource contains additional fields like: sprint, closedSprints, flagged and epic. Issues are returned ordered by rank. JQL order has higher priority than default rank.

Request

Path parameters

sprintId Required

integer
Format: int64

boardId Required

integer
Format: int64

Query parameters

expand

string

jql

string

maxResults

integer
Format: int32

validateQuery

boolean

fields

Array<StringList>

startAt

integer
Format: int64

Example

Code Block

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/agile/1.0/board/{boardId}/sprint/{sprintId}/issue"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "GET",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

Epics

Expand

title	Get issues without an epic

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

Returns all issues that do not belong to any epic. This only includes issues that the user has permission to view. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank.

Request

Query parameters

expand

string

jql

string

maxResults

integer
Format: int32

validateQuery

boolean

fields

Array<StringList>

startAt

integer
Format: int64

Example

Code Block

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/agile/1.0/epic/none/issue"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "GET",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

Expand

title	Remove issues from any epic

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

Removes issues from epics. The user needs to have the edit issue permission for all issue they want to remove from epics. The maximum number of issues that can be moved in one operation is 50.

Request

Body parameters

issues

Array<string>

Unique items: true

Example

Code Block

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth

url = "http://{baseurl}/rest/agile/1.0/epic/none/issue"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Content-Type": "application/json"
}

response = requests.request(
   "POST",
   url,
   headers=headers,
   auth=auth
)

print(response.text)

Expand

title	Get an epic by id or key

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

Returns the epic for a given epic Id. This epic will only be returned if the user has permission to view it.

Request

Path parameters

epicIdOrKey Required

string

Example

Code Block

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json

url = "http://{baseurl}/rest/agile/1.0/epic/{epicIdOrKey}"

auth = HTTPBasicAuth("email@example.com", "<api_token>")

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "GET",
   url,
   headers=headers,
   auth=auth
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

Jira architecture

Atlassian's architecture documentation will help you understand Jira fundamentals and get a high-level perspective of Jira's dependencies.

It covers such topics as webhooks, web panels, web fragments, authentication, and templates.

Learn more about Jira architecture

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 45

New Version 46

Key

Beginners guide

Jira REST APIs

Authentication

API Calls:

Request

Body parameters

Example

Request

Query parameters

Request

Body parameters

Request

Path parameters

Request

Path parameters

Query parameters

Example

Request

Path parameters

Query parameters

Example

Request

Path parameters

Query parameters

Example

Request

Path parameters

Query parameters

Example

Request

Path parameters

Query parameters

Example

Request

Path parameters

Query parameters

Example

Epics

Request

Query parameters

Example

Request

Body parameters

Example

Request

Path parameters

Example

Jira architecture