Atlassian: Create filter

← Filters operations · Get started

Operation atlassian.createfilter

Provider route: POST /{cloudId}/rest/api/3/filter. 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["filters"]["createFilter"]>[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.filters.createFilter(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.filters.create_filter(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}$
query	object	Optional	Additional keys: not allowed
query.expand	string	Optional
query.overrideSharePermissions	boolean	Optional	Default: false
body	Model	Required within parent	Expand Create filter — request body — body

Referenced models: Create filter — 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 Get filter — response body

Referenced models: Get filter — response body

Schemas

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

Create filter — request body — body

Field	Type	Presence	Description and constraints
$	object	Root	Details about a filter. Additional keys: not allowed
approximateLastUsed	string	Optional	\[Experimental\] Approximate last used time. Returns the date and time when the filter was last used. Returns `null` if the filter hasn't been used after tracking was enabled. For performance reasons, timestamps aren't updated in real time and therefore may not be exactly accurate. Format: date-time Read only: true
description	string	Optional	A description of the filter.
editPermissions	array	Optional	The groups and projects that can edit the filter.
editPermissions[]	Model	Each item	Expand Create filter — request body — body edit Permissions item
favourite	boolean	Optional	Whether the filter is selected as a favorite.
favouritedCount	integer	Optional	The count of how many users have selected this filter as a favorite, including the filter owner. Format: int64 Read only: true
id	string	Optional	The unique identifier for the filter. Read only: true
jql	string	Optional	The JQL query for the filter. For example, *project = SSP AND issuetype = Bug*.
name	string	Required within parent	The name of the filter. Must be unique.
owner	Model	Optional	Expand Assign issue — request body — body The user who owns the filter. This is defaulted to the creator of the filter, however Jira administrators can change the owner of a shared filter in the admin settings. Read only: true
searchUrl	string	Optional	A URL to view the filter results in Jira, using the [Search for issues using JQL](#api-rest-api-3-filter-search-get) operation with the filter's JQL string to return the filter results. For example, *https://your-domain.atlassian.net/rest/api/3/search?jql=project+%3D+SSP+AND+issuetype+%3D+Bug*. Format: uri Read only: true
self	string	Optional	The URL of the filter. Format: uri Read only: true
sharePermissions	array	Optional	The groups and projects that the filter is shared with.
sharePermissions[]	Model	Each item	Expand Create filter — request body — body edit Permissions item
sharedUsers	Model	Optional	Expand Create filter — request body — body shared Users A paginated list of the users that the filter is shared with. This includes users that are members of the groups or can browse the projects that the filter is shared with. Read only: true
subscriptions	Model	Optional	Expand Create filter — request body — body subscriptions A paginated list of the users that are subscribed to the filter. Read only: true
viewUrl	string	Optional	A URL to view the filter results in Jira, using the ID of the filter. For example, *https://your-domain.atlassian.net/issues/?filter=10100*. Format: uri Read only: true

Referenced models: Create filter — request body — body subscriptions, Create filter — request body — body edit Permissions item, Assign issue — request body — body, Create filter — request body — body shared Users

Get filter — response body

Field	Type	Presence	Description and constraints
$	object	Root	Details about a filter.
approximateLastUsed	JSON	Optional
approximateLastUsed (anyOf 1)	JSON	Alternative
approximateLastUsed (anyOf 1) (anyOf 1)	string	Alternative	\[Experimental\] Approximate last used time. Returns the date and time when the filter was last used. Returns `null` if the filter hasn't been used after tracking was enabled. For performance reasons, timestamps aren't updated in real time and therefore may not be exactly accurate. Read only: true
approximateLastUsed (anyOf 1) (anyOf 2)	integer	Alternative
approximateLastUsed (anyOf 2)	null	Alternative
description	JSON	Optional
description (anyOf 1)	string	Alternative	A description of the filter.
description (anyOf 2)	null	Alternative
editPermissions	JSON	Optional
editPermissions (anyOf 1)	array	Alternative	The groups and projects that can edit the filter.
editPermissions (anyOf 1)[]	Model	Each item	Expand Get share permission — response body
editPermissions (anyOf 2)	null	Alternative
favourite	JSON	Optional
favourite (anyOf 1)	boolean	Alternative	Whether the filter is selected as a favorite.
favourite (anyOf 2)	null	Alternative
favouritedCount	JSON	Optional
favouritedCount (anyOf 1)	JSON	Alternative
favouritedCount (anyOf 1) (anyOf 1)	integer	Alternative	The count of how many users have selected this filter as a favorite, including the filter owner. Format: int64 Read only: true
favouritedCount (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
favouritedCount (anyOf 2)	null	Alternative
id	JSON	Optional
id (anyOf 1)	string	Alternative	The unique identifier for the filter. Read only: true
id (anyOf 2)	null	Alternative
jql	JSON	Optional
jql (anyOf 1)	string	Alternative	The JQL query for the filter. For example, *project = SSP AND issuetype = Bug*.
jql (anyOf 2)	null	Alternative
name	JSON	Optional
name (anyOf 1)	string	Alternative	The name of the filter. Must be unique.
name (anyOf 2)	null	Alternative
owner	JSON	Optional
owner (anyOf 1)	Model	Alternative	Expand Get user — response body The user who owns the filter. This is defaulted to the creator of the filter, however Jira administrators can change the owner of a shared filter in the admin settings. Read only: true
owner (anyOf 2)	null	Alternative
searchUrl	JSON	Optional
searchUrl (anyOf 1)	string	Alternative	A URL to view the filter results in Jira, using the [Search for issues using JQL](#api-rest-api-3-filter-search-get) operation with the filter's JQL string to return the filter results. For example, *https://your-domain.atlassian.net/rest/api/3/search?jql=project+%3D+SSP+AND+issuetype+%3D+Bug*. Format: uri Read only: true
searchUrl (anyOf 2)	null	Alternative
self	JSON	Optional
self (anyOf 1)	string	Alternative	The URL of the filter. Format: uri Read only: true
self (anyOf 2)	null	Alternative
sharePermissions	JSON	Optional
sharePermissions (anyOf 1)	array	Alternative	The groups and projects that the filter is shared with.
sharePermissions (anyOf 1)[]	Model	Each item	Expand Get share permission — response body
sharePermissions (anyOf 2)	null	Alternative
sharedUsers	JSON	Optional
sharedUsers (anyOf 1)	Model	Alternative	Expand Get filter — response body — shared Users end-index, items, max-results, size, start-index A paginated list of the users that the filter is shared with. This includes users that are members of the groups or can browse the projects that the filter is shared with. Read only: true
sharedUsers (anyOf 2)	null	Alternative
subscriptions	JSON	Optional
subscriptions (anyOf 1)	Model	Alternative	Expand Get filter — response body — subscriptions A paginated list of subscriptions to a filter A paginated list of the users that are subscribed to the filter. Read only: true
subscriptions (anyOf 2)	null	Alternative
viewUrl	JSON	Optional
viewUrl (anyOf 1)	string	Alternative	A URL to view the filter results in Jira, using the ID of the filter. For example, *https://your-domain.atlassian.net/issues/?filter=10100*. Format: uri Read only: true
viewUrl (anyOf 2)	null	Alternative

Referenced models: Get filter — response body — subscriptions A paginated list of subscriptions to a filter, Get share permission — response body, Get user — response body, Get filter — response body — shared Users end-index, items, max-results, size, start-index

Create filter — request body — body subscriptions

Field	Type	Presence	Description and constraints
$	object	Root	A paginated list of subscriptions to a filter. Additional keys: not allowed
end-index	integer	Optional	The index of the last item returned on the page. Format: int32 Read only: true
items	array	Optional	The list of items. Read only: true
items[]	Model	Each item	Expand Create filter — request body — body subscriptions items item
max-results	integer	Optional	The maximum number of results that could be on the page. Format: int32 Read only: true
size	integer	Optional	The number of items on the page. Format: int32 Read only: true
start-index	integer	Optional	The index of the first item returned on the page. Format: int32 Read only: true

Referenced models: Create filter — request body — body subscriptions items item

Policy, approvals and errors

SDK function policy ID: atlassian.createfilter. Catalog operation: createfilter. 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: ["write:jira-work"]

Official provider source