# 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 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:
# 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:/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:/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:/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" }