View Source

Beginners guide

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

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:

Example

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

Node.js

// 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));

# 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

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

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

# 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=(",", ": ")))

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

Returned if the request is invalid.

A schema has not been defined for this response code.

Returned if the user is not logged in.

A schema has not been defined for this response code.

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

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'

# 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=(",", ": ")))

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

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

# 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=(",", ": ")))

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

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

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

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

# 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=(",", ": ")))

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

# 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=(",", ": ")))

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