Atlassian Jira Expression API
The Atlassian Jira Expression API enables creating custom expressions for complex calculations and data operations within Jira.
OpenAPI Specification
components:
schemas:
JiraExpressionsAnalysis:
additionalProperties: false
description: Details about the analysed Jira expression.
properties:
results:
description: The results of Jira expressions analysis.
items:
$ref: '#/components/schemas/JiraExpressionAnalysis'
type: array
required:
- results
type: object
JiraExpressionResult:
additionalProperties: false
description: The result of evaluating a Jira expression.
properties:
meta:
allOf:
- $ref: '#/components/schemas/JiraExpressionEvaluationMetaDataBean'
description: >-
Contains various characteristics of the performed expression
evaluation.
value:
description: >-
The value of the evaluated expression. It may be a primitive JSON
value or a Jira REST API object. (Some expressions do not produce
any meaningful results—for example, an expression that returns a
lambda function—if that's the case a simple string representation is
returned. These string representations should not be relied upon and
may change without notice.)
required:
- value
type: object
externalDocs:
description: Find out more about Atlassian products and services.
url: http://www.atlassian.com
info:
contact:
email: [email protected]
description: Needs description.
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: http://atlassian.com/terms/
title: 'Atlassian rest/api/3/expression/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/expression/analyse:
post:
deprecated: false
description: >-
Analyses and validates Jira expressions.<br><br>As an experimental
feature, this operation can also attempt to type-check the
expressions.<br><br>Learn more about Jira expressions in the
[documentation](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/).<br><br>**[Permissions](#permissions)
required**: None.
operationId: atlassianAnalyseexpression
parameters:
- description: |-
The check to perform:
* `syntax` Each expression's syntax is checked to ensure the expression can be parsed. Also, syntactic limits are validated. For example, the expression's length.
* `type` EXPERIMENTAL. Each expression is type checked and the final type of the expression inferred. Any type errors that would result in the expression failure at runtime are reported. For example, accessing properties that don't exist or passing the wrong number of arguments to functions. Also performs the syntax check.
* `complexity` EXPERIMENTAL. Determines the formulae for how many [expensive operations](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/#expensive-operations) each expression may execute.
in: query
name: check
schema:
default: syntax
enum:
- syntax
- type
- complexity
type: string
requestBody:
content:
application/json:
example:
contextVariables:
listOfStrings: List<String>
record: '{ a: Number, b: String }'
value: User
expressions:
- issues.map(issue => issue.properties['property_key'])
schema:
$ref: '#/components/schemas/JiraExpressionForAnalysis'
description: The Jira expressions to analyse.
required: true
responses:
'200':
content:
application/json:
example: >-
{"results":[{"expression":"analysed
expression","errors":[{"line":1,"column":4,"message":"!, -,
typeof, (, IDENTIFIER, null, true, false, NUMBER, STRING,
TEMPLATE_LITERAL, new, [ or { expected, >
encountered.","type":"syntax"},{"message":"Jira expression is
too long (1040), limit: 1000
characters","type":"other"},{"message":"Jira expression has too
many nodes (150), limit: 100
leaves","type":"other"}],"valid":false},{"expression":"issues.map(i
=> {idAndKey: [i.id, i.key], summary: i.summary, comments:
i.comments})","valid":true,"type":"List<{idAndKey: [Number,
String], summary: String, comments:
List<Comment>}>","complexity":{"expensiveOperations":"N","variables":{"N":"issues"}}},{"expression":"issues.map(i
=> i.id > '0')","errors":[{"expression":"i.id >
0","message":"Can't compare Number to
String.","type":"type"}],"valid":false,"type":"TypeError"}]}
schema:
$ref: '#/components/schemas/JiraExpressionsAnalysis'
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: 400 response
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: 404 response
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- read:jira-user
- {}
summary: Atlassian Analyse Jira Expression
tags:
- Jira Expressions
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
- read:jira-user
state: Current
- scheme: OAuth2
scopes:
- read:field:jira
- read:jira-expressions:jira
state: Beta
x-atlassian-connect-scope: READ
/rest/api/3/expression/eval:
post:
deprecated: false
description: >-
Evaluates a Jira expression and returns its value.<br><br>This resource
can be used to test Jira expressions that you plan to use elsewhere, or
to fetch data in a flexible way. Consult the [Jira expressions
documentation](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/)
for more details.<br><br>#### Context variables ####<br><br>The
following context variables are available to Jira expressions evaluated
by this resource. Their presence depends on various factors; usually you
need to manually request them in the context object sent in the payload,
but some of them are added automatically under certain
conditions.<br><br> * `user`
([User](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#user)):
The current user. Always available and equal to `null` if the request is
anonymous.<br> * `app`
([App](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#app)):
The [Connect
app](https://developer.atlassian.com/cloud/jira/platform/index/#connect-apps)
that made the request. Available only for authenticated requests made by
Connect Apps (read more here: [Authentication for Connect
apps](https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/)).<br>
* `issue`
([Issue](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)):
The current issue. Available only when the issue is provided in the
request context object.<br> * `issues`
([List](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#list)
of
[Issues](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)):
A collection of issues matching a JQL query. Available only when JQL is
provided in the request context object.<br> * `project`
([Project](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#project)):
The current project. Available only when the project is provided in the
request context object.<br> * `sprint`
([Sprint](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#sprint)):
The current sprint. Available only when the sprint is provided in the
request context object.<br> * `board`
([Board](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#board)):
The current board. Available only when the board is provided in the
request context object.<br> * `serviceDesk`
([ServiceDesk](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#servicedesk)):
The current service desk. Available only when the service desk is
provided in the request context object.<br> * `customerRequest`
([CustomerRequest](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#customerrequest)):
The current customer request. Available only when the customer request
is provided in the request context object.<br><br>Also, custom context
variables can be passed in the request with their types. Those variables
can be accessed by key in the Jira expression. These variable types are
available for use in a custom context:<br><br> * `user`: A
[user](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#user)
specified as an Atlassian account ID.<br> * `issue`: An
[issue](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)
specified by ID or key. All the fields of the issue object are available
in the Jira expression.<br> * `json`: A JSON object containing custom
content.<br> * `list`: A JSON list of `user`, `issue`, or `json`
variable types.<br><br>This operation can be accessed
anonymously.<br><br>**[Permissions](#permissions) required**: None.
However, an expression may return different results for different users
depending on their permissions. For example, different users may see
different comments on the same issue. <br>Permission to access Jira
Software is required to access Jira Software context variables (`board`
and `sprint`) or fields (for example, `issue.sprint`).
operationId: atlassianEvaluatejiraexpression
parameters:
- description: >-
Use [expand](#expansion) to include additional information in the
response. This parameter accepts `meta.complexity` that returns
information about the expression complexity. For example, the number
of expensive operations used by the expression and how close the
expression is to reaching the [complexity
limit](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/#restrictions).
Useful when designing and debugging your expressions.
in: query
name: expand
schema:
type: string
requestBody:
content:
application/json:
example:
context:
board: 10100
custom:
config:
type: json
value:
userId: '10002'
issuesList:
- key: ACJIRA-1471
type: issue
- id: 100001
type: issue
myUser:
accountId: '100001'
type: user
nullField:
type: json
customerRequest: 1450
issue:
key: ACJIRA-1470
issues:
jql:
maxResults: 100
query: project = HSP
startAt: 0
validation: strict
project:
key: ACJIRA
serviceDesk: 10023
sprint: 10001
expression: >-
{ key: issue.key, type: issue.issueType.name, links:
issue.links.map(link => link.linkedIssue.id),
listCustomVariable: issuesList.includes(issue), customVariables:
myUser.accountId == config.userId}
schema:
$ref: '#/components/schemas/JiraExpressionEvalRequestBean'
description: The Jira expression and the evaluation context.
required: true
responses:
'200':
content:
application/json:
example: >-
{"value":"The expression's result. This value can be any JSON,
not necessarily a
String","meta":{"complexity":{"steps":{"value":1,"limit":10000},"expensiveOperations":{"value":3,"limit":10},"beans":{"value":0,"limit":1000},"primitiveValues":{"value":1,"limit":10000}},"issues":{"jql":{"startAt":0,"maxResults":1000,"count":140,"totalCount":140,"validationWarnings":["There
is a problem with the JQL query."]}}}}
schema:
$ref: '#/components/schemas/JiraExpressionResult'
description: >-
Returned if the evaluation results in a value. The result is a JSON
primitive value, list, or object.
'400':
content:
application/json:
example: >-
{"errorMessages":["Evaluation failed: \"issue['a' + 'b']\" -
Unrecognized property of `issue`: \"ab\" ('a' + 'b'). Available
properties of type 'Issue' are: 'assignee', 'comments',
'description', 'id', 'issueType', 'key', 'priority', 'project',
'properties', 'reporter', 'status', 'summary'"],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: |-
Returned if:
* the request is invalid, that is:
* invalid data is provided, such as a request including issue ID and key.
* the expression is invalid and can not be parsed.
* evaluation fails at runtime. This may happen for various reasons. For example, accessing a property on a null object (such as the expression `issue.id` where `issue` is `null`). In this case an error message is provided.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
content:
application/json:
example: >-
{"errorMessages":["Issue does not exist or you do not have
permission to see it."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: >-
Returned if any object provided in the request context is not found
or the user does not have permission to view it.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- read:jira-user
- {}
summary: Atlassian Evaluate Jira Expression
tags:
- Jira Expressions
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
- read:jira-user
state: Current
- scheme: OAuth2
scopes:
- read:jira-expressions:jira
state: Beta
x-atlassian-connect-scope: READ
servers:
- url: https://your-domain.atlassian.net
tags:
- name: Jira Expressions
x-atlassian-narrative:
documents:
- anchor: about
body: >-
The Jira REST API enables you to interact with Jira programmatically.
Use this API to
[build
apps](https://developer.atlassian.com/cloud/jira/platform/integrating-with-jira-cloud/),
script interactions with
Jira, or develop any other type of integration. This page documents the
REST resources available in Jira Cloud, including
the HTTP response codes and example requests and responses.
title: About
- anchor: version
body: >
This documentation is for **version 3** of the Jira Cloud platform REST
API, which is the latest version
but is in **beta**. [Version
2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/) and
version 3 of the API offer the same collection of operations. However,
version 3 provides support for
the [Atlassian Document
Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)
(ADF) in:
- `body` in comments, including where comments are used in issue, issue
link, and transition resources.
- `comment` in worklogs.
- `description` and `environment` fields in issues.
- `textarea` type custom fields (multi-line text fields) in issues.
Single line custom fields
(`textfield`) accept a string and don't handle Atlassian Document Format content.
However, these new features are under development and may change.
title: Version
- anchor: authentication
body: >
### Forge apps
For Forge apps, [REST API
scopes](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/)
are used when authenticating with Jira Cloud platform. See [Add scopes
to call an Atlassian REST
API](https://developer.atlassian.com/platform/forge/add-scopes-to-call-an-atlassian-rest-api/)
for more details.
The URIs for Forge app REST API calls have this structure:
`/rest/api/3/<resource-name>`
For example, `/rest/api/3/issue/DEMO-1`
### Connect apps
For Connect apps, authentication (JWT-based) is built into the Connect
libraries. Authorization is implemented using either
scopes (shown as _App scope required_ for operations on this page) or
user impersonation. See
[Security for Connect
apps](https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/)
for details.
The URIs for Connect app REST API calls have this structure:
`https://<site-url>/rest/api/3/<resource-name>`
For example, `https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1`
### Other integrations
For integrations that are not Forge or Connect apps, use OAuth 2.0
authorization code grants (3LO) for security
(3LO scopes are shown as for operations _OAuth scopes required_). See
[OAuth 2.0 (3LO)
apps](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)
for details.
The URIs for OAuth 2.0 (3LO) app REST API calls have this structure:
`https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/<resource-name>`
For example,
`https://api.atlassian.com/ex/jira/35273b54-3f06-40d2-880f-dd28cf8daafa/rest/api/3/issue/DEMO-1`
### Ad-hoc API calls
For personal scripts, bots, and ad-hoc execution of the REST APIs use
basic authentication. See [Basic auth for REST
APIs](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/)
for details.
The URIs for basic authentication REST API calls have this structure:
`https://<site-url>/rest/api/3/<resource-name>`
For example, `https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1`
title: Authentication and authorization
- anchor: permissions
body: >
### Operation permissions
Most operations in this API require permissions. The calling user must
have the required permissions for an operation to
use it. Note that for Connect apps, the app user must have the required
permissions for the operation and the app must
have scopes that permit the operation.
A permission can be granted to a group, project role, or issue role that
the user is a member of, or granted directly to a user.
See [Permissions overview](https://confluence.atlassian.com/x/FQiiLQ)
for details. The most common permissions are:
- **Administer the Cloud site**: Users in the _site-admins_ group have
this
permission. See [Manage
groups](https://confluence.atlassian.com/x/24xjL) for details.
- **Administer Jira**: Granted by the _Jira Administrators_ global
permission. There is a default group for this permission.
See [Manage groups](https://confluence.atlassian.com/x/24xjL) and
[Managing global permissions](https://confluence.atlassian.com/x/x4dKLg)
for details.
- **Administer a project in Jira**: Granted by the _Administer projects_
project permission for a project. This can be
granted to a user, a group, a project role, and more.
See [Managing project
permissions](https://confluence.atlassian.com/x/yodKLg) for details.
- **Access a project in Jira**: Granted by the _Browse projects_ project
permission for a project. This can be
granted to a user, a group, a project role, and more.
See [Managing project
permissions](https://confluence.atlassian.com/x/yodKLg) for details.
- **Access Jira**: Granted by the _Jira Users_ global permission. Users
in the default product access group (for example,
_jira-software-users-acmesite_) have this permission.
See [Manage groups](https://confluence.atlassian.com/x/24xjL) and
[Managing global permissions](https://confluence.atlassian.com/x/x4dKLg)
for details.
### Anonymous access
Some operations provide support for anonymous access. However, anonymous
access is only available if
the Jira permission needed to access the object or records returned by
the operation is granted to
the _Public_ group. See [Allowing anonymous access to your
project](https://confluence.atlassian.com/x/GDxxLg)
for details.
If an operation is called anonymously and anonymous access is not
available, the operation will return
an error. Note that not all operations that correspond to objects that
can be given public access
provide for anonymous access.
title: Permissions
- anchor: expansion
body: >+
### Expansion
The Jira REST API uses resource expansion, which means that some parts
of a resource are not returned unless specified
in the request. This simplifies responses and minimizes network traffic.
To expand part of a resource in a request, use the expand query
parameter and specify the object(s) to be expanded.
If you need to expand nested objects, use the `.` dot notation. If you
need to expand multiple objects, use a
comma-separated list.
For example, the following request expands the `names` and
`renderedFields` properties for the _JRACLOUD-34423_ issue:
`GET issue/JRACLOUD-34423?expand=names,renderedFields`
To discover which object can be expanded, refer to the `expand` property
in the object.
In the JSON example below, the resource declares `widgets` as
expandable.
```json
{
"expand": "widgets",
"self": "https://your-domain.atlassian.net/rest/api/3/resource/KEY-1",
"widgets": {
"widgets": [],
"size": 5
}
}
```
### Pagination
The Jira REST API uses pagination to improve performance. Pagination is
enforced for operations that could return a large
collection of items. When you make a request to a paginated resource,
the response wraps the returned array of values in
a JSON object with paging metadata. For example:
```json
{
"startAt" : 0,
"maxResults" : 10,
"total": 200,
"isLast": false,
"values": [
{ /* result 0 */ },
{ /* result 1 */ },
{ /* result 2 */ }
]
}
```
* `startAt` is the index of the first item returned in the page.
* `maxResults` is the maximum number of items that a page can return.
Each operation can have a different limit for
the number of items returned, and these limits may change without notice. To find the maximum number of items
that an operation could return, set `maxResults` to a large number—for example, over 1000—and if the returned value of `maxResults` is less than the requested value, the returned value is the maximum.
* `total` is the total number of items contained in all pages. This
number **_may change_** as the client
requests the subsequent pages, therefore the client should always assume
that the requested page can be empty. Note
that this property is not returned for all operations.
* `isLast` indicates whether the page returned is the last one. Note
that this property is not returned for all operations.
### Ordering
Some operations support ordering the elements of a response by a field.
Check the documentation for the operation to
confirm whether ordering of a response is supported and which fields can
be used. Responses are listed in ascending order
by default. You can change the order using the `orderby` query parameter
with a `-` or `+` symbol. For example:
* `?orderBy=name` to order by `name` field ascending.
* `?orderBy=+name` to order by `name` field ascending.
* `?orderBy=-name` to order by `name` field descending.
title: Expansion, pagination, and ordering
- anchor: timestamps
body: >
By default, top-level timestamps (e.g. updated and created) are returned
in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format, in the system
default user time zone.
To return date time data in the logged in user's timezone, please refer
to `renderedFields` property under the `expand` query parameter in
relevant APIs.
title: Timestamps
- anchor: special-request-headers
body: >-
The following request and response headers define important metadata for
the Jira Cloud REST API resources.
- `X-Atlassian-Token` (request): Operations that accept
multipart/form-data must include the `X-Atlassian-Token: no-check`
header in requests. Otherwise the request is blocked by cross-site
request forgery (CSRF/XSRF) protection.
- `X-Force-Accept-Language` (request): controls how the standard HTTP
`Accept-Language` header is processed.
By default `Accept-Language` is ignored and the response is in the
language configured in the user's profile or,
when no language is configured for the user, the default Jira instance
language. For the response to recognize
`Accept-Language` send `X-Force-Accept-Language = true` as well. If
`Accept-Language` requests a language that Jira
can return the response is in that language, otherwise Jira returns the
response in the default language. If
`Accept-Language` is not specified the response is in the default
language.
- `X-AAccountId` (response): This response header contains the
Atlassian account ID of the authenticated user.
title: Special headers
- anchor: anonymous-operations
body: |2-
Jira provides for all permissions, except the [global permission](https://confluence.atlassian.com/x/x4dKLg) Administer Jira, to be assigned to *Anyone*. Once a permission is assigned to *Anyone*, anyone knowing a project's URL is able to use the features in Jira enabled by the permission. However, the Jira REST API does not enable anonymous access for operations by default. This means that an anonymous user who may be able to perform an action through Jira, may not be able to perform the same action where it's enabled by the REST API.
The operations that provide anonymous access are annotated "This operation can be accessed anonymously."
title: Anonymous operations
- anchor: async-operations
body: >-
Some Jira REST API operations may trigger long-running or
computationally expensive tasks. In these cases, the operation
will schedule an asynchronous task and return a `303 (See Other)`
response, indicating the location of the queued task
in the `Location` header. You can query this task to get progress
updates.
When the task finishes, the response object will contain the `result`
field. The content of the field is specific to the
operation that created the task. Refer to the operation’s documentation
for more information.
Note that asynchronous tasks are not guaranteed to be run in order. In
other words, if you need your tasks to execute
in a certain order, you should start a task only after the prerequisite
task(s) have finished.
title: Asynchronous operations
- anchor: experimental
body: >
Features and methods marked as experimental may change without notice.
Feedback on experimental functionality is welcome.
Report your suggestions and bugs in the [ACJIRA
project](https://ecosystem.atlassian.net/projects/ACJIRA) (preferred) or
use the
**Give docs feedback** link at the top of this page.
title: Experimental features
- anchor: status-codes
body: >-
The Jira Cloud platform REST API uses the [standard HTTP status
codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).
Operations that return an error status code may also return a response
body containing details of the error or errors.
The schema for the response body is shown below:
```json
{
"id": "https://docs.atlassian.com/jira/REST/schema/error-collection#",
"title": "Error Collection",
"type": "object",
"properties": {
"errorMessages": {
"type": "array",
"items": {
"type": "string"
}
},
"errors": {
"type": "object",
"patternProperties": {
".+": {
"type": "string"
}
},
"additionalProperties": false
},
"status": {
"type": "integer"
}
},
"additionalProperties": false
}
```
title: Status codes