What we do
Tools
Industries
Department
How we workLet's talk →
Home/Jira/Jira API
Jira

The Jira API: Authenticate, Create an Issue, and Fix What Stopped Working

Jira's REST API reads and writes almost everything the interface does: issues, comments, transitions, projects and users. On Jira Cloud you call it with an API token and your account email. Here's the setup, the calls for creating and moving an issue, and the recent changes behind most "it worked last month" errors.

The essentials

Base URL: https://your-site.atlassian.net/rest/api/3/. Version 2 (/rest/api/2/) still exists; the main difference is that v3 expects rich text in Atlassian Document Format.

Auth for a script: basic auth with your Atlassian account email as the username and an API token as the password. Your password won't work.

Make a token: in your Atlassian account's security settings.

id.atlassian.com Security Create and manage API tokens

Building an app other people install? Use OAuth 2.0 or Atlassian's Forge platform instead of personal tokens.

Why a Jira script that used to work now fails

Most of these come from changes on Atlassian's side, not your code. Work down the list.

Searches fail on the old endpoint

How you'll know: Calls to /rest/api/3/search or /rest/api/2/search return errors.

Fix: Atlassian has removed those endpoints from Jira Cloud. Move to /rest/api/3/search/jql. It pages with nextPageToken instead of startAt, so loops that counted by offset need rewriting. Ask for the fields you need explicitly. Our JQL page covers the query side.

A 401 out of nowhere

How you'll know: Every call starts failing authentication on the same morning, with no code change.

Fix: The token expired. Tokens now carry an expiry date you choose, from one day to a year, and since December 2024 new ones default to a year. Make a new one, and note the expiry date somewhere your team will see it.

A new scoped token gets rejected

How you'll know: You made an API token with scopes, and your site URL refuses it.

Fix: Scoped tokens go through Atlassian's gateway, https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/..., not your-site.atlassian.net. Swap the base URL.

The description field throws an error

How you'll know: Creating or editing an issue on v3 fails with a message that the value must be an Atlassian Document.

Fix: v3 wants descriptions and comments as Atlassian Document Format JSON, not a plain string. Build the small ADF structure (a doc containing a paragraph containing text), or send plain text to the v2 endpoint instead.

User fields are empty or rejected

How you'll know: Old code sets the assignee or reporter by username, and nothing happens.

Fix: Jira Cloud identifies people by accountId. Look it up with /rest/api/3/user/search?query= and an email or name, and cache the result.

A transition stops working after a workflow edit

How you'll know: Moving issues to Done fails, or moves them somewhere unexpected.

Fix: Transition IDs belong to a workflow, and an admin changed it. Fetch the available transitions for each issue and pick by name instead of hardcoding the number.

Bulk jobs get 429s

How you'll know: A migration or nightly sync fails partway through with 429 Too Many Requests.

Fix: Read the Retry-After header, wait that long, and spread big jobs out instead of firing requests in parallel.

Create a Jira issue with the API, then move it along

The four calls behind most integrations: a support tool, a form or a monitoring alert opening a ticket.

  1. 1

    Find out what the issue type requires

    Call GET /rest/api/3/issue/createmeta/{projectKey}/issuetypes, then the same path with the issue type ID, to see which fields are required for that project and type. Required fields differ between projects.

  2. 2

    Look up custom field IDs

    Custom fields appear in the API as customfield_10020 and so on, not by their names. GET /rest/api/3/field lists them all with their names, so you can map once and store it.

  3. 3

    Create the issue

    POST /rest/api/3/issue with a fields object holding the project key, the issue type, a summary, and anything else required. The response gives you the new issue's ID and key, such as OPS-142.

    Watch for: the description. On v3 it must be Atlassian Document Format, which is the most common first error.

  4. 4

    Transition it

    GET /rest/api/3/issue/OPS-142/transitions lists the moves available from its current status. POST to the same path with the chosen transition's ID to move it. If the transition has a screen with required fields, include them in the same request.

An API token or an OAuth app?

API token

Scripts and in-house integrations

  • Basic auth with an email and token: the quickest way to start.
  • It acts as that person. Their permissions apply and their name goes on every change.
  • It breaks when the token expires or the person leaves the company.
OAuth 2.0 or Forge

Apps other sites install

  • Each user or site authorizes your app with the scopes it asks for.
  • No shared personal credentials, and access can be revoked per site.
  • More setup, and Forge apps run on Atlassian's own hosting.

For an integration your own company relies on, run it from a dedicated account rather than a staff member's login. Atlassian's service accounts can only create scoped tokens, so plan for the gateway URL above.

Questions people ask

Does Jira have a REST API?

Yes. Jira Cloud's REST API covers issues, comments, transitions, projects, users and most of what the interface does. Jira Data Center has its own REST API, usually called with a personal access token as a bearer token rather than an email and API token.

How do I get a Jira API token?

Sign in at id.atlassian.com, open Security, and choose to create and manage API tokens. Name the token, pick an expiry date, and copy it, because you won't see it again. Use it with your account email as basic auth.

Can I create a Jira ticket using the API?

Yes. Send a POST to /rest/api/3/issue with the project, issue type, summary and any required fields. The result is the same ticket a person would create in the interface, and you can attach files, add comments and transition it with further calls.

Is there a Python library for the Jira API?

Yes. The jira package on PyPI is the most widely used, and atlassian-python-api covers Jira alongside Confluence and other Atlassian products. Both handle auth and paging for you. Check that your version supports the new JQL search endpoint before relying on it.

What's the difference between Jira API v2 and v3?

They cover the same resources. Version 3 expects and returns rich text (descriptions, comments) in Atlassian Document Format, while v2 uses plain text with wiki markup. New work should use v3, though v2 is handy for a quick script that sends plain text.

Can the Jira API tell me when an issue changes?

Not by itself; the REST API answers when you ask. To be told about changes, register a webhook or have an automation rule send a web request. Our Jira webhooks page covers that side.

Who builds and maintains a Jira API integration if we have no spare developer?

Often it's whoever on staff knows some code, until the token expires or an endpoint is removed. n-frames builds these integrations as its actual work, such as support tickets that open a Jira issue with every field filled in, and stays on the hook when Atlassian changes something underneath them.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.