Atlassian: Search for issues using JQL enhanced search (POST)

← Issue search operations · Get started

Operation atlassian.searchandreconsileissuesusingjqlpost

Provider route: POST /{cloudId}/rest/api/3/search/jql. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/atlassian with npm, or alter-sdk-atlassian with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { AtlassianIntegration } from "@alter-ai/atlassian";

async function execute(input: Parameters<AtlassianIntegration["issueSearch"]["searchAndReconsileIssuesUsingJqlPost"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new AtlassianIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.issueSearch.searchAndReconsileIssuesUsingJqlPost(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_atlassian import AtlassianIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = AtlassianIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.issue_search.search_and_reconsile_issues_using_jql_post(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.cloudId	string	Required within parent	Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
body	Model	Required within parent	Expand Search for issues using JQL enhanced search (POST) — request body — body

Referenced models: Search for issues using JQL enhanced search (POST) — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Search for issues using JQL enhanced search (GET) — response body

Referenced models: Search for issues using JQL enhanced search (GET) — response body

Schemas

20 more schemas are linked from the tables above, on the schema pages.

Search for issues using JQL enhanced search (GET) — response body

Field	Type	Presence	Description and constraints
$	object	Root	The result of a JQL search with issues reconsilation.
isLast	JSON	Optional
isLast (anyOf 1)	boolean	Alternative	Indicates whether this is the last page of the paginated response. Read only: true
isLast (anyOf 2)	null	Alternative
issues	JSON	Optional
issues (anyOf 1)	array	Alternative	The list of issues found by the search or reconsiliation. Read only: true
issues (anyOf 1)[]	Model	Each item	Expand Get issue — response body
issues (anyOf 2)	null	Alternative
names	JSON	Optional
names (anyOf 1)	object	Alternative	The ID and name of each field in the search results. Read only: true Additional keys: see wildcard field
names (anyOf 1).*	string	Additional keys	Read only: true
names (anyOf 2)	null	Alternative
nextPageToken	JSON	Optional
nextPageToken (anyOf 1)	string	Alternative	Continuation token to fetch the next page. If this result represents the last or the only page this token will be null. This token will expire in 7 days. Read only: true
nextPageToken (anyOf 2)	null	Alternative
schema	JSON	Optional
schema (anyOf 1)	object	Alternative	The schema describing the field types in the search results. Read only: true Additional keys: see wildcard field
schema (anyOf 1).*	Model	Additional keys	Expand Create custom field — response body — schema The schema of a field
schema (anyOf 2)	null	Alternative
warnings	JSON	Optional
warnings (anyOf 1)	array	Alternative	Experimental. Warnings generated during the search, e.g. when a JQL clause exceeded its argument limit or when the result set was truncated due to an ingestion limit. This field is currently rolling out behind a feature flag and may be absent, empty, or change shape without notice until generally available. Read only: true
warnings (anyOf 1)[]	Model	Each item	Expand Search for issues using JQL enhanced search (GET) — response body — warnings array item
warnings (anyOf 2)	null	Alternative

Referenced models: Get issue — response body, Create custom field — response body — schema The schema of a field, Search for issues using JQL enhanced search (GET) — response body — warnings array item

Search for issues using JQL enhanced search (POST) — request body — body

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
expand	string	Optional	Use [expand](#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 comma-delimited string of values. The expand options are: * `renderedFields` Returns field values rendered in HTML format. * `names` Returns the display name of each field. * `schema` Returns the schema describing a field type. * `transitions` Returns all possible transitions for the issue. * `operations` Returns all possible operations for the issue. * `editmeta` Returns information about how each field can be edited. * `changelog` Returns a list of recent updates to an issue, sorted by date, starting from the most recent. * `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. Examples: `"names,changelog"` Returns the display name of each field as well as a list of recent updates to an issue.
fields	array	Optional	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: * `*all` Returns all fields. * `*navigable` Returns navigable fields. * `id` Returns only issue IDs. * Any issue field, prefixed with a dash to exclude. The default is `id`. Examples: * `summary,comment` Returns the summary and comments fields only. * `*all,-comment` Returns all fields except comments. Multiple `fields` parameters can be included in a request. Note: By default, this resource returns IDs only. This differs from [GET issue](#api-rest-api-3-issue-issueIdOrKey-get) where the default is all fields.
fields[]	string	Each item
fieldsByKeys	boolean	Optional	Reference fields by their key (rather than ID). The default is `false`.
includeArchivedProjects	boolean	Optional	Whether to also return issues that belong to archived projects. Archived projects are excluded by default. Requires *Browse projects* permission on the archived project. The default is `false`.
jql	string	Optional	A [JQL](https://confluence.atlassian.com/x/egORLQ) expression. For performance reasons, this parameter requires a bounded query. A bounded query is a query with a search restriction. * Example of an unbounded query: `order by key desc`. * Example of a bounded query: `assignee = currentUser() order by key`. Additionally, `orderBy` clause can contain a maximum of 7 fields.
maxResults	integer	Optional	The maximum number of items to return per page. To manage page size, API 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. It returns max 5000 issues. Default: 50 Format: int32
nextPageToken	string	Optional	The token for a page to fetch that is not the first page. The first page has a `nextPageToken` of `null`. Use the `nextPageToken` to fetch the next page of issues.
properties	array	Optional	A list of up to 5 issue properties to include in the results. This parameter accepts a comma-separated list.
properties[]	string	Each item
reconcileIssues	array	Optional	Strong consistency issue ids to be reconciled with search results. Accepts max 50 ids. This list of ids should be consistent with each paginated request across different pages.
reconcileIssues[]	integer	Each item	Format: int64

Create custom field — response body — schema The schema of a field

Field	Type	Presence	Description and constraints
$	object	Root	The schema of a field.
configuration	JSON	Optional
configuration (anyOf 1)	object	Alternative	If the field is a custom field, the configuration of the field. Read only: true Additional keys: see wildcard field
configuration (anyOf 1).*	JSON	Additional keys	Read only: true
configuration (anyOf 2)	null	Alternative
custom	JSON	Optional
custom (anyOf 1)	string	Alternative	If the field is a custom field, the URI of the field. Read only: true
custom (anyOf 2)	null	Alternative
customId	JSON	Optional
customId (anyOf 1)	JSON	Alternative
customId (anyOf 1) (anyOf 1)	integer	Alternative	If the field is a custom field, the custom ID of the field. Format: int64 Read only: true
customId (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
customId (anyOf 2)	null	Alternative
items	JSON	Optional
items (anyOf 1)	string	Alternative	When the data type is an array, the name of the field items within the array. Read only: true
items (anyOf 2)	null	Alternative
system	JSON	Optional
system (anyOf 1)	string	Alternative	If the field is a system field, the name of the field. Read only: true
system (anyOf 2)	null	Alternative
type	JSON	Optional
type (anyOf 1)	string	Alternative	The data type of the field. Read only: true
type (anyOf 2)	null	Alternative

Search for issues using JQL enhanced search (GET) — response body — warnings array item

Field	Type	Presence	Description and constraints
$	object	Root	Experimental. A warning returned alongside successful search results.
details	JSON	Optional
details (anyOf 1)	Model	Alternative	Expand Search for issues using JQL enhanced search (GET) — response body — warnings array item details actual, arguments, clause, limit Structured details about the warning, if available.
details (anyOf 2)	null	Alternative
message	JSON	Optional
message (anyOf 1)	string	Alternative	A human-readable explanation of the warning suitable for surfacing to end users. Read only: true
message (anyOf 2)	null	Alternative
type	JSON	Optional
type (anyOf 1)	string	Alternative	The type of warning, e.g. CLAUSE\_LIMIT\_EXCEEDED. Read only: true
type (anyOf 2)	null	Alternative

Referenced models: Search for issues using JQL enhanced search (GET) — response body — warnings array item details actual, arguments, clause, limit

Get issue — response body — fields To Include actually Included, excluded, included

Field	Type	Presence	Description and constraints
$	object	Root
actuallyIncluded	JSON	Optional
actuallyIncluded (anyOf 1)	array	Alternative	Unique items: true
actuallyIncluded (anyOf 1)[]	string	Each item
actuallyIncluded (anyOf 2)	null	Alternative
excluded	JSON	Optional
excluded (anyOf 1)	array	Alternative	Unique items: true
excluded (anyOf 1)[]	string	Each item
excluded (anyOf 2)	null	Alternative
included	JSON	Optional
included (anyOf 1)	array	Alternative	Unique items: true
included (anyOf 1)[]	string	Each item
included (anyOf 2)	null	Alternative

Policy, approvals and errors

SDK function policy ID: atlassian.searchandreconsileissuesusingjqlpost. Catalog operation: searchandreconsileissuesusingjqlpost. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["read:jira-work"]

Official provider source