Getting Started

jira.js is a TypeScript client for the Atlassian Jira Cloud and Data Center REST APIs, for Node.js and browsers. It covers seven surfaces:

• Jira Cloud platform — issues, projects, fields, workflows
• Jira Agile — boards, sprints, backlog
• Jira Service Management — requests, queues, organizations
• Assets — objects, schemas and types, AQL
• Teams — teams, their members and external links
• Organization APIs — directories, users, groups, domains, policies, SCIM
• Jira Data Center — the self-hosted platform, Agile included

Install

npm install jira.js

See Installation for requirements and the 6.0 status.

Create a client

Each surface has a factory. Most projects need the platform one:

import { createCloudClient } from 'jira.js';

const jira = createCloudClient({
  host: 'https://your-domain.atlassian.net',
  auth: {
    type: 'basic',
    email: 'email@example.com',
    apiToken: 'YOUR_API_TOKEN',
  },
});

host is the bare site URL — the API path belongs to the request, not here.

Generate an API token at id.atlassian.com/manage-profile/security/api-tokens.

If you need more than one surface, build the client once and hand it to each factory. That matters under OAuth 2.0: two clients mean two token states, and since Atlassian rotates the refresh token on every refresh, whichever refreshes first invalidates the other's copy.

import { createClient } from 'jira.js/core';
import { createAgileClient, createCloudClient } from 'jira.js';

const client = createClient({ host, auth });

const jira = createCloudClient(client);
const agile = createAgileClient(client);

The shared client reaches the three site surfaces. The others build from their own configuration, each for its own reason. Assets does not answer on your site's host at all and needs a workspaceId — see Assets. Teams answers on the site host but takes only an API token or a bearer token, never OAuth 2.0 — see Teams. The three organization APIs sit above the site entirely, answer on api.atlassian.com and take an organization key — see Organization Administration. Data Center is a surface of its own: it speaks /rest/api/2 against your own instance, takes that instance's credentials, and is built with createServerClient — see Jira Data Center.

Make your first request

Every endpoint is a promise-returning method:

// Who am I?
const me = await jira.myself.getCurrentUser();
console.log(me.displayName);

// Search with JQL
const { issues } = await jira.issueSearch.searchForIssuesUsingJqlEnhancedSearchPost({
  jql: 'project = TEST AND statusCategory != Done ORDER BY created DESC',
  maxResults: 20,
});

for (const issue of issues ?? []) {
  console.log(issue.key, issue.fields?.summary);
}

Rich text

Fields like a comment body or an issue description take Atlassian Document Format. You can still write them as a wiki-markup string — the library routes that write through Jira's v2 endpoint, which parses the markup server-side, then reads the result back so what you get is a real document:

// Wiki markup — still works, still formats
await jira.issueComments.addComment({
  issueIdOrKey: 'TEST-1',
  body: 'h2. Heading\n\n*bold* and {code}inline{code}',
});

Reads always come back as a document, never as a string.

Next steps

• Authentication — API token, OAuth 2.0 (3LO)
• Assets — the configuration management database, and the client it is built with
• Teams — teams across the organization, and the orgId every call is addressed to
• Organization Administration — directories, users, groups and SCIM, above the site
• Jira Data Center — the self-hosted surface, its authentication and how it differs from Cloud
• Error Handling — typed errors and their predicates
• Response Validation — what happens when Jira sends something unexpected
• Tree-Shaking — keeping the bundle small
• API Reference — every endpoint, parameter and model