# Cloud API reference

Keep in mind

The JXL API v1 is available in JXL for Jira Cloud only.

The API enables you, for example, to create Sheets using Jira automation rules (opens new window). The API expects and responds with data in JSON (opens new window) format.

# Base URL

https://{regionId}.jira.jxl.dev

Parameters

Name Necessity Description
regionId Required The ID of the AWS region (opens new window) where the API responsible for your JXL app installation is hosted. Find your app's region ID in the app menu at the top right of any Sheet page.
au  JXL Sydney site (Atlassian Australia region)
jp  JXL Tokyo site (Atlassian Japan region)
kr  JXL Seoul site (Atlassian South Korea region)
sg  JXL Singapore site (Atlassian Singapore region)
in  JXL Mumbai site (Atlassian India region)
eu  JXL Frankfurt site (Atlassian Europe region)
de  JXL Frankfurt site (Atlassian Germany region)
ch  JXL Zürich site (Atlassian Switzerland region)
gb  JXL London site (Atlassian UK region)
br  JXL São Paulo site (Atlassian Brazil region)
ca  JXL Montreal site (Atlassian Canada region)
us  JXL Northern Virginia site (Atlassian USA region)

Example

https://au.jira.jxl.dev

# Authentication

The API uses the basic HTTP authentication (opens new window) scheme for purposes of authentication and authorisation. This means all requests must have an Authorization header that contains the word Basic followed by a space and a Base64 (opens new window)-encoded string username:password. Example:

Authorization: Basic ZGVtbzpwQDU1dzByZA==

For the username use the email address that you use to sign in to your Jira site. For the password it's recommended to use an API token. How to obtain an API token from Atlassian (opens new window)
Example: max@planetexpress.earth:oWC3B0wqDLYXvaAlnzrH38E2
Make sure to Base64-encode the string before sending it.

Make sure the User you are authenticating the request with has the necessary Permissions for the changes you'd like to make via the API.

# Methods

# Create sheet

POST /api/1/sites/{siteHostname}/projects/{projectKey}/sheets

Request

Path parameters

Name Necessity Description
siteHostname Required The hostname of your Jira Cloud site.
projectKey or projectId Required The Project key of the Project in which you'd like the Sheet to be located. Alternatively, the ID of the Project in which you'd like the Sheet to be located. How to find a Jira project ID (opens new window)

Example

https://au.jira.jxl.dev/api/1/sites/mysite.atlassian.net/projects/ABC/sheets

Body parameters

Name Necessity Description
title Required The title of the Sheet.
scope Required The sheet scope, i.e. the set of Issues you'd like to be listed in the table.
scope
type
Required The type of sheet scope.
jql JQL statement
filter  Jira Filter
scope
value
Required The value of the sheet scope. Can be either a JQL statement or a Filter ID, depending on the chosen type of scope.
rowNumbers Optional Whether row numbers should be shown in the table.
true  for row numbers visible
false  for row numbers hidden (default)
columns Optional An object defining the column layout of the Sheet. The columns will appear in the order listed from left to right. If omitted, the default column layout will be used for the Sheet.
columns[]
content
Required A keyword to specify the column content. See Content keywords below for more information.
columns[]
heading
Optional Your column heading, which supersedes the default heading.
columns[]
readonly
Optional Whether the column's cells should be read-only.
true  for read-only column
false  for editable column, if it's editable (default)
structures Optional An object defining the Structures in the Sheet.
structures[]
title
Required The title of the Structure.
structures[]
hierarchyIssueListing
Optional Whether individual Issues can be displayed more than once across Hierarchy Levels in the table.
single  List Issues once (default)
multiple  List Issues more than once where applicable
structures[]
levels
Required An object defining the Levels of the Structure.
structures[] levels[]
type
Required The type of Level.
aggregation  Sum-up level
grouping  Grouping level
hierarchy  Hierarchy level
structures[] levels[]
groupBy
Required A keyword to specify the content to group by. Only applicable for Levels of type: grouping. See Content keywords below for more information.
structures[] levels[]
aggregate
Optional Whether the Grouping should be summed up. Only applicable for Levels of type: grouping.
true Grouping with sum-up
false Grouping without sum-up
structures[] levels[]
issueTypeMatches
Required The Issue type/s of the Level. Add multiple items if needed. Only applicable for Levels of type: hierarchy.
structures[] levels[] issueTypeMatches[]
type
Required Whether the Issue type match for the Level is specified or a wildcard.
defined  Specific Issue type
wildcard  Wildcard for Issue types
structures[] levels[] issueTypeMatches[]
issueType
Required An Issue type ID to match for the Level. Only applicable for issueTypeMatches items of type: defined. How to find an Issue type ID (opens new window)
structures[] levels[] issueTypeMatches[]
hierarchyLevel
Optional The Jira issue type level (opens new window) that the wildcard should match. Only applicable for issueTypeMatches items of type: wildcard. Omit this parameter to match Issue types of all Jira issue type levels.
-1  Only Sub-task issue types
 0  Only Base issue types
 1  Only Epic issue types
