openapi: 3.1.0
info:
title: Atlassian Admin Account Issue Search API
description: The Atlassian Admin API provides programmatic access to manage Atlassian organizations, users, domains, policies, and events. It enables administrators to automate organization management tasks, integrate with identity providers, and ensure appropriate access to Atlassian products.
version: 1.0.0
contact:
name: Atlassian Developer
url: https://developer.atlassian.com/cloud/admin/
license:
name: Atlassian Developer Terms
url: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
x-logo:
url: https://wac-cdn.atlassian.com/assets/img/favicons/atlassian/favicon.png
servers:
- url: https://api.atlassian.com
description: Atlassian Cloud API
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Issue Search
paths:
/rest/api/3/issue/picker:
get:
deprecated: false
description: Returns lists of issues matching a query string. Use this resource to provide auto-completion suggestions when the user is looking for an issue using a word or string.
This operation returns two lists:
* `History Search` which includes issues from the user's history of created, edited, or viewed issues that contain the string in the `query` parameter.
* `Current Search` which includes issues that match the JQL expression in `currentJQL` and contain the string in the `query` parameter.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
operationId: atlassianGetissuepickerresource
parameters:
- description: A string to match against text fields in the issue such as title, description, or comments.
in: query
name: query
schema:
example: query
type: string
x-showInExample: 'true'
- description: A JQL query defining a list of issues to search for the query term. Note that `username` and `userkey` cannot be used as search terms for this parameter, due to privacy reasons. Use `accountId` instead.
in: query
name: currentJQL
schema:
type: string
- description: The key of an issue to exclude from search results. For example, the issue the user is viewing when they perform this query.
in: query
name: currentIssueKey
schema:
type: string
- description: The ID of a project that suggested issues must belong to.
in: query
name: currentProjectId
schema:
type: string
- description: Indicate whether to include subtasks in the suggestions list.
in: query
name: showSubTasks
schema:
type: boolean
- description: When `currentIssueKey` is a subtask, whether to include the parent issue in the suggestions if it matches the query.
in: query
name: showSubTaskParent
schema:
type: boolean
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/IssuePickerSuggestions'
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- {}
summary: Atlassian Get Issue Picker Suggestions
tags:
- Issue Search
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:issue-details:jira
state: Beta
x-atlassian-connect-scope: READ
/rest/api/3/jql/match:
post:
deprecated: false
description: Checks whether one or more issues would be returned by one or more JQL queries.
**[Permissions](#permissions) required:** None, however, issues are only matched against JQL queries where the user has:
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: atlassianMatchissues
parameters: []
requestBody:
content:
application/json:
example:
issueIds:
- 10001
- 1000
- 10042
jqls:
- project = FOO
- issuetype = Bug
- summary ~ "some text" AND project in (FOO, BAR)
schema:
$ref: '#/components/schemas/IssuesAndJQLQueries'
required: true
responses:
'200':
content:
application/json:
example: '{"matches":[{"matchedIssues":[10000,10004],"errors":[]},{"matchedIssues":[100134,10025,10236],"errors":[]},{"matchedIssues":[],"errors":[]},{"matchedIssues":[],"errors":["Invalid JQL: broken = value"]}]}'
schema:
$ref: '#/components/schemas/IssueMatches'
description: Returned if the request is successful.
'400':
description: Returned if `jqls` exceeds the maximum number of JQL queries or `issueIds` exceeds the maximum number of issue IDs.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
summary: Atlassian Check Issues Against Jql
tags:
- Issue Search
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:issue-details:jira
state: Beta
x-atlassian-connect-scope: READ
/rest/api/3/search/id:
post:
deprecated: false
description: Searches for IDs of issues using [JQL](https://confluence.atlassian.com/x/egORLQ).
Use the [Search](#api-rest-api-3-search-post) endpoint if you need to fetch more than just issue IDs. The Search endpoint returns more information, but may take much longer to respond to requests. This is because it uses a different mechanism for ordering results than this endpoint and doesn't provide the total number of results for your query.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** Issues are included in the response where the user has:
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project containing the issue.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: atlassianSearchforissuesids
parameters: []
requestBody:
content:
application/json:
example:
jql: project = HSP
maxResults: 1000
nextPageToken: EgQIlMIC
schema:
$ref: '#/components/schemas/IdSearchRequestBean'
description: A JSON object containing the search request.
required: true
responses:
'200':
content:
application/json:
example: '{"issueIds":[10000,10001,10002],"nextPageToken":"EgQIlMIC"}'
schema:
$ref: '#/components/schemas/IdSearchResults'
description: Returned if the request is successful.
'400':
description: Returned if the JQL query is invalid.
'401':
description: Returned if the authentication credentials are incorrect.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- {}
summary: Atlassian Search Issue Ids Using Jql
tags:
- Issue Search
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:issue-details:jira
- read:field.default-value:jira
- read:field.option:jira
- read:field:jira
- read:group:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: READ
/rest/api/3/search:
get:
deprecated: false
description: Searches for issues using [JQL](https://confluence.atlassian.com/x/egORLQ).
If the JQL query expression is too large to be encoded as a query parameter, use the [POST](#api-rest-api-3-search-post) version of this resource.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** Issues are included in the response where the user has:
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project containing the issue.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: atlassianSearchforissuesusingjql
parameters:
- description: "The [JQL](https://confluence.atlassian.com/x/egORLQ) that defines the search. Note:\n\n * If no JQL expression is provided, all issues are returned.\n * `username` and `userkey` cannot be used as search terms due to privacy reasons. Use `accountId` instead.\n * If a user has hidden their email address in their user profile, partial matches of the email address will not find the user. An exact match is required."
in: query
name: jql
schema:
example: project = HSP
type: string
x-showInExample: 'true'
- description: The index of the first item to return in a page of results (page offset).
in: query
name: startAt
schema:
default: 0
format: int32
type: integer
- description: The maximum number of items to return per page. To manage page size, Jira may return fewer items per page where a large number of fields are requested. The greatest number of items returned per page is achieved when requesting `id` or `key` only.
in: query
name: maxResults
schema:
default: 50
format: int32
type: integer
- description: "Determines how to validate the JQL query and treat the validation results. Supported values are:\n\n * `strict` Returns a 400 response code if any errors are found, along with a list of all errors (and warnings).\n * `warn` Returns all errors as warnings.\n * `none` No validation is performed.\n * `true` *Deprecated* A legacy synonym for `strict`.\n * `false` *Deprecated* A legacy synonym for `warn`.\n\nNote: If the JQL is not correctly formed a 400 response code is returned, regardless of the `validateQuery` value."
in: query
name: validateQuery
schema:
default: strict
enum:
- strict
- warn
- none
- 'true'
- 'false'
type: string
- description: "A list of fields to return for each issue, use it to retrieve a subset of fields. This parameter accepts a comma-separated list. Expand options include:\n\n * `*all` Returns all fields.\n * `*navigable` Returns navigable fields.\n * Any issue field, prefixed with a minus to exclude.\n\nExamples:\n\n * `summary,comment` Returns only the summary and comments fields.\n * `-description` Returns all navigable (default) fields except description.\n * `*all,-comment` Returns all fields except comments.\n\nThis parameter may be specified multiple times. For example, `fields=field1,field2&fields=field3`.\n\nNote: All navigable fields are returned by default. This differs from [GET issue](#api-rest-api-3-issue-issueIdOrKey-get) where the default is all fields."
in: query
name: fields
schema:
items:
default: '*navigable'
type: string
type: array
- description: "Use [expand](#expansion) to include additional information about issues in the response. This parameter accepts a comma-separated list. Expand options include:\n\n * `renderedFields` Returns field values rendered in HTML format.\n * `names` Returns the display name of each field.\n * `schema` Returns the schema describing a field type.\n * `transitions` Returns all possible transitions for the issue.\n * `operations` Returns all possible operations for the issue.\n * `editmeta` Returns information about how each field can be edited.\n * `changelog` Returns a list of recent updates to an issue, sorted by date, starting from the most recent.\n * `versionedRepresentations` Instead of `fields`, returns `versionedRepresentations` a JSON array containing each version of a field's value, with the highest numbered item representing the most recent version."
in: query
name: expand
schema:
type: string
- description: A list of issue property keys for issue properties to include in the results. This parameter accepts a comma-separated list. Multiple properties can also be provided using an ampersand separated list. For example, `properties=prop1,prop2&properties=prop3`. A maximum of 5 issue property keys can be specified.
in: query
name: properties
schema:
items:
type: string
type: array
- description: Reference fields by their key (rather than ID).
in: query
name: fieldsByKeys
schema:
default: false
type: boolean
responses:
'200':
content:
application/json:
example: '{"expand":"names,schema","issues":[{"expand":"","fields":{"watcher":{"isWatching":false,"self":"https://your-domain.atlassian.net/rest/api/3/issue/EX-1/watchers","watchCount":1,"watchers":[{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"}]},"attachment":[{"author":{"accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","active":false,"avatarUrls":{"16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32","48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"},"displayName":"Mia Krystof","key":"","name":"","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"content":"https://your-domain.atlassian.net/jira/rest/api/3/attachment/content/10000","created":"2022-10-06T07:32:47.000+0000","filename":"picture.jpg","id":10000,"mimeType":"image/jpeg","self":"https://your-domain.atlassian.net/rest/api/3/attachments/10000","size":23123,"thumbnail":"https://your-domain.atlassian.net/jira/rest/api/3/attachment/thumbnail/10000"}],"sub-tasks":[{"id":"10000","outwardIssue":{"fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/images/icons/statuses/open.png","name":"Open"}},"id":"10003","key":"ED-2","self":"https://your-domain.atlassian.net/rest/api/3/issue/ED-2"},"type":{"id":"10000","inward":"Parent","name":"","outward":"Sub-task"}}],"description":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"Main order flow broken"}]}]},"project":{"avatarUrls":{"16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000","48x48":"https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000"},"id":"10000","insight":{"lastIssueUpdateTime":"2021-04-22T05:37:05.000+0000","totalIssueCount":100},"key":"EX","name":"Example","projectCategory":{"description":"First Project Category","id":"10000","name":"FIRST","self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000"},"self":"https://your-domain.atlassian.net/rest/api/3/project/EX","simplified":false,"style":"classic"},"comment":[{"author":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"body":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper."}]}]},"created":"2021-01-17T12:34:00.000+0000","id":"10000","self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000","updateAuthor":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"updated":"2021-01-18T23:45:00.000+0000","visibility":{"identifier":"Administrators","type":"role","value":"Administrators"}}],"issuelinks":[{"id":"10001","outwardIssue":{"fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/images/icons/statuses/open.png","name":"Open"}},"id":"10004L","key":"PR-2","self":"https://your-domain.atlassian.net/rest/api/3/issue/PR-2"},"type":{"id":"10000","inward":"depends on","name":"Dependent","outward":"is depended by"}},{"id":"10002","inwardIssue":{"fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/images/icons/statuses/open.png","name":"Open"}},"id":"10004","key":"PR-3","self":"https://your-domain.atlassian.net/rest/api/3/issue/PR-3"},"type":{"id":"10000","inward":"depends on","name":"Dependent","outward":"is depended by"}}],"worklog":[{"author":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"comment":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"I did some work here."}]}]},"id":"100028","issueId":"10002","self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/worklog/10000","started":"2021-01-17T12:34:00.000+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"updateAuthor":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"updated":"2021-01-18T23:45:00.000+0000","visibility":{"identifier":"276f955c-63d7-42c8-9520-92d01dca0625","type":"group","value":"jira-developers"}}],"updated":1,"timetracking":{"originalEstimate":"10m","originalEstimateSeconds":600,"remainingEstimate":"3m","remainingEstimateSeconds":200,"timeSpent":"6m","timeSpentSeconds":400}},"id":"10002","key":"ED-1","self":"https://your-domain.atlassian.net/rest/api/3/issue/10002"}],"maxResults":50,"startAt":0,"total":1,"warningMessages":["The value ''bar'' does not exist for the field ''foo''."]}'
schema:
$ref: '#/components/schemas/SearchResults'
description: Returned if the request is successful.
'400':
description: Returned if the JQL query is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- {}
summary: Atlassian Search For Issues Using Jql Get
tags:
- Issue Search
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:issue-details:jira
- read:audit-log:jira
- read:avatar:jira
- read:field-configuration:jira
- read:issue-meta:jira
state: Beta
x-atlassian-connect-scope: READ
post:
deprecated: false
description: Searches for issues using [JQL](https://confluence.atlassian.com/x/egORLQ).
There is a [GET](#api-rest-api-3-search-get) version of this resource that can be used for smaller JQL query expressions.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** Issues are included in the response where the user has:
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project containing the issue.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: atlassianSearchforissuesusingjqlpost
parameters: []
requestBody:
content:
application/json:
example:
expand:
- names
- schema
- operations
fields:
- summary
- status
- assignee
fieldsByKeys: false
jql: project = HSP
maxResults: 15
startAt: 0
schema:
$ref: '#/components/schemas/SearchRequestBean'
description: A JSON object containing the search request.
required: true
responses:
'200':
content:
application/json:
example: '{"expand":"names,schema","issues":[{"expand":"","fields":{"watcher":{"isWatching":false,"self":"https://your-domain.atlassian.net/rest/api/3/issue/EX-1/watchers","watchCount":1,"watchers":[{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"}]},"attachment":[{"author":{"accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","active":false,"avatarUrls":{"16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32","48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"},"displayName":"Mia Krystof","key":"","name":"","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"content":"https://your-domain.atlassian.net/jira/rest/api/3/attachment/content/10000","created":"2022-10-06T07:32:47.000+0000","filename":"picture.jpg","id":10000,"mimeType":"image/jpeg","self":"https://your-domain.atlassian.net/rest/api/3/attachments/10000","size":23123,"thumbnail":"https://your-domain.atlassian.net/jira/rest/api/3/attachment/thumbnail/10000"}],"sub-tasks":[{"id":"10000","outwardIssue":{"fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/images/icons/statuses/open.png","name":"Open"}},"id":"10003","key":"ED-2","self":"https://your-domain.atlassian.net/rest/api/3/issue/ED-2"},"type":{"id":"10000","inward":"Parent","name":"","outward":"Sub-task"}}],"description":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"Main order flow broken"}]}]},"project":{"avatarUrls":{"16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000","48x48":"https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000"},"id":"10000","insight":{"lastIssueUpdateTime":"2021-04-22T05:37:05.000+0000","totalIssueCount":100},"key":"EX","name":"Example","projectCategory":{"description":"First Project Category","id":"10000","name":"FIRST","self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000"},"self":"https://your-domain.atlassian.net/rest/api/3/project/EX","simplified":false,"style":"classic"},"comment":[{"author":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"body":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper."}]}]},"created":"2021-01-17T12:34:00.000+0000","id":"10000","self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000","updateAuthor":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"updated":"2021-01-18T23:45:00.000+0000","visibility":{"identifier":"Administrators","type":"role","value":"Administrators"}}],"issuelinks":[{"id":"10001","outwardIssue":{"fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/images/icons/statuses/open.png","name":"Open"}},"id":"10004L","key":"PR-2","self":"https://your-domain.atlassian.net/rest/api/3/issue/PR-2"},"type":{"id":"10000","inward":"depends on","name":"Dependent","outward":"is depended by"}},{"id":"10002","inwardIssue":{"fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/images/icons/statuses/open.png","name":"Open"}},"id":"10004","key":"PR-3","self":"https://your-domain.atlassian.net/rest/api/3/issue/PR-3"},"type":{"id":"10000","inward":"depends on","name":"Dependent","outward":"is depended by"}}],"worklog":[{"author":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"comment":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"I did some work here."}]}]},"id":"100028","issueId":"10002","self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/worklog/10000","started":"2021-01-17T12:34:00.000+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"updateAuthor":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"},"updated":"2021-01-18T23:45:00.000+0000","visibility":{"identifier":"276f955c-63d7-42c8-9520-92d01dca0625","type":"group","value":"jira-developers"}}],"updated":1,"timetracking":{"originalEstimate":"10m","originalEstimateSeconds":600,"remainingEstimate":"3m","remainingEstimateSeconds":200,"timeSpent":"6m","timeSpentSeconds":400}},"id":"10002","key":"ED-1","self":"https://your-domain.atlassian.net/rest/api/3/issue/10002"}],"maxResults":50,"startAt":0,"total":1,"warningMessages":["The value ''bar'' does not exist for the field ''foo''."]}'
schema:
$ref: '#/components/schemas/SearchResults'
description: Returned if the request is successful.
'400':
description: Returned if the JQL query is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- {}
summary: Atlassian Search For Issues Using Jql Post
tags:
- Issue Search
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:issue-details:jira
- read:field.default-value:jira
- read:field.option:jira
- read:field:jira
- read:group:jira
state: Beta
x-atlassian-connect-scope: READ
components:
schemas:
JsonTypeBean:
additionalProperties: false
description: The schema of a field.
properties:
configuration:
additionalProperties:
readOnly: true
description: If the field is a custom field, the configuration of the field.
readOnly: true
type: object
custom:
description: If the field is a custom field, the URI of the field.
readOnly: true
type: string
customId:
description: If the field is a custom field, the custom ID of the field.
format: int64
readOnly: true
type: integer
items:
description: When the data type is an array, the name of the field items within the array.
readOnly: true
type: string
system:
description: If the field is a system field, the name of the field.
readOnly: true
type: string
type:
description: The data type of the field.
readOnly: true
type: string
required:
- type
type: object
IdSearchResults:
additionalProperties: false
description: Result of your JQL search. Returns a list of issue IDs and a token to fetch the next page if one exists.
properties:
issueIds:
description: The list of issue IDs found by the search.
items:
format: int64
readOnly: true
type: integer
readOnly: true
type: array
nextPageToken:
description: Continuation token to fetch the next page. If this result represents the last or the only page this token will be null.
readOnly: true
type: string
type: object
IssueBean:
additionalProperties: false
description: Details about an issue.
properties:
changelog:
allOf:
- $ref: '#/components/schemas/PageOfChangelogs'
description: Details of changelogs associated with the issue.
readOnly: true
editmeta:
allOf:
- $ref: '#/components/schemas/IssueUpdateMetadata'
description: The metadata for the fields on the issue that can be amended.
readOnly: true
expand:
description: Expand options that include additional issue details in the response.
readOnly: true
type: string
xml:
attribute: true
fields:
additionalProperties: {}
type: object
fieldsToInclude:
$ref: '#/components/schemas/IncludedFields'
id:
description: The ID of the issue.
readOnly: true
type: string
key:
description: The key of the issue.
readOnly: true
type: string
names:
additionalProperties:
readOnly: true
type: string
description: The ID and name of each field present on the issue.
readOnly: true
type: object
operations:
allOf:
- $ref: '#/components/schemas/Operations'
description: The operations that can be performed on the issue.
readOnly: true
properties:
additionalProperties:
readOnly: true
description: Details of the issue properties identified in the request.
readOnly: true
type: object
renderedFields:
additionalProperties:
readOnly: true
description: The rendered value of each field present on the issue.
readOnly: true
type: object
schema:
additionalProperties:
$ref: '#/components/schemas/JsonTypeBean'
description: The schema describing each field present on the issue.
readOnly: true
type: object
self:
description: The URL of the issue details.
format: uri
readOnly: true
type: string
transitions:
description: The transitions that can be performed on the issue.
items:
$ref: '#/components/schemas/IssueTransition'
readOnly: true
type: array
versionedRepresentations:
additionalProperties:
additionalProperties:
readOnly: true
readOnly: true
type: object
description: The versions of each field on the issue.
readOnly: true
type: object
type: object
xml:
name: issue
ChangeDetails:
additionalProperties: false
description: A change item.
properties:
field:
description: The name of the field changed.
readOnly: true
type: string
fieldId:
description: The ID of the field changed.
readOnly: true
type: string
fieldtype:
description: The type of the field changed.
readOnly: true
type: string
from:
description: The details of the original value.
readOnly: true
type: string
fromString:
description: The details of the original value as a string.
readOnly: true
type: string
to:
description: The details of the new value.
readOnly: true
type: string
toString:
description: The details of the new value as a string.
readOnly: true
type: string
type: object
SimpleLink:
additionalProperties: false
description: Details about the operations available in this version.
properties:
href:
type: string
iconClass:
type: string
id:
type: string
label:
type: string
styleClass:
type: string
title:
type: string
weight:
format: int32
type: integer
type: object
xml:
name: link
HistoryMetadataParticipant:
additionalProperties: true
description: Details of user or system associated with a issue history metadata item.
properties:
avatarUrl:
description: The URL to an avatar for the user or system associated with a history record.
type: string
displayName:
description: The display name of the user or system associated with a history record.
type: string
displayNameKey:
description: The key of the display name of the user or system associated with a history record.
type: string
id:
description: The ID of the user or system associated with a history record.
type: string
type:
description: The type of the user or system associated with a history record.
type: string
url:
description: The URL of the user or system associated with a history record.
type: string
type: object
ProjectDetails:
additionalProperties: false
description: Details about a project.
properties:
avatarUrls:
allOf:
- $ref: '#/components/schemas/AvatarUrlsBean'
description: The URLs of the project's avatars.
readOnly: true
id:
description: The ID of the project.
type: string
key:
description: The key of the project.
readOnly: true
type: string
name:
description: The name of the project.
readOnly: true
type: string
projectCategory:
allOf:
- $ref: '#/components/schemas/UpdatedProjectCategory'
description: The category the project belongs to.
readOnly: true
projectTypeKey:
description: The [project type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes) of the project.
enum:
- software
- service_desk
- business
readOnly: true
type: string
self:
description: The URL of the project details.
readOnly: true
type: string
simplified:
description: Whether or not the project is simplified.
readOnly: true
type: boolean
type: object
PageOfChangelogs:
additionalProperties: false
description: A page of changelogs.
properties:
histories:
description: The list of changelogs.
items:
$ref: '#/components/schemas/Changelog'
readOnly: true
type: array
maxResults:
description: The maximum number of results that could be on the page.
format: int32
readOnly: true
type: integer
startAt:
description: The index of the first item returned on the page.
format: int32
readOnly: true
type: integer
total:
description: The number of results on the page.
format: int32
readOnly: true
type: integer
type: object
IssueMatchesForJQL:
additionalProperties: false
description: A list of the issues matched to a JQL query or details of errors encountered during matching.
properties:
errors:
description: A list of errors.
items:
description: A list of errors.
type: string
type: array
uniqueItems: true
matchedIssues:
description: A list of issue IDs.
items:
description: A list of issue IDs.
format: int64
type: integer
type: array
uniqueItems: true
required:
- errors
- matchedIssues
type: object
SuggestedIssue:
additionalProperties: false
description: An issue suggested for use in the issue picker auto-completion.
properties:
id:
description: The ID of the issue.
format: int64
readOnly: true
type: integer
img:
description: The URL of the issue type's avatar.
readOnly: true
type: string
key:
description: The key of the issue.
readOnly: true
type: string
keyHtml:
description: The key of the issue in HTML format.
readOnly: true
type: string
summary:
description: The phrase containing the query string in HTML format, with the string highlighted with HTML bold tags.
readOnly: true
type: string
summaryText:
description: The phrase containing the query string, as plain text.
readOnly: true
type: string
type: object
IncludedFields:
additionalProperties: false
properties:
actuallyIncluded:
items:
type: string
type: array
uniqueItems: true
excluded:
items:
type: string
type: array
uniqueItems: true
included:
items:
type: string
type: array
uniqueItems: true
type: object
Scope:
additionalProperties: true
description: The projects the item is associated with. Indicated for items associated with [next-gen projects](https://confluence.atlassian.com/x/loMyO).
properties:
project:
allOf:
- $ref: '#/components/schemas/ProjectDetails'
description: The project the item has scope in.
readOnly: true
type:
description: The type of scope.
enum:
- PROJECT
- TEMPLATE
readOnly: true
type: string
type: object
StatusDetails:
additionalProperties: true
description: A status.
properties:
description:
description: The description of the status.
readOnly: true
type: string
iconUrl:
description: The URL of the icon used to represent the status.
readOnly: true
type: string
id:
description: The ID of the status.
readOnly: true
type: string
name:
description: The name of the status.
readOnly: true
type: string
scope:
allOf:
- $ref: '#/components/schemas/Scope'
description: The scope of the field.
readOnly: true
self:
description: The URL of the status.
readOnly: true
type: string
statusCategory:
allOf:
- $ref: '#/components/schemas/StatusCategory'
description: The category assigned to the status.
readOnly: true
type: object
Operations:
additionalProperties: true
description: Details of the operations that can be performed on the issue.
properties:
linkGroups:
description: Details of the link groups defining issue operations.
items:
$ref: '#/components/schemas/LinkGroup'
readOnly: true
type: array
type: object
UpdatedProjectCategory:
additionalProperties: false
description: A project category.
properties:
description:
description: The name of the project category.
readOnly: true
type: string
id:
description: The ID of the project category.
readOnly: true
type: string
name:
description: The description of the project category.
readOnly: true
type: string
self:
description: The URL of the project category.
readOnly: true
type: string
type: object
IssueTransition:
additionalProperties: true
description: Details of an issue transition.
properties:
expand:
description: Expand options that include additional transition details in the response.
readOnly: true
type: string
fields:
additionalProperties:
$ref: '#/components/schemas/FieldMetadata'
description: Details of the fields associated with the issue transition screen. Use this information to populate `fields` and `update` in a transition request.
readOnly: true
type: object
hasScreen:
description: Whether there is a screen associated with the issue transition.
readOnly: true
type: boolean
id:
description: The ID of the issue transition. Required when specifying a transition to undertake.
type: string
isAvailable:
description: Whether the transition is available to be performed.
readOnly: true
type: boolean
isConditional:
description: Whether the issue has to meet criteria before the issue transition is applied.
readOnly: true
type: boolean
isGlobal:
description: Whether the issue transition is global, that is, the transition is applied to issues regardless of their status.
readOnly: true
type: boolean
isInitial:
description: Whether this is the initial issue transition for the workflow.
readOnly: true
type: boolean
looped:
type: boolean
name:
description: The name of the issue transition.
readOnly: true
type: string
to:
allOf:
- $ref: '#/components/schemas/StatusDetails'
description: Details of the issue status after the transition.
readOnly: true
type: object
LinkGroup:
additionalProperties: false
description: Details a link group, which defines issue operations.
properties:
groups:
items:
$ref: '#/components/schemas/LinkGroup'
type: array
header:
$ref: '#/components/schemas/SimpleLink'
id:
type: string
links:
items:
$ref: '#/components/schemas/SimpleLink'
type: array
styleClass:
type: string
weight:
format: int32
type: integer
type: object
SearchResults:
additionalProperties: false
description: The result of a JQL search.
properties:
expand:
description: Expand options that include additional search result details in the response.
readOnly: true
type: string
issues:
description: The list of issues found by the search.
items:
$ref: '#/components/schemas/IssueBean'
readOnly: true
type: array
maxResults:
description: The maximum number of results that could be on the page.
format: int32
readOnly: true
type: integer
names:
additionalProperties:
readOnly: true
type: string
description: The ID and name of each field in the search results.
readOnly: true
type: object
schema:
additionalProperties:
$ref: '#/components/schemas/JsonTypeBean'
description: The schema describing the field types in the search results.
readOnly: true
type: object
startAt:
description: The index of the first item returned on the page.
format: int32
readOnly: true
type: integer
total:
description: The number of results on the page.
format: int32
readOnly: true
type: integer
warningMessages:
description: Any warnings related to the JQL query.
items:
readOnly: true
type: string
readOnly: true
type: array
type: object
IssueUpdateMetadata:
description: A list of editable field details.
properties:
fields:
additionalProperties:
$ref: '#/components/schemas/FieldMetadata'
readOnly: true
type: object
type: object
IssuePickerSuggestionsIssueType:
additionalProperties: false
description: A type of issue suggested for use in auto-completion.
properties:
id:
description: The ID of the type of issues suggested for use in auto-completion.
readOnly: true
type: string
issues:
description: A list of issues suggested for use in auto-completion.
items:
$ref: '#/components/schemas/SuggestedIssue'
readOnly: true
type: array
label:
description: The label of the type of issues suggested for use in auto-completion.
readOnly: true
type: string
msg:
description: If no issue suggestions are found, returns a message indicating no suggestions were found,
readOnly: true
type: string
sub:
description: If issue suggestions are found, returns a message indicating the number of issues suggestions found and returned.
readOnly: true
type: string
type: object
SearchRequestBean:
additionalProperties: false
properties:
expand:
description: "Use [expand](em>#expansion) to include additional information about issues in the response. Note that, unlike the majority of instances where `expand` is specified, `expand` is defined as a list of values. The expand options are:\n\n * `renderedFields` Returns field values rendered in HTML format.\n * `names` Returns the display name of each field.\n * `schema` Returns the schema describing a field type.\n * `transitions` Returns all possible transitions for the issue.\n * `operations` Returns all possible operations for the issue.\n * `editmeta` Returns information about how each field can be edited.\n * `changelog` Returns a list of recent updates to an issue, sorted by date, starting from the most recent.\n * `versionedRepresentations` Instead of `fields`, returns `versionedRepresentations` a JSON array containing each version of a field's value, with the highest numbered item representing the most recent version."
items:
type: string
type: array
fields:
description: "A list of fields to return for each issue, use it to retrieve a subset of fields. This parameter accepts a comma-separated list. Expand options include:\n\n * `*all` Returns all fields.\n * `*navigable` Returns navigable fields.\n * Any issue field, prefixed with a minus to exclude.\n\nThe default is `*navigable`.\n\nExamples:\n\n * `summary,comment` Returns the summary and comments fields only.\n * `-description` Returns all navigable (default) fields except description.\n * `*all,-comment` Returns all fields except comments.\n\nMultiple `fields` parameters can be included in a request.\n\nNote: All navigable fields are returned by default. This differs from [GET issue](#api-rest-api-3-issue-issueIdOrKey-get) where the default is all fields."
items:
type: string
type: array
fieldsByKeys:
description: Reference fields by their key (rather than ID). The default is `false`.
type: boolean
jql:
description: A [JQL](https://confluence.atlassian.com/x/egORLQ) expression.
type: string
maxResults:
default: 50
description: The maximum number of items to return per page.
format: int32
type: integer
properties:
description: A list of up to 5 issue properties to include in the results. This parameter accepts a comma-separated list.
items:
type: string
type: array
startAt:
description: The index of the first item to return in the page of results (page offset). The base index is `0`.
format: int32
type: integer
validateQuery:
description: "Determines how to validate the JQL query and treat the validation results. Supported values:\n\n * `strict` Returns a 400 response code if any errors are found, along with a list of all errors (and warnings).\n * `warn` Returns all errors as warnings.\n * `none` No validation is performed.\n * `true` *Deprecated* A legacy synonym for `strict`.\n * `false` *Deprecated* A legacy synonym for `warn`.\n\nThe default is `strict`.\n\nNote: If the JQL is not correctly formed a 400 response code is returned, regardless of the `validateQuery` value."
enum:
- strict
- warn
- none
- 'true'
- 'false'
type: string
type: object
FieldMetadata:
additionalProperties: false
description: The metadata describing an issue field.
properties:
allowedValues:
description: The list of values allowed in the field.
items:
readOnly: true
readOnly: true
type: array
autoCompleteUrl:
description: The URL that can be used to automatically complete the field.
readOnly: true
type: string
configuration:
additionalProperties:
readOnly: true
description: The configuration properties.
readOnly: true
type: object
defaultValue:
description: The default value of the field.
readOnly: true
hasDefaultValue:
description: Whether the field has a default value.
readOnly: true
type: boolean
key:
description: The key of the field.
readOnly: true
type: string
name:
description: The name of the field.
readOnly: true
type: string
operations:
description: The list of operations that can be performed on the field.
items:
readOnly: true
type: string
readOnly: true
type: array
required:
description: Whether the field is required.
readOnly: true
type: boolean
schema:
allOf:
- $ref: '#/components/schemas/JsonTypeBean'
description: The data type of the field.
readOnly: true
required:
- key
- name
- operations
- required
- schema
type: object
xml:
name: availableField
IssuesAndJQLQueries:
additionalProperties: false
description: List of issues and JQL queries.
properties:
issueIds:
description: A list of issue IDs.
items:
description: A list of issue IDs.
format: int64
type: integer
type: array
uniqueItems: true
jqls:
description: A list of JQL queries.
items:
description: A list of JQL queries.
type: string
type: array
required:
- issueIds
- jqls
type: object
IdSearchRequestBean:
additionalProperties: false
properties:
jql:
description: A [JQL](https://confluence.atlassian.com/x/egORLQ) expression. Order by clauses are not allowed.
type: string
maxResults:
default: 1000
description: The maximum number of items to return per page.
format: int32
type: integer
nextPageToken:
description: The continuation token to fetch the next page. This token is provided by the response of this endpoint.
type: string
type: object
IssuePickerSuggestions:
additionalProperties: false
description: A list of issues suggested for use in auto-completion.
properties:
sections:
description: A list of issues for an issue type suggested for use in auto-completion.
items:
$ref: '#/components/schemas/IssuePickerSuggestionsIssueType'
readOnly: true
type: array
type: object
IssueMatches:
additionalProperties: false
description: A list of matched issues or errors for each JQL query, in the order the JQL queries were passed.
properties:
matches:
items:
$ref: '#/components/schemas/IssueMatchesForJQL'
type: array
required:
- matches
type: object
HistoryMetadata:
additionalProperties: true
description: Details of issue history metadata.
properties:
activityDescription:
description: The activity described in the history record.
type: string
activityDescriptionKey:
description: The key of the activity described in the history record.
type: string
actor:
allOf:
- $ref: '#/components/schemas/HistoryMetadataParticipant'
description: Details of the user whose action created the history record.
cause:
allOf:
- $ref: '#/components/schemas/HistoryMetadataParticipant'
description: Details of the cause that triggered the creation the history record.
description:
description: The description of the history record.
type: string
descriptionKey:
description: The description key of the history record.
type: string
emailDescription:
description: The description of the email address associated the history record.
type: string
emailDescriptionKey:
description: The description key of the email address associated the history record.
type: string
extraData:
additionalProperties:
type: string
description: Additional arbitrary information about the history record.
type: object
generator:
allOf:
- $ref: '#/components/schemas/HistoryMetadataParticipant'
description: Details of the system that generated the history record.
type:
description: The type of the history record.
type: string
type: object
Changelog:
additionalProperties: false
description: A log of changes made to issue fields. Changelogs related to workflow associations are currently being deprecated.
properties:
author:
allOf:
- $ref: '#/components/schemas/UserDetails'
description: The user who made the change.
readOnly: true
created:
description: The date on which the change took place.
format: date-time
readOnly: true
type: string
historyMetadata:
allOf:
- $ref: '#/components/schemas/HistoryMetadata'
description: The history metadata associated with the changed.
readOnly: true
id:
description: The ID of the changelog.
readOnly: true
type: string
items:
description: The list of items changed.
items:
$ref: '#/components/schemas/ChangeDetails'
readOnly: true
type: array
type: object
StatusCategory:
additionalProperties: true
description: A status category.
properties:
colorName:
description: The name of the color used to represent the status category.
readOnly: true
type: string
id:
description: The ID of the status category.
format: int64
readOnly: true
type: integer
key:
description: The key of the status category.
readOnly: true
type: string
name:
description: The name of the status category.
readOnly: true
type: string
self:
description: The URL of the status category.
readOnly: true
type: string
type: object
AvatarUrlsBean:
additionalProperties: false
properties:
16x16:
description: The URL of the item's 16x16 pixel avatar.
format: uri
type: string
24x24:
description: The URL of the item's 24x24 pixel avatar.
format: uri
type: string
32x32:
description: The URL of the item's 32x32 pixel avatar.
format: uri
type: string
48x48:
description: The URL of the item's 48x48 pixel avatar.
format: uri
type: string
type: object
UserDetails:
additionalProperties: false
description: "User details permitted by the user's Atlassian Account privacy settings. However, be aware of these exceptions:\n\n * User record deleted from Atlassian: This occurs as the result of a right to be forgotten request. In this case, `displayName` provides an indication and other parameters have default values or are blank (for example, email is blank).\n * User record corrupted: This occurs as a results of events such as a server import and can only happen to deleted users. In this case, `accountId` returns *unknown* and all other parameters have fallback values.\n * User record unavailable: This usually occurs due to an internal service outage. In this case, all parameters have fallback values."
properties:
accountId:
description: The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*.
maxLength: 128
type: string
accountType:
description: The type of account represented by this user. This will be one of 'atlassian' (normal users), 'app' (application user) or 'customer' (Jira Service Desk customer user)
readOnly: true
type: string
active:
description: Whether the user is active.
readOnly: true
type: boolean
avatarUrls:
allOf:
- $ref: '#/components/schemas/AvatarUrlsBean'
description: The avatars of the user.
readOnly: true
displayName:
description: The display name of the user. Depending on the user’s privacy settings, this may return an alternative value.
readOnly: true
type: string
emailAddress:
description: The email address of the user. Depending on the user’s privacy settings, this may be returned as null.
readOnly: true
type: string
key:
description: This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details.
readOnly: true
type: string
name:
description: This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details.
readOnly: true
type: string
self:
description: The URL of the user.
readOnly: true
type: string
timeZone:
description: The time zone specified in the user's profile. Depending on the user’s privacy settings, this may be returned as null.
readOnly: true
type: string
type: object
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: Use an Atlassian API key as a Bearer token. Create API keys at https://admin.atlassian.com.
oauth2:
type: oauth2
description: OAuth 2.0 authorization for Atlassian Cloud APIs.
flows:
authorizationCode:
authorizationUrl: https://auth.atlassian.com/authorize
tokenUrl: https://auth.atlassian.com/oauth/token
scopes:
read:org:admin: Read organization information.
write:org:admin: Modify organization settings.
read:user:admin: Read user information.
write:user:admin: Modify user accounts.
read:policy:admin: Read organization policies.
write:policy:admin: Modify organization policies.
read:event:admin: Read organization events.
externalDocs:
description: Atlassian Admin REST API Documentation
url: https://developer.atlassian.com/cloud/admin/organization/rest/intro/