jxl.app
Open in
urlscan Pro
75.2.60.5
Public Scan
Submitted URL: https://br.jira.jxl.dev/
Effective URL: https://jxl.app/docs/guide/api/
Submission: On January 11 via api from US — Scanned from DE
Effective URL: https://jxl.app/docs/guide/api/
Submission: On January 11 via api from US — Scanned from DE
Form analysis 0 forms found in the DOM
Text Content
JXL Documentation
Guide
Releases
Roadmap
Guide
Releases
Roadmap
* * Quick demo
* Installation and purchase
* Jira Cloud
* Jira Data Center
* About sheets
* What are sheets?
* Navigating sheets
* Sheets directory
* Themes
* Managing sheets
* Creating and deleting sheets
* Creating new sheets
* Copying sheets
* Creating sheets from a filter
* Moving sheets
* Deleting sheets
* Sharing sheets
* Editing sheets
* Sheet title
* Sheet folders
* Sheet description
* Sheet scope
* Adding columns
* Removing columns
* Re-arranging columns
* Renaming columns
* Header format
* Cell format
* Cell content
* Work calendar
* Date and time format
* Making columns read-only
* Adapting sheets
* Exporting sheets
* Embedding sheets
* Working in sheets
* View preferences
* Resizing columns
* Freezing columns
* Hiding columns
* Redacting columns
* Sorting columns
* Filtering columns
* Filtering levels
* Table search
* Level-specific search and filtering
* Using logical operators
* Using regular expressions
* Working with issues
* Editing cells
* Copying and pasting values
* Bulk editing issues
* Creating issues
* Cloning issues
* Duplicating issues
* Deleting issues
* Sheet features
* Issue hierarchy
* Custom issue structure
* Grouping issues
* Sum-ups
* Ranking issues
* Re-positioning issues
* Conditional formatting
* Saved views
* Formulas
* Permissions
* Global permissions
* Scheme permissions
* Sheet permissions
* Issue permissions
* Supported fields
* Jira system fields
* Custom field types
* Third-party fields
* Smart columns
* History columns
* Time in status
* Time between statuses
* Time with assignee
* Time in status with assignee
* Time between statuses with assignee
* Date of / Time since status
* Date of / Time since status changed
* Number of statuses
* Number of status changes
* Number of assignee changes
* Merged columns
* Keyboard commands
* macOS
* Windows, Linux, etc.
* Site migration
* Migration paths
* Feature differences
* Cloud API reference
* Base URL
* Authentication
* Methods
* Create sheet
* Retrieve sheet
* Delete sheet
* Troubleshooting
* Frequently asked questions
# 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
Copied
# 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==
Copied
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
Copied
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
subtasksDonePercent Sub-tasks done percentage subtasksProgress Sub-tasks
progress subtaskStatuses Sub-task statuses 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"
}
]
}
]
}
]
}
Copied
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" }
Copied
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" }
Copied
--------------------------------------------------------------------------------
# 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
Copied
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" }
Copied
--------------------------------------------------------------------------------
# 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
Copied
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" }
Copied
Updated: 7 Jan 2025
← Site migration Troubleshooting →
© Appfire
Get support Report problems Suggest features Give feedback Rate and review
Website Blog Newsletter Security Service status SLA
Privacy Cookies Terms and conditions