structures[] levels[] issueTypeMatches[]
pattern
Required A pattern to match Issue type/s for the Level. Only applicable for issueTypeMatches items of type: wildcard.
all  All Issue types
remaining  Only Issue types that haven't been specified in any other Level of the Structure
structures[] levels[]
parentLinkages
Required The Parent linkage/s of the Level. Add multiple items if needed. Only applicable for Levels of type: hierarchy.
structures[] levels[] parentLinkages[]
type
Required The type of Parent linkage.
default  Uses the Jira default Field/s
defined  Uses an Issue link description
structures[] levels[] parentLinkages[]
issueLinkType
Required An Issue link type ID to determine Parent linkage. Only applicable for parentLinkages items of type: defined.
structures[] levels[] parentLinkages[]
direction
Required The direction of the Issue link description to determine Parent linkage. Only applicable for parentLinkages items of type: defined.
out  Outward Issue link description
in  Inward Issue link description
Content keywords
content Description
activeSprint Active sprint
affectedServices Affected services
affectedServicesCount Number of affected services
affectsVersions Affects versions
affectsVersionsCount Number of affected versions
affectsVersionDescription Affected version description
affectsVersionReleaseDate Affected version release date
affectsVersionStatus Affected version status
allCommenters All commenters
approvers Approvers
assignee Assignee
assigneeChangesCount Number of assignee changes
assigneeDomain Domain of assignee
atlasProjectKey Atlas project key
atlasProjectStatus Atlas project status
attachments Attachments
attachmentsCount Number of attachments
attachmentsSize Attachments size
businessValue Business value
category Category
components Components
componentsCount Number of components
createdDate Created date
description Description
developmentBuildsCount Number of builds
developmentBuildsStatus Builds status
developmentPullRequestsCount Number of pull requests
developmentPullRequestsStatus Pull requests status
dueDate Due date
environment Environment
epicColor Epic color
epicLink Epic link
epicName Epic name
epicStatus Epic status
epicTheme Epic theme
firstSprint First sprint
fixVersions Fix versions
fixVersionsCount Number of fix versions
fixVersionDescription Fix version description
fixVersionReleaseDate Fix version release date
fixVersionStatus Fix version status
flagged Flagged
futureSprint Future sprint
issueColor Issue color
issueId Issue ID
issueLinkDescriptions Issue link descriptions
issueLinks Issue links
issueLinksCount Number of issue links
issueLinkTypes Issue link types
issueUrl Issue URL
labels Labels
labelsCount Number of labels
lastPublicActivityDate Date of last public activity
lastSprint Last sprint
lastUpdateAction Last update action
lastUpdateBy Last updated by user
lastViewedDate Last viewed date
linkedIssues Linked issues
linkedIssuesCount Number of linked issues
linkedIssueStatuses Linked issue statuses
linkedIssueTypes Linked issue types
notes Notes
openSprint Open sprint
organizations Organizations
originalEstimate Original estimate
originalEstimateSum Σ Original estimate
parent Parent
parentIssueType Parent issue type
parentLink Parent link
parentPriority Parent priority
parentStatus Parent status
parentSummary Parent summary
portalIssueUrl Customer portal issue URL
previousStatus Previous status
priority Priority
progress Progress
progressSum Σ Progress
project Project
projectCategory Project category
projectConfigurationType Project configuration type
projectId Project ID
projectKey Project key
projectType Project type
rank Rank
remainingEstimate Remaining estimate
remainingEstimateSum Σ Remaining estimate
reporter Reporter
reporterDomain Domain of reporter
requestChannel Request channel
requestLanguage Request language
requestParticipants Request participants
requestType Request type
resolution Resolution
resolvedDate Resolved date
satisfaction Satisfaction
satisfactionComment Satisfaction comment
satisfactionDate Satisfaction date
securityLevel Security level
storyPoints Story points
storyPointsEstimate Story points estimate
subtasks Sub-tasks
subtasksCount Number of sub-tasks
subtasksProgress Sub-tasks progress
sprint Sprint
sprintClosure Sprint closure
sprintCount Number of sprints
sprintGoal Sprint goal
sprintStatus Sprint status
startDate Start date
status Status
statusCategory Status category
statusCategoryChangedDate Status category changed date
statusChangedDate Status changed date
statusChangesCount Number of status changes
statusDate Date of status
statusesCount Number of statuses
summary Summary
targetEnd Target end
targetStart Target start
team Team
timeBetweenCreatedAndFirstResponseToCustomer Time between created and first response to customer
timeBetweenCreatedAndResolved Time between created and resolved
timeBetweenStatuses Time between statuses
timeBetweenStatusesWithAssignee Time between statuses with assignee
timeInStatus Time in status
timeInStatusWithAssignee Time in status with assignee
timeSinceAffectsVersionReleaseDate Time since affected version release date
timeSinceCreated Time since created
timeSinceDueDate Time to or since due date
timeSinceFixVersionReleaseDate Time to fix version release date
timeSinceLastViewed Time since last viewed
timeSinceLastPublicActivity Time since last public activity
timeSinceResolved Time since resolved
timeSinceStartDate Time to or since start date
timeSinceStatus Time since status
timeSinceStatusCategoryChanged Time since status category changed
timeSinceStatusChanged Time since status changed
timeSinceTargetEnd Time to or since target end
timeSinceTargetStart Time to or since target start
timeSinceUpdated Time since updated
timeSpent Time spent
timespentSum Σ Time spent
timeWithAssignee Time with assignee
updatedDate Updated date
updatesCount Number of updates
votes Votes
watchers Watchers
workratio Work ratio
commentsCount Number of comments
allComments All comments
firstComment First comment
firstCommentDate Date of first comment
timeSinceFirstComment Time since first comment
firstCommentBy First commented by user
firstCommentVisibility First comment visibility
lastComment Last comment
lastCommentDate Date of last comment
timeSinceLastComment Time since last comment
lastCommentBy Last commented by user
lastCommentVisibility Last comment visibility
firstInternalComment First internal comment
firstInternalCommentDate Date of first internal comment
timeSinceFirstInternalComment Time since first internal comment
firstInternalCommentBy First internally commented by user
lastInternalComment Last internal comment
lastInternalCommentDate Date of last internal comment
timeSinceLastInternalComment Time since last internal comment
lastInternalCommentBy Last internally commented by user
allExternalComments All external comments
firstExternalComment First external comment
firstExternalCommentDate Date of first external comment
timeSinceFirstExternalComment Time since first external comment
firstExternalCommentBy First externally commented by user
lastExternalComment Last external comment
lastExternalCommentDate Date of last external comment
timeSinceLastExternalComment Time since last external comment
lastExternalCommentBy Last externally commented by user
firstCommentByCustomer First comment by customer
firstCommentByCustomerDate Date of first comment by customer
timeSinceFirstCommentByCustomer Time since first comment by customer
firstCommentByCustomerBy First commented by customer
lastCommentByCustomer Last comment by customer
lastCommentByCustomerDate Date of last comment by customer
timeSinceLastCommentByCustomer Time since last comment by customer
lastCommentByCustomerBy Last commented by customer
firstResponseToCustomer First response to customer
firstResponseToCustomerDate Date of first response to customer
timeSinceFirstResponseToCustomer Time since first response to customer
firstResponseToCustomerBy First responded to customer by user
lastResponseToCustomer Last response to customer
lastResponseToCustomerDate Date of last response to customer
timeSinceLastResponseToCustomer Time since last response to customer
lastResponseToCustomerBy Last responded to customer by user
appfireBigPictureRiskConsequence BigPicture: Risk consequence
appfireBigPictureRiskProbability BigPicture: Risk probability
appfireBigPictureTaskMode BigPicture: Task mode
easyAgileProgramsProgram Easy Agile: Program
easyAgileProgramsProgramIncrement Easy Agile: Program increment
digitalRoseESignSignatureExport eSign: Signature export
digitalRoseESignSignatureCount eSign: Signature count
digitalRoseESignSignatureFinalized eSign: Signature finalised
digitalRoseESignSignaturePending eSign: Signature pending
digitalRoseESignSignatureStatusCount eSign: Signature status count
digitalRoseESignSignedBy eSign: Signed by
digitalRoseESignSignedOn eSign: Signed on
heroCodersIssueChecklist Issue Checklist: Checklist
heroCodersIssueChecklistCompleted Issue Checklist: Checklist Completed
heroCodersIssueChecklistProgress Issue Checklist: Checklist progress
heroCodersIssueChecklistProgressPercent Issue Checklist: Checklist progress %
tempoAccount Tempo: Account
tempoTeam Tempo: Team
customfield_10000 (example) ID of a Custom field in your Jira site. How to find a Jira custom field ID (opens new window)
customfield_10000:goalDuration (example) SLA - Goal duration
customfield_10000:timeElapsed (example) SLA - Time elapsed
customfield_10000:timeRemaining (example) SLA - Time remaining
customfield_10000:timeSinceBreached (example) SLA - Time since breached
customfield_10000:progressPercent (example) SLA - Progress
customfield_10000:cycleStatus (example) SLA - Cycle status
customfield_10000:metVsBreached (example) SLA - Met vs breached
customfield_10000:startTime (example) SLA - Start time
customfield_10000:finishTime (example) SLA - Finish time
customfield_10000:breachTime (example) SLA - Breach time
customfield_10000:timeDifference (example) Date or datetime custom field - Time to or since value
customfield_10000:count (example) Multi value custom field - Number of values
merged:{fuzzy-field-type}:{field-name}
merged:group:Assigned teams (example)
To specify a merged column use the keyword merged followed by a colon, a fuzzy field type identifier, another colon, and the Field's name. Available fuzzy field type identifiers:
text  Text fields
select  Select list fields
people  People fields
group  Group fields
version  Version fields
labels  Label fields
number  Number fields
date  Date fields
date-time  Date time fields

