The Jira Service Management REST API, with Examples

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

What the JSM API covers

The Jira Service Management API is a distinct REST surface from the core Jira platform API. Atlassian Cloud exposes it under the /rest/servicedeskapi/ base path, and it models the concepts that make a service desk different from a plain issue tracker: customer requests, request types, queues, SLA timers, approvals, participants, organizations, and customers. If you have tried to read SLA data or queue contents through the ordinary /rest/api/3/ Jira endpoints, you already know they are not there. They live in the service desk API.

This post walks the endpoints that matter most in day-to-day operations and shows the exact atlassian-cli command that calls each one, so you can script them without hand-writing HTTP requests. Every command below is verified against the command reference.

How this differs from Atlassian's own CLI. atlassian-cli is an independent, community open-source project. It is not Atlassian's official CLI (acli) and is not affiliated with Atlassian. Use the official acli for first-party vendor support; use atlassian-cli if you want a single free Rust binary spanning Jira, Confluence, Bitbucket, and JSM with a consistent flag layout across all four.

Authentication

The service desk API authenticates exactly like the rest of Atlassian Cloud: your account email plus an API token, sent over HTTPS Basic auth against your site base URL. There is no separate JSM credential and no separate login. Configure one profile and it works for every product group.

# Log in once; the same profile serves jira, confluence, bitbucket, and jsm
atlassian-cli auth login \
  --profile support \
  --base-url https://your-site.atlassian.net \
  --email you@company.com \
  --token $ATLASSIAN_TOKEN \
  --default

# Confirm the credential resolves
atlassian-cli auth test --profile support

Generate the token from your Atlassian account security settings, keep it in an environment variable rather than in shell history, and add --profile support to any command that should target this site. For the full profile model, including multiple sites and per-command overrides, see the authentication guide.

The requests endpoint

Customer requests are the heart of the service desk API. In raw REST terms they live at /rest/servicedeskapi/request, with per-request detail at .../request/{issueIdOrKey}. A request is a Jira issue underneath, but the servicedeskapi view carries the portal fields, request type, current status, and customer context that the plain issue API omits.

Creating a request through the API requires two ids: the service desk it belongs to and the request type within that desk. Discover both before you create anything.

# 1. List service desks to find the id
atlassian-cli jsm service-desk list --limit 25

# 2. List request types for service desk 10
atlassian-cli jsm request-type list --servicedesk-id 10 --limit 25

# 3. Create a request (POST /rest/servicedeskapi/request)
atlassian-cli jsm request create \
  --servicedesk-id 10 \
  --request-type-id 7 \
  --summary "VPN access issue" \
  --description "Cannot connect from the Berlin office"

Once a request exists you can drive it through its lifecycle. The API exposes available transitions, comments (public or internal), participants, and status, each as its own sub-resource under the request key.

# Inspect a single request
atlassian-cli jsm request get SD-123
atlassian-cli jsm request status SD-123

# See valid transitions, then apply one
atlassian-cli jsm request transitions SD-123
atlassian-cli jsm request transition SD-123 --transition "In Progress"

# Add a public reply the customer sees, or drop --public for an internal note
atlassian-cli jsm request add-comment SD-123 --body "Investigating now" --public

The --public flag maps directly to the public field on the comment endpoint. Omit it and the comment stays internal to agents, which is the difference between a customer-facing update and a private working note.

SLA endpoints

SLAs are the endpoint people most often reach the API for, because there is no clean way to bulk-read them in the portal. The service desk API serves them at /rest/servicedeskapi/request/{issueIdOrKey}/sla, returning each configured metric with its cycle state and remaining time.

# Every SLA metric on a request
atlassian-cli jsm sla list SD-123

# One specific metric by id, e.g. time to resolution
atlassian-cli jsm sla get SD-123 --sla-id time-to-resolution

Where this becomes useful is JSON output. Pull the SLA data as JSON and you can filter for anything close to breaching, then feed the result into an alert or a stand-up report.

# Flag requests whose resolution SLA has an ongoing (unbreached but running) cycle
atlassian-cli jsm sla list SD-123 --format json \
  | jq '.[] | select(.name == "Time to resolution")'

