# 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 logo menu at top right of any Sheet page.
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://us.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://us.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  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://us.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 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: 16 June 2022