Example

{
    "title": "My awesome sheet",
    "scope": {
        "type": "jql",
        "value": "project = 'ABC' AND resolution = EMPTY ORDER BY createdDate DESC"
    },
    "columns": [
        {
            "content": "assignee",
            "heading": "Ticket owner"
        },
        {
            "content": "customfield_10000",
            "readonly": true
        }
    ],
    "structures": [
        {
            "title": "My custom issue structure",
            "hierarchyIssueListing": "single",
            "levels": [
                { 
                    "type": "aggregation"
                },
                { 
                    "type": "grouping",
                    "groupBy": "sprint",
                    "aggregate": true
                },
                {
                    "type": "hierarchy",
                    "issueTypeMatches": [
                        {
                            "type": "defined",
                            "issueType": "10000"
                        }
                    ],
                    "parentLinkages": [
                        {
                            "type": "default"
                        }
                    ]
                },
                {
                    "type": "hierarchy",
                    "issueTypeMatches": [
                        {
                            "type": "wildcard",
                            "pattern": "remaining",
                            "hierarchyLevel": 0
                        }
                    ],
                    "parentLinkages": [
                        {
                            "type": "defined",
                            "issueLinkType": "10000",
                            "direction": "out"
                        }
                    ]
                }
            ]
        }
    ]
}

