Atlassian: Create plan

← Plans operations · Get started

Operation atlassian.createplan

Provider route: POST /{cloudId}/rest/api/3/plans/plan. 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["plans"]["createPlan"]>[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.plans.createPlan(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.plans.create_plan(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.useGroupId	boolean	Optional	Default: false
body	Model	Required within parent	Expand Create plan — request body — body

Referenced models: Create plan — 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
$	JSON	Root
$ (anyOf 1)	integer	Alternative	Format: int64
$ (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Schemas

Create plan — request body — body

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
crossProjectReleases	array	Optional	The cross-project releases to include in the plan. Unique items: true
crossProjectReleases[]	Model	Each item	Expand Create plan — request body — body cross Project Releases item
customFields	array	Optional	The custom fields for the plan. Unique items: true
customFields[]	Model	Each item	Expand Create plan — request body — body custom Fields item
exclusionRules	Model	Optional	Expand Create plan — request body — body exclusion Rules The exclusion rules for the plan.
issueSources	array	Required within parent	The issue sources to include in the plan. Unique items: true
issueSources[]	Model	Each item	Expand Create plan — request body — body issue Sources item
leadAccountId	string	Optional	The account ID of the plan lead.
name	string	Required within parent	The plan name. Maximum length: 255 Minimum length: 1
permissions	array	Optional	The permissions for the plan. Unique items: true
permissions[]	Model	Each item	Expand Create plan — request body — body permissions item
scheduling	Model	Required within parent	Expand Create plan — request body — body scheduling The scheduling settings for the plan.

Referenced models: Create plan — request body — body cross Project Releases item, Create plan — request body — body custom Fields item, Create plan — request body — body exclusion Rules, Create plan — request body — body issue Sources item, Create plan — request body — body permissions item, Create plan — request body — body scheduling

Create plan — request body — body cross Project Releases item

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
name	string	Required within parent	The cross-project release name.
releaseIds	array	Optional	The IDs of the releases to include in the cross-project release. Unique items: true
releaseIds[]	integer	Each item	Format: int64

Create plan — request body — body custom Fields item

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
customFieldId	integer	Required within parent	The custom field ID. Format: int64
filter	boolean	Optional	Allows filtering issues based on their values for the custom field.

Create plan — request body — body exclusion Rules

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
issueIds	array	Optional	The IDs of the issues to exclude from the plan. Unique items: true
issueIds[]	integer	Each item	Format: int64
issueTypeIds	array	Optional	The IDs of the issue types to exclude from the plan. Unique items: true
issueTypeIds[]	integer	Each item	Format: int64
numberOfDaysToShowCompletedIssues	integer	Optional	Issues completed this number of days ago will be excluded from the plan. Format: int32
releaseIds	array	Optional	The IDs of the releases to exclude from the plan. Unique items: true
releaseIds[]	integer	Each item	Format: int64
workStatusCategoryIds	array	Optional	The IDs of the work status categories to exclude from the plan. Unique items: true
workStatusCategoryIds[]	integer	Each item	Format: int64
workStatusIds	array	Optional	The IDs of the work statuses to exclude from the plan. Unique items: true
workStatusIds[]	integer	Each item	Format: int64

Create plan — request body — body issue Sources item

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
type	string	Required within parent	The issue source type. This must be "Board", "Project" or "Filter". One of: Board, Project, Filter
value	integer	Required within parent	The issue source value. This must be a board ID if the type is "Board", a project ID if the type is "Project" or a filter ID if the type is "Filter". Format: int64

Create plan — request body — body permissions item

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
holder	Model	Required within parent	Expand Create plan — request body — body permissions item holder The permission holder.
type	string	Required within parent	The permission type. This must be "View" or "Edit". One of: View, Edit

Referenced models: Create plan — request body — body permissions item holder

Create plan — request body — body scheduling

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
dependencies	string	Optional	The dependencies for the plan. This must be "Sequential" or "Concurrent". One of: Sequential, Concurrent
endDate	Model	Optional	Expand Create plan — request body — body scheduling end Date The end date field for the plan.
estimation	string	Required within parent	The estimation unit for the plan. This must be "StoryPoints", "Days" or "Hours". One of: StoryPoints, Days, Hours
inferredDates	string	Optional	The inferred dates for the plan. This must be "None", "SprintDates" or "ReleaseDates". One of: None, SprintDates, ReleaseDates
startDate	Model	Optional	Expand Create plan — request body — body scheduling end Date The start date field for the plan.

Referenced models: Create plan — request body — body scheduling end Date

Create plan — request body — body permissions item holder

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
type	string	Required within parent	The permission holder type. This must be "Group" or "AccountId". One of: Group, AccountId
value	string	Required within parent	The permission holder value. This must be a group name if the type is "Group" or an account ID if the type is "AccountId".

Create plan — request body — body scheduling end Date

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
dateCustomFieldId	integer	Optional	A date custom field ID. This is required if the type is "DateCustomField". Format: int64
type	string	Required within parent	The date field type. This must be "DueDate", "TargetStartDate", "TargetEndDate" or "DateCustomField". One of: DueDate, TargetStartDate, TargetEndDate, DateCustomField

Policy, approvals and errors

SDK function policy ID: atlassian.createplan. Catalog operation: createplan. 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