Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
contact:
email: ecosystem@atlassian.com
description: Jira Cloud platform REST API documentation
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
title: Jira Cloud platform REST JQL functions (apps) API
version: 1001.0.0-SNAPSHOT-82b018affa468e58f284fbe4df33536469d757df
servers:
- url: https://your-domain.atlassian.net
tags:
- description: This resource represents JQL function's precomputations. Precomputation is a mapping between custom function call and JQL fragment returned by this function. Use it to get and update precomputations.
name: JQL Functions (Apps)
paths:
/rest/api/3/jql/function/computation:
get:
deprecated: false
description: 'Returns the list of a function''s precomputations along with information about when they were created, updated, and last used. Each precomputation has a `value` \- the JQL fragment to replace the custom function clause with.
**Permissions required:** This API is only accessible to apps and apps can only inspect their own functions.
The new `read:app-data:jira` OAuth scope is 100% optional now, and not using it won''t break your app. However, we recommend adding it to your app''s scope list because we will eventually make it mandatory.'
operationId: getPrecomputations
parameters:
- description: "The function key in format:\n\n * Forge: `ari:cloud:ecosystem::extension/[App ID]/[Environment ID]/static/[Function key from manifest]`\n * Connect: `[App key]__[Module key]`"
in: query
name: functionKey
schema:
items:
default: ''
type: string
type: array
- description: The index of the first item to return in a page of results (page offset).
in: query
name: startAt
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: 100
format: int32
type: integer
- description: "[Order](#ordering) the results by a field:\n\n * `functionKey` Sorts by the functionKey.\n * `used` Sorts by the used timestamp.\n * `created` Sorts by the created timestamp.\n * `updated` Sorts by the updated timestamp."
in: query
name: orderBy
schema:
type: string
responses:
'200':
content:
application/json:
example: '{"isLast":true,"maxResults":100,"startAt":0,"total":1,"values":[{"arguments":["Test"],"created":"2023-10-14T05:25:20.000+0000","field":"issue","functionKey":"ari:cloud:ecosystem::extension/00000000-1111-2222-3333-4444444/111111-2222-3333-4444-55555/static/issuesWithText","functionName":"issuesWithText","id":"cf75a1b0-4ac6-4bd8-8a50-29a465a96520","operator":"in","updated":"2023-10-14T05:25:20.000+0000","used":"2023-10-14T05:25:20.000+0000","value":"issue in (TEST-1, TEST-2, TEST-3)"},{"arguments":["10001"],"created":"2023-10-14T05:25:20.000+0000","error":"Error message to be displayed to the user","field":"issue","functionKey":"ari:cloud:ecosystem::extension/00000000-1111-2222-3333-4444444/111111-2222-3333-4444-55555/static/issuesWithText","functionName":"issuesWithText","id":"2a854f11-d0e1-4260-aea8-64a562a7062a","operator":"=","updated":"2023-10-14T05:25:20.000+0000","used":"2023-10-14T05:25:20.000+0000"}]}'
schema:
$ref: '#/components/schemas/PageBean2JqlFunctionPrecomputationBean'
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the request is not authenticated as the app that provided the function.
'404':
description: Returned if the function is not found.
security:
- basicAuth: []
- OAuth2: []
summary: Get precomputations (apps)
tags:
- JQL Functions (Apps)
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes: []
state: Current
- scheme: OAuth2
scopes:
- read:app-data:jira
state: Beta
x-atlassian-connect-scope: READ
post:
deprecated: false
description: 'Update the precomputation value of a function created by a Forge/Connect app.
**Permissions required:** An API for apps to update their own precomputations.
The new `write:app-data:jira` OAuth scope is 100% optional now, and not using it won''t break your app. However, we recommend adding it to your app''s scope list because we will eventually make it mandatory.'
operationId: updatePrecomputations
parameters:
- in: query
name: skipNotFoundPrecomputations
schema:
default: false
type: boolean
requestBody:
content:
application/json:
example:
values:
- id: f2ef228b-367f-4c6b-bd9d-0d0e96b5bd7b
value: issue in (TEST-1, TEST-2, TEST-3)
- error: Error message to be displayed to the user
id: 2a854f11-d0e1-4260-aea8-64a562a7062a
schema:
$ref: '#/components/schemas/JqlFunctionPrecomputationUpdateRequestBean'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/JqlFunctionPrecomputationUpdateResponse'
description: 200 response
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/JqlFunctionPrecomputationUpdateErrorResponse'
description: Returned if the request is invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/JqlFunctionPrecomputationUpdateErrorResponse'
description: Returned if the request is not authenticated as the app that provided the function.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/JqlFunctionPrecomputationUpdateErrorResponse'
description: Returned if the function is not found.
security:
- basicAuth: []
- OAuth2: []
summary: Update precomputations (apps)
tags:
- JQL Functions (Apps)
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes: []
state: Current
- scheme: OAuth2
scopes:
- write:app-data:jira
state: Beta
x-atlassian-connect-scope: READ
/rest/api/3/jql/function/computation/search:
post:
deprecated: false
description: 'Returns function precomputations by IDs, along with information about when they were created, updated, and last used. Each precomputation has a `value` \- the JQL fragment to replace the custom function clause with.
**Permissions required:** This API is only accessible to apps and apps can only inspect their own functions.
The new `read:app-data:jira` OAuth scope is 100% optional now, and not using it won''t break your app. However, we recommend adding it to your app''s scope list because we will eventually make it mandatory.'
operationId: getPrecomputationsByID
parameters:
- description: "[Order](#ordering) the results by a field:\n\n * `functionKey` Sorts by the functionKey.\n * `used` Sorts by the used timestamp.\n * `created` Sorts by the created timestamp.\n * `updated` Sorts by the updated timestamp."
in: query
name: orderBy
schema:
type: string
requestBody:
content:
application/json:
example:
precomputationIDs:
- f2ef228b-367f-4c6b-bd9d-0d0e96b5bd7b
- 2a854f11-d0e1-4260-aea8-64a562a7062a
schema:
$ref: '#/components/schemas/JqlFunctionPrecomputationGetByIdRequest'
required: true
responses:
'200':
content:
application/json:
example: '{"notFoundPrecomputationIDs":["cce1ef75-d566-40f8-a1a8-a9067f70ad69","82583f5d-0a44-454b-a1f5-4e06838fbf80"],"precomputations":[{"arguments":["Test"],"created":"2023-10-14T05:25:20.000+0000","field":"issue","functionKey":"ari:cloud:ecosystem::extension/00000000-1111-2222-3333-4444444/111111-2222-3333-4444-55555/static/issuesWithText","functionName":"issuesWithText","id":"cf75a1b0-4ac6-4bd8-8a50-29a465a96520","operator":"in","updated":"2023-10-14T05:25:20.000+0000","used":"2023-10-14T05:25:20.000+0000","value":"issue in (TEST-1, TEST-2, TEST-3)"},{"arguments":["10001"],"created":"2023-10-14T05:25:20.000+0000","error":"Error message to be displayed to the user","field":"issue","functionKey":"ari:cloud:ecosystem::extension/00000000-1111-2222-3333-4444444/111111-2222-3333-4444-55555/static/issuesWithText","functionName":"issuesWithText","id":"2a854f11-d0e1-4260-aea8-64a562a7062a","operator":"=","updated":"2023-10-14T05:25:20.000+0000","used":"2023-10-14T05:25:20.000+0000"}]}'
schema:
$ref: '#/components/schemas/JqlFunctionPrecomputationGetByIdResponse'
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the request is not authenticated as the app that provided the function.
'404':
description: Returned if the function is not found.
security:
- basicAuth: []
- OAuth2: []
summary: Get precomputations by ID (apps)
tags:
- JQL Functions (Apps)
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes: []
state: Current
- scheme: OAuth2
scopes:
- read:app-data:jira
state: Beta
x-atlassian-connect-scope: READ
components:
schemas:
JqlFunctionPrecomputationBean:
additionalProperties: false
description: Jql function precomputation.
properties:
arguments:
description: The list of arguments function was invoked with.
items:
readOnly: true
type: string
readOnly: true
type: array
created:
description: The timestamp of the precomputation creation.
format: date-time
readOnly: true
type: string
error:
description: The error message to be displayed to the user.
readOnly: true
type: string
field:
description: The field the function was executed against.
readOnly: true
type: string
functionKey:
description: The function key.
readOnly: true
type: string
functionName:
description: The name of the function.
readOnly: true
type: string
id:
description: The id of the precomputation.
readOnly: true
type: string
operator:
description: The operator in context of which function was executed.
readOnly: true
type: string
updated:
description: The timestamp of the precomputation last update.
format: date-time
readOnly: true
type: string
used:
description: The timestamp of the precomputation last usage.
format: date-time
readOnly: true
type: string
value:
description: The JQL fragment stored as the precomputation.
readOnly: true
type: string
type: object
JqlFunctionPrecomputationUpdateErrorResponse:
additionalProperties: false
description: Error response returned updating JQL Function precomputations fails.
properties:
errorMessages:
description: The list of error messages produced by this operation.
items:
readOnly: true
type: string
readOnly: true
type: array
notFoundPrecomputationIDs:
description: List of precomputations that were not found.
items:
readOnly: true
type: string
readOnly: true
type: array
uniqueItems: true
type: object
JqlFunctionPrecomputationUpdateResponse:
additionalProperties: false
description: Result of updating JQL Function precomputations.
properties:
notFoundPrecomputationIDs:
description: List of precomputations that were not found and skipped. Only returned if the request passed skipNotFoundPrecomputations=true.
items:
readOnly: true
type: string
readOnly: true
type: array
uniqueItems: true
type: object
PageBean2JqlFunctionPrecomputationBean:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/JqlFunctionPrecomputationBean'
readOnly: true
type: array
type: object
JqlFunctionPrecomputationUpdateRequestBean:
additionalProperties: false
description: List of pairs (id and value) for precomputation updates.
properties:
values:
items:
$ref: '#/components/schemas/JqlFunctionPrecomputationUpdateBean'
type: array
type: object
writeOnly: true
JqlFunctionPrecomputationGetByIdResponse:
additionalProperties: false
description: Get precomputations by ID response.
properties:
notFoundPrecomputationIDs:
description: List of precomputations that were not found.
items:
readOnly: true
type: string
readOnly: true
type: array
precomputations:
description: The list of precomputations.
items:
$ref: '#/components/schemas/JqlFunctionPrecomputationBean'
readOnly: true
type: array
type: object
JqlFunctionPrecomputationGetByIdRequest:
additionalProperties: false
description: Request to fetch precomputations by ID.
properties:
precomputationIDs:
items:
type: string
writeOnly: true
type: array
writeOnly: true
type: object
writeOnly: true
JqlFunctionPrecomputationUpdateBean:
additionalProperties: false
description: Precomputation id and its new value.
properties:
error:
description: The error message to be displayed to the user if the given function clause is no longer valid during recalculation of the precomputation.
type: string
writeOnly: true
id:
description: The id of the precomputation to update.
type: string
writeOnly: true
value:
description: The new value of the precomputation.
type: string
writeOnly: true
required:
- id
type: object
writeOnly: true
securitySchemes:
OAuth2:
description: OAuth2 scopes for Jira
flows:
authorizationCode:
authorizationUrl: https://auth.atlassian.com/authorize
scopes:
delete:async-task:jira: Delete asynchronous task.
delete:attachment:jira: Delete issue attachments.
delete:avatar:jira: Delete system and custom avatars.
delete:comment.property:jira: Delete issue comment properties.
delete:comment:jira: Delete issue comments.
delete:dashboard.property:jira: Delete dashboard properties.
delete:dashboard:jira: Delete dashboards.
delete:field-configuration-scheme:jira: Delete field configuration schemes.
delete:field-configuration:jira: Delete field configurations.
delete:field.option:jira: Delete field options.
delete:field:jira: Delete fields.
delete:filter.column:jira: Delete filter columns.
delete:filter:jira: Delete filters.
delete:group:jira: Delete user groups.
delete:issue-link-type:jira: Delete issue link types.
delete:issue-link:jira: Delete issue links.
delete:issue-type-scheme:jira: Delete issue type schemes.
delete:issue-type-screen-scheme:jira: Delete issue type screen schemes.
delete:issue-type.property:jira: Delete issue type properties.
delete:issue-type:jira: Delete issue types.
delete:issue-worklog.property:jira: Delete issue worklog properties.
delete:issue-worklog:jira: Delete issue worklogs.
delete:issue.property:jira: Delete issue properties.
delete:issue.remote-link:jira: Delete issue remote links.
delete:issue:jira: Delete issues.
delete:permission-scheme:jira: Delete permission schemes.
delete:permission:jira: Delete permissions.
delete:project-category:jira: Delete project categories.
delete:project-role:jira: Delete project roles.
delete:project-version:jira: Delete project versions.
delete:project.avatar:jira: Delete project avatars.
delete:project.component:jira: Delete project components.
delete:project.property:jira: Delete project properties.
delete:project:jira: Delete projects and their details, such as issue types, project lead, and avatars.
delete:screen-scheme:jira: Delete screen schemes.
delete:screen-tab:jira: Delete screen tabs.
delete:screen:jira: Delete screens.
delete:screenable-field:jira: Delete screenable fields.
delete:user-configuration:jira: Delete user configurations.
delete:user.property:jira: Delete user properties.
delete:webhook:jira: Delete webhooks.
delete:workflow-scheme:jira: Delete workflow schemes.
delete:workflow.property:jira: Delete workflow properties.
delete:workflow:jira: Delete workflows.
manage:jira-configuration: Configure Jira settings that require the Jira administrators permission, for example, create projects and custom fields, view workflows, manage issue link types.
manage:jira-project: Create and edit project settings and create new project-level objects, for example, versions, components.
manage:jira-webhook: Manage Jira webhooks. Enables an OAuth app to register and unregister dynamic webhooks in Jira. It also provides for fetching of registered webhooks.
read:app-data:jira: Read app data.
read:application-role:jira: View application roles.
read:attachment:jira: View issue attachments.
read:audit-log:jira: View audit logs.
read:avatar:jira: View system and custom avatars.
read:comment.property:jira: View issue comment properties.
read:comment:jira: View issue comments.
read:custom-field-contextual-configuration:jira: Read custom field contextual configurations.
read:dashboard.property:jira: View dashboard properties.
read:dashboard:jira: View dashboards.
read:email-address:jira: View email addresses of all users regardless of the user's profile visibility settings.
read:field-configuration-scheme:jira: View field configuration schemes.
read:field-configuration:jira: Read field configurations.
read:field.default-value:jira: View field default values.
read:field.option:jira: View field options.
read:field.options:jira: Read field options.
read:field:jira: View fields.
read:filter.column:jira: View filter columns.
read:filter.default-share-scope:jira: View filter default share scopes.
read:filter:jira: View filters.
read:group:jira: View user groups.
read:instance-configuration:jira: View instance configurations.
read:issue-details:jira: View issue details.
read:issue-event:jira: Read issue events.
read:issue-field-values:jira: View issue field valueses.
read:issue-link-type:jira: View issue link types.
read:issue-link:jira: View issue links.
read:issue-meta:jira: View issue meta.
read:issue-security-level:jira: View issue security levels.
read:issue-security-scheme:jira: View issue security schemes.
read:issue-status:jira: View issue statuses.
read:issue-type-hierarchy:jira: Read issue type hierarchies.
read:issue-type-scheme:jira: View issue type schemes.
read:issue-type-screen-scheme:jira: View issue type screen schemes.
read:issue-type.property:jira: View issue type properties.
read:issue-type:jira: View issue types.
read:issue-worklog.property:jira: View issue worklog properties.
read:issue-worklog:jira: View issue worklogs.
read:issue.changelog:jira: View issue changelogs.
read:issue.property:jira: View issue properties.
read:issue.remote-link:jira: View issue remote links.
read:issue.time-tracking:jira: View issue time trackings.
read:issue.transition:jira: View issue transitions.
read:issue.vote:jira: View issue votes.
read:issue.votes:jira: View issue voteses.
read:issue.watcher:jira: View issue watchers.
read:issue:jira: View issues.
read:jira-expressions:jira: View jira expressions.
read:jira-user: View user information in Jira that you have access to, including usernames, email addresses, and avatars.
read:jira-work: Read project and issue data. Search for issues and objects associated with issues (such as attachments and worklogs).
read:jql:jira: View JQL.
read:label:jira: View labels.
read:license:jira: View licenses.
read:notification-scheme:jira: View notification schemes.
read:permission-scheme:jira: View permission schemes.
read:permission:jira: View permissions.
read:priority:jira: View priorities.
read:project-category:jira: View project categories.
read:project-role:jira: View project roles.
read:project-type:jira: View project types.
read:project-version:jira: View project versions.
read:project.avatar:jira: Read project avatars.
read:project.component:jira: View project components.
read:project.email:jira: View project emails.
read:project.feature:jira: Read project features.
read:project.property:jira: View project properties.
read:project:jira: View projects.
read:resolution:jira: View resolutions.
read:role:jira: View roles.
read:screen-field:jira: View screen fields.
read:screen-scheme:jira: View screen schemes.
read:screen-tab:jira: View screen tabs.
read:screen:jira: View screens.
read:screenable-field:jira: View screenable fields.
read:status:jira: View statuses.
read:user-configuration:jira: View user configurations.
read:user.columns:jira: View user columnses.
read:user.property:jira: View user properties.
read:user:jira: View users.
read:webhook:jira: View webhooks.
read:workflow-scheme:jira: View workflow schemes.
read:workflow.property:jira: View workflow properties.
read:workflow:jira: View workflows.
send:notification:jira: Send notifications.
validate:jql:jira: Validate JQL.
write:app-data:jira: Write app data.
write:attachment:jira: Create and update issue attachments.
write:avatar:jira: Create and update system and custom avatars.
write:comment.property:jira: Create and update issue comment properties.
write:comment:jira: Create and update issue comments.
write:custom-field-contextual-configuration:jira: Save custom field contextual configurations.
write:dashboard.property:jira: Create and update dashboard properties.
write:dashboard:jira: Create and update dashboards.
write:field-configuration-scheme:jira: Create and update field configuration schemes.
write:field-configuration:jira: Save field configurations.
write:field.default-value:jira: Create and update field default values.
write:field.option:jira: Create and update field options.
write:field:jira: Create and update fields.
write:filter.column:jira: Create and update filter columns.
write:filter.default-share-scope:jira: Create and update filter default share scopes.
write:filter:jira: Create and update filters.
write:group:jira: Create and update user groups.
write:instance-configuration:jira: Create and update instance configurations.
write:issue-link-type:jira: Create and update issue link types.
write:issue-link:jira: Create and update issue links.
write:issue-type-scheme:jira: Create and update issue type schemes.
write:issue-type-screen-scheme:jira: Create and update issue type screen schemes.
write:issue-type.property:jira: Create and update issue type properties.
write:issue-type:jira: Create and update issue types.
write:issue-worklog.property:jira: Create and update issue worklog properties.
write:issue-worklog:jira: Create and update issue worklogs.
write:issue.property:jira: Create and update issue properties.
write:issue.remote-link:jira: Create and update issue remote links.
write:issue.time-tracking:jira: Create and update issue time trackings.
write:issue.vote:jira: Create and update issue votes.
write:issue.watcher:jira: Create and update issue watchers.
write:issue:jira: Create and update issues.
write:jira-work: Create and edit issues in Jira, post comments, create worklogs, and delete issues.
write:permission-scheme:jira: Create and update permission schemes.
write:permission:jira: Create and update permissions.
write:project-category:jira: Create and update project categories.
write:project-role:jira: Create and update project roles.
write:project-version:jira: Create and update project versions.
write:project.avatar:jira: Create and update project avatars.
write:project.component:jira: Create and update project components.
write:project.email:jira: Create and update project emails.
write:project.feature:jira: Save project features.
write:project.property:jira: Create and update project properties.
write:project:jira: Create and update projects.
write:screen-scheme:jira: Create and update screen schemes.
write:screen-tab:jira: Create and update screen tabs.
write:screen:jira: Create and update screens.
write:screenable-field:jira: Create and update screenable fields.
write:user-configuration:jira: Create and update user configurations.
write:user.property:jira: Create and update user properties.
write:webhook:jira: Create and update webhooks.
write:workflow-scheme:jira: Create and update workflow schemes.
write:workflow.property:jira: Create and update workflow properties.
write:workflow:jira: Create and update workflows.
tokenUrl: https://auth.atlassian.com/oauth/token
type: oauth2
basicAuth:
description: You can access this resource via basic auth.
scheme: basic
type: http
externalDocs:
description: Find out more about Atlassian products and services.
url: http://www.atlassian.com
x-atlassian-narrative:
documents:
- anchor: about
body: "The Jira REST API enables you to interact with Jira programmatically. Use this API to \n[build apps](https://developer.atlassian.com/cloud/jira/platform/integrating-with-jira-cloud/), script interactions with \nJira, or develop any other type of integration. This page documents the REST resources available in Jira Cloud, including \nthe 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\nversion. [Version 2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/) and\nversion 3 of the API offer the same collection of operations. However, version 3 provides support for\nthe [Atlassian Document Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)\n(ADF) in:\n- `body` in comments, including where comments are used in issue, issue link, and transition resources.\n- `comment` in worklogs.\n- `description` and `environment` fields in issues.\n- `textarea` type custom fields (multi-line text fields) in issues. Single line custom fields\n (`textfield`) accept a string and don't handle Atlassian Document Format content.\n"
title: Version
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/jira/refs/heads/main/openapi/jira-jql-functions-apps-api-openapi.yml