Response

Success

HTTP code Description
200 OK - The creation of the Sheet was successful. You can find the ID of the newly created Sheet in the response body.

Example

{ "id": "RC0PL9tv" }

Errors

HTTP code Description
400 Bad request - The request data has an unexpected shape. Or JXL is not installed in the specified Jira site.
401 Unauthorized - The request is missing a valid Authorization header.
403 Forbidden - The User whose credentials were provided can’t sign in to the Jira site specified in the request. Or the specified Project doesn’t exist. Or the User doesn’t have the required Permissions for the operation.
452 The JXL app doesn’t have the required Permissions.
* The request to the Jira API failed. Check the jiraError parameter of the response body for an explanation.

Example

{ "message": "No authorization provided" }

# Retrieve sheet

GET /api/1/sites/{siteHostname}/projects/{projectKey}/sheets/{sheetId}

Request

Path parameters

Name Necessity Description
siteHostname Required The hostname of your Jira Cloud site.
projectKey or projectId Required The Project key of the Project in which the Sheet is located. Alternatively, the ID of the Project in which the Sheet is located. How to find a Jira project ID (opens new window)
sheetId Required The ID of the Sheet you'd like to retrieve. The ID is the string towards the end of a Sheet's URL in your browser's address bar.

Example

https://au.jira.jxl.dev/api/1/sites/mysite.atlassian.net/projects/ABC/sheets/RC0PL9tv

