Getting Started

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

• Jira Cloud platform — issues, projects, fields, workflows
• Jira Agile — boards, sprints, backlog
• Jira Service Management — requests, queues, organizations

Install

npm install jira.js@next

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);

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)
• 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