# 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 where the API responsible for your JXL app installation is hosted. Find your app's region ID in the us JXL Northern Virginia site (Atlassian USA region) eu JXL Frankfurt site (Atlassian Europe region) au JXL Sydney site (Atlassian Asia Pacific 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 Currently, the only option is a JQL statement. |
scope: value | Required | The value of the sheet scope, e.g. the JQL statement. |
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 | Optional | A keyword to specify the column content. See Column content 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) |
Column content
content | Description |
---|---|
affectsVersions | Affects versions |
affectsVersionsCount | Number of affected versions (JXL special column) |
approvers | Approvers |
assignee | Assignee |
attachments | Attachments |
attachmentsCount | Number of attachments (JXL special column) |
attachmentsSize | Attachments size (JXL special column) |
businessValue | Business value |
comments | Comments - internal and external |
commentsCount | Number of comments (JXL special column) |
components | Components |
componentsCount | Number of components (JXL special column) |
customerConversation | Comments - external only |
requestType | Request type |
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 |
fixVersions | Fix versions |
fixVersionsCount | Number of fix versions (JXL special column) |
firstCommentBy | First commented by user (JXL special column) |
firstCommentDate | Date of first comment (JXL special column) |
flagged | Flagged |
issueColor | Issue color |
issueLinks | Linked issues |
issueLinksCount | Number of issue links (JXL special column) |
labels | Labels |
labelsCount | Number of labels (JXL special column) |
lastCommentBy | Last commented by user (JXL special column) |
lastCommentDate | Date of last comment (JXL special column) |
lastUpdateAction | Last update action (JXL special column) |
lastUpdateBy | Last updated by user (JXL special column) |
linkedIssuesCount | Number of issues linked (JXL special column) |
notes | Notes (JXL special column) |
organizations | Organizations |
originalEstimate | Original estimate |
originalEstimateSum | Σ Original estimate |
parent | Parent |
parentLink | Parent link |
priority | Priority |
progress | Progress |
progressSum | Σ Progress |
project | Project |
projectCategory | Project category |
projectConfigurationType | Project configuration type (JXL special column) |
projectType | Project type (JXL special column) |
rank | Rank |
remainingEstimate | Remaining estimate |
remainingEstimateSum | Σ Remaining estimate |
reporter | Reporter |
requestLanguage | Request language |
requestParticipants | Request participants |
resolution | Resolution |
resolvedDate | Resolved date |
satisfaction | Satisfaction |
satisfactionDate | Satisfaction date |
securityLevel | Security level |
storyPoints | Story points |
storyPointsEstimate | Story points estimate |
subtasks | Sub-tasks |
subtasksCount | Number of sub-tasks (JXL special column) |
sprint | Sprint |
sprintCount | Number of sprints (JXL special column) |
status | Status |
statusCategory | Status category |
statusCategoryChanged | Status category changed date |
startDate | Start date |
summary | Summary |
targetEnd | Target end |
targetStart | Target start |
team | Team |
timeBetweenCreatedAndResolved | Time between created and resolved (JXL special column) |
timeSinceCreated | Time since created (JXL special column) |
timeSinceDueDate | Time to due date (JXL special column) |
timeSinceResolved | Time since resolved (JXL special column) |
timeSinceStatusCategoryChanged | Time since status category changed (JXL special column) |
timeSinceStatusChanged | Time since status changed (JXL special column) |
timeSinceUpdated | Time since updated (JXL special column) |
timeSpent | Time spent |
timepentSum | Σ Time spent |
updatedDate | Updated date |
votes | Votes |
watchers | Watchers |
workratio | Work ratio |
easyAgileProgramsProgram | Easy Agile: Program |
easyAgileProgramsProgramIncrement | Easy Agile: Program increment |
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 |
e.g. customfield_10000 | ID of a Custom field in your Jira site. How to find a Jira custom field ID (opens new window) |
Example
{
"title": "My awesome sheet",
"scope": {
"type": "jql",
"value": "project = 'JSWC' AND resolution = EMPTY ORDER BY createdDate DESC"
},
"columns": [
{
"content": "assignee",
"heading": "Owner"
},
{
"content": "customfield_10000",
"readonly": true
}
]
}
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": "Invalid sheet data" }
# 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 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) |
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 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" }