Because the CLI shares one output layer across every command, the same --format json, --format csv, and --envelope flags documented in the command reference behave identically here as they do for Jira issue search. That consistency is what lets you compose SLA reads into larger scripts without special-casing JSM.

Queues

Queues are how agents actually see their work, and they are entirely a service desk concept. The API lists them at /rest/servicedeskapi/servicedesk/{id}/queue and returns the issues inside a queue at that path plus /{queueId}/issue. A queue is a saved JQL filter with a defined column set, so reading it through the API gives you exactly what an agent sees in the portal, in a form you can page and export.

# List queues for service desk 10 to find queue ids
atlassian-cli jsm queue list 10

# Inspect one queue's definition
atlassian-cli jsm queue get 10 5

# Page through the issues currently in queue 5
atlassian-cli jsm queue issues 10 5 --limit 25

Exporting a queue to CSV is a common request from team leads who want a snapshot for a weekly review without handing out portal logins.

# Snapshot the triage queue for a weekly review
atlassian-cli jsm queue issues 10 5 --limit 100 --format csv > triage-queue.csv

Approvals and participants

Change and access requests frequently gate on an approval step. The API models approvals under /rest/servicedeskapi/request/{issueIdOrKey}/approval, and the CLI mirrors that with list, get, approve, and decline verbs. This is the piece you automate when you want an approval to fire from a chat command or a pipeline rather than a portal click.

# See pending approvals on a request
atlassian-cli jsm approval list SD-123

# Approve or decline a specific approval by id
atlassian-cli jsm approval approve SD-123 --approval-id 1
atlassian-cli jsm approval decline SD-123 --approval-id 1

Participants are the other request sub-resource worth scripting. Adding a participant by account id notifies another agent or stakeholder and gives them visibility, which is handy when a ticket needs a specialist pulled in.

atlassian-cli jsm request participants SD-123
atlassian-cli jsm request add-participant SD-123 --account-id 5f0a1b2c3d4e

The same API also governs who is allowed to raise requests in the first place. Customers live at /rest/servicedeskapi/customer and organizations at /rest/servicedeskapi/organization, and both are directly scriptable. Onboarding a new team, for example, is a create-then-link pattern: make the organization, then attach it to the service desk that should serve it.

# Create an organization and attach it to service desk 10
atlassian-cli jsm organization create --name "ACME Ops"
atlassian-cli jsm service-desk add-organization 10 --org-id 42

# Create a customer account for the portal
atlassian-cli jsm customer create --email new@customer.com --display-name "New Customer"

Grouping customers into organizations at the API level is what lets you manage access by team rather than one account at a time, which matters once a desk serves more than a handful of external users.

Endpoint-to-command map

If you already think in REST paths, this table is the fastest way to find the CLI equivalent. Every command is a real subcommand from the reference, not a wrapper you have to build.

A real triage script

Individual commands are useful, but the payoff of a scriptable API is composition. Here is a small triage check that a lead could run each morning: it lists the open requests in a queue, reads SLA state on the newest ticket, and posts an internal note. It uses only the endpoints covered above.

#!/bin/bash
# Morning JSM triage snapshot
set -euo pipefail

PROFILE="support"
DESK=10
QUEUE=5

# 1. How many issues are sitting in the triage queue right now?
COUNT=$(atlassian-cli jsm queue issues "$DESK" "$QUEUE" \
  --profile "$PROFILE" --format json | jq 'length')
echo "Triage queue has $COUNT open requests."

# 2. Grab the most recent request key from that queue
KEY=$(atlassian-cli jsm queue issues "$DESK" "$QUEUE" \
  --profile "$PROFILE" --limit 1 --format json | jq -r '.[0].key')

# 3. Read its SLA metrics so the lead sees any pressure early
atlassian-cli jsm sla list "$KEY" --profile "$PROFILE"

# 4. Drop an internal note that triage has started
atlassian-cli jsm request add-comment "$KEY" \
  --profile "$PROFILE" \
  --body "Picked up in morning triage."

echo "Triage snapshot complete for $KEY."

The important detail is that every step reads or writes through the service desk API, yet the script never touches a raw URL, a Basic auth header, or a pagination cursor. The CLI handles those, and the JSON output slots straight into jq. Extend the same pattern to loop over multiple queues, or wire it into a scheduler for a daily digest.

FAQ

Related Resources