# 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 the 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`	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
`affectsVersions`	Affects versions
`affectsVersionsCount`	Number of affected versions
`approvers`	Approvers
`assignee`	Assignee
`attachments`	Attachments
`attachmentsCount`	Number of attachments
`attachmentsSize`	Attachments size
`businessValue`	Business value
`category`	Category
`components`	Components
`componentsCount`	Number of components
`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
`flagged`	Flagged
`issueColor`	Issue color
`issueId`	Issue ID
`issueLinks`	Linked issues
`issueLinksCount`	Number of issue links
`issueUrl`	Issue URL
`labels`	Labels
`labelsCount`	Number of labels
`lastUpdateAction`	Last update action
`lastUpdateBy`	Last updated by user
`lastViewedDate`	Last viewed date
`linkedIssuesCount`	Number of issues linked
`notes`	Notes
`organizations`	Organizations
`originalEstimate`	Original estimate
`originalEstimateSum`	Σ Original estimate
`parent`	Parent
`parentLink`	Parent link
`portalIssueUrl`	Customer portal issue URL
`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
`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
`sprint`	Sprint
`sprintClosure`	Sprint closure
`sprintCount`	Number of sprints
`sprintStatus`	Sprint status
`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
`timeSinceCreated`	Time since created
`timeSinceDueDate`	Time to due date
`timeSinceLastViewed`	Time since last viewed
`timeSinceResolved`	Time since resolved
`timeSinceStatusCategoryChanged`	Time since status category changed
`timeSinceStatusChanged`	Time since status changed
`timeSinceUpdated`	Time since updated
`timeSpent`	Time spent
`timepentSum`	Σ Time spent
`updatedDate`	Updated date
`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
`lastComment`	Last comment
`lastCommentDate`	Date of last comment
`timeSinceLastComment`	Time since last comment
`lastCommentBy`	Last commented by user
`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
`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
`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
`customfield_10000` (example)	ID of a Custom field in your Jira site. How to find a Jira custom field ID (opens new window)
`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": "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" }

← Site migration Troubleshooting →