Response

Success

HTTP code Description
200 OK - The retrieval of the Sheet was successful. The response body will deliver the Sheet data.

Example

See the Create sheet method's request body parameters.

Errors

HTTP code Description
400 Bad request - The request data has an unexpected shape. Or JXL is not installed in the specified Jira site.
401 Unauthorized - The request is missing a valid Authorization header.
403 Forbidden - The User whose credentials were provided can’t sign in to the Jira site specified in the request. Or the specified Project doesn’t exist. Or the specified Sheet doesn’t exist. Or the User doesn’t have the required Permissions for the operation.
452 The JXL app doesn’t have the required Permissions.
512 The requested Sheet contains invalid data.
* The request to the Jira API failed. Check the jiraError parameter of the response body for an explanation.

Example

{ "message": "No authorization provided" }

# Delete sheet

DELETE /api/1/sites/{siteHostname}/projects/{projectKey}/sheets/{sheetId}

Request

Path parameters

Name Necessity Description
siteHostname Required The hostname of your Jira Cloud site.
projectKey or projectId Required The Project key of the Project in which the Sheet is located. Alternatively, the ID of the Project in which the Sheet is located. How to find a Jira project ID (opens new window)
sheetId Required The ID of the Sheet you'd like to delete. The ID is the string towards the end of a Sheet's URL in your browser's address bar.

Example

https://au.jira.jxl.dev/api/1/sites/mysite.atlassian.net/projects/ABC/sheets/RC0PL9tv

Response

Success

HTTP code Description
204 No content - The deletion of the Sheet was successful. The response body will be empty.

Errors

HTTP code Description
400 Bad request - The request data has an unexpected shape. Or JXL is not installed in the specified Jira site.
401 Unauthorized - The request is missing a valid Authorization header.
403 Forbidden - The User whose credentials were provided can’t sign in to the Jira site specified in the request. Or the specified Project doesn’t exist. Or the specified Project doesn’t exist. Or the specified Sheet doesn’t exist. Or the User doesn’t have the required Permissions for the operation.
452 The JXL app doesn’t have the required Permissions.
* The request to the Jira API failed. Check the jiraError parameter of the response body for an explanation.

Example

{ "message": "Invalid sheet data" }
Updated: 3 Dec 2024