Jira simulator

jira-twin is a local, stateful simulator of the Jira Cloud REST API for testing code that files, works and searches issues: issues with their comments, worklogs, attachments, links, watchers and change history; projects with their versions and components; and Jira Software’s boards, sprints and epics all keep their records between calls. It never calls Jira or Atlassian, sends no email or notification and accepts any email address and API token.

Quickstart

Install the CLI, sign in and boot the simulator with RYSTIC_URL pointing at it.

On Pro you sign in with an API key from your account .

curl -fsSL https://www.rystic.ai/install.sh | sh
rystic login rys_…   # your API key
export RYSTIC_URL=$(rystic run jira-twin -d --port 0 --scenario jira_sprint_board --json | jq -r .data.url)
curl -s "$RYSTIC_URL/_rystic/version"
# -> {..."product":"jira-twin"...}

On Enterprise, the licensed edition signs in with a license file in place of the key: rystic login ./rystic-license.json (licensing ).

First calls

The default scenario is a software project, PLAT, in the middle of a sprint. Read its newest issue, file a new one and read it back:

curl -s -G "$RYSTIC_URL/rest/api/3/search/jql" -u me@example.com:token --data-urlencode 'jql=project = PLAT ORDER BY created DESC' -d fields=summary,status -d maxResults=1 | jq -c '.issues[0] | {key, summary: .fields.summary, status: .fields.status.name}'
# -> {"key":"PLAT-6","summary":"Checkout returns 500 on expired payment token","status":"Blocked"}
curl -s "$RYSTIC_URL/rest/api/3/issue" -u me@example.com:token -H 'Content-Type: application/json' -d '{"fields":{"project":{"key":"PLAT"},"issuetype":{"name":"Task"},"summary":"Retry failed webhooks"}}' | jq -c '{id, key}'
# -> {"id":"10107","key":"PLAT-7"}
curl -s "$RYSTIC_URL/rest/api/3/issue/PLAT-7?fields=summary,status" -u me@example.com:token | jq -c '{key, summary: .fields.summary, status: .fields.status.name}'
# -> {"key":"PLAT-7","summary":"Retry failed webhooks","status":"To Do"}

A search returns only issue ids unless it names fields, as Jira’s does.

Connect your client

Point a Jira library at $RYSTIC_URL as its site URL with any email address and API token, and the rest of your code stays as it is. Atlassian publishes no official Jira SDK, so these are the most used libraries. Python (jira):

import os
from jira import JIRA

jira = JIRA(server=os.environ["RYSTIC_URL"], basic_auth=("me@example.com", "token"))
print(jira.myself()["accountId"])

Node (jira.js):

import { createCloudClient } from "jira.js";

const jira = createCloudClient({
  host: process.env.RYSTIC_URL,
  auth: { type: "basic", email: "me@example.com", apiToken: "token" },
});
const me = await jira.myself.getCurrentUser();

Go (go-jira):

import (
	"os"

	jira "github.com/andygrunwald/go-jira"
)

func main() {
	tp := jira.BasicAuthTransport{Username: "me@example.com", Password: "token"}
	client, _ := jira.NewClient(tp.Client(), os.Getenv("RYSTIC_URL"))
	client.User.GetSelf()
}

A client that reads its site from a config file, such as jira-cli, takes the simulator’s URL as the server in that file.

Retries

The simulator does not rate-limit, so no request is answered 429 and a client’s backoff stays idle. Jira has no idempotency keys and the simulator reads none: a POST sent twice makes two records.

Each client’s quickstart was run against this simulator in each way it connects, with the vendor’s own hosts blocked.

Auth

The simulator takes your credential where Jira Cloud does, as HTTP Basic with an email address and an API token (curl -u me@example.com:token), and checks no value: any non-empty user name works, with any token or none.

A request acts as one default user whatever token it carries, unless it names another user as below. Each scenario names one of its own users as that default, so GET /rest/api/3/myself answers that user and the comments, worklogs and attachments you create are authored by it. To act as another seeded user, send X-Rystic-Actor: <accountId>, or bind the email address you send to its account id with POST /_rystic/credentials and {"bindings":{"<email>":"<accountId>"}} (the control plane); loading a scenario or a reset clears those bindings. With no scenario, the default is the user you seed under the key member, and myself answers account id tb-member-account-id until you seed one. A request whose Basic header has an empty user name, whose header is malformed or whose scheme is Bearer is refused with 401 and Client must be authenticated to access this resource. on a route that checks credentials. Not every route checks one: serverInfo, issue and project reads and the field and issue type lists answer a request with no credential, where Jira refuses some of them. Send a credential on every request so the code you test is the code that reaches Jira.

API version

The simulator serves Jira Cloud’s REST API versions 2 and 3 under /rest/api/2 and /rest/api/3, and the Jira Software API under /rest/agile/1.0; the version is part of the path, so you pin it by the URL you call.

Both REST versions read and write the same records: an issue created through /rest/api/2 is read back through /rest/api/3, and a description is stored as sent and returned in the form it arrived in, plain text or Atlassian Document Format, on either version. A comment follows Jira’s own split: version 2 takes a plain-text body and version 3 takes Atlassian Document Format, and a create with the other form answers 400. A path under any other version, such as /rest/api/latest or /rest/api/4, answers 404 No route in twin for GET /rest/api/4/issue/PLAT-1. GET /rest/api/3/serverInfo reports a Cloud deployment.

Coverage

Project, user and workflow administration, custom field setup, dashboards, groups, permission schemes, webhooks and Jira Service Management are out of scope; Limitations lists, by family, the published operations it does not serve, and GET /_rystic/routes lists the routes a running simulator serves. On 2026-11-06, the simulator matched Jira Cloud on 835 of the 1035 tests that compare the two (80.7%), and 17 of them gave no verdict.

170 routes, counted from the simulator’s route table.

Scenarios

The simulator ships 4 scenarios; the quickstart boots jira_sprint_board.

What each scenario holds:

• jira_fresh_site: One admin, one empty project and the full catalog of issue types, statuses, priorities, fields and link types — every issue listing returns nothing, so a first write’s effect is unmistakable.
• jira_sprint_board: Six issues across To Do, In Progress, Blocked and Done — epic, story, subtask, bug and task — on a scrum board whose three sprints run from closed through active to future, with two saved filters, comments, worklogs, watchers, votes, attachments, links, change history, both a released and an open version and two registered webhooks, one already lapsed.
• jira_triage_inbox: Attachments, remote links back to the originating tickets, watchers, three votes on the loudest report, reporter comments and a duplicate link, including one report from a deactivated reporter.

Boot one by name, or load one into a running simulator:

rystic run jira-twin -d --port 0 --scenario jira_sprint_board
curl -s -X POST "$RYSTIC_URL/_rystic/scenario" -d '{"name":"jira_sprint_board"}'

What the scenarios do not hold

• Each scenario holds one project, with Jira’s default issue types, statuses and priorities. Create more projects by seeding them (Seeding state): the simulator serves no project create.
• Without --scenario, the simulator boots with no project, issue type, status or priority, so an issue create has nothing to name. Seed those first or boot a scenario.

Seeding state

Each resource is one register, named state_<resource> (state_issue, state_project, state_sprint and so on), holding records keyed by their id; GET /_rystic/registers lists every register and its fields. Seed a project the scenario lacks, read it back and file an issue in it:

curl -s -X POST "$RYSTIC_URL/_rystic/seed" -d '{"state_project": {"10500": {"id": "10500", "key": "OPS", "name": "Operations", "projectTypeKey": "software"}}}'
curl -s "$RYSTIC_URL/rest/api/3/project/OPS" -u me@example.com:token | jq -c '{key, name}'
# -> {"key":"OPS","name":"Operations"}
curl -s "$RYSTIC_URL/rest/api/3/issue" -u me@example.com:token -H 'Content-Type: application/json' -d '{"fields":{"project":{"key":"OPS"},"issuetype":{"name":"Task"},"summary":"Rotate keys"}}' | jq -c '{id, key}'
# -> {"id":"10108","key":"OPS-1"}

A record is served as stored, with its self link filled in when you leave it out. An issue number counts per project from the seeded issues and an issue id counts across the site.

Scenarios and seeding covers seed files, refusals and the seed gate.

Features

Each feature has its own page:

• Boards, sprints and epics: Jira Software’s Agile API: boards with a backlog, sprints you run from create to complete and epics that group issues.
• Issue attachments: Upload files to an issue as Jira’s multipart form does, download them through a signed redirect and delete them.
• Versions and components: A project’s release versions and components: create, release, archive and swap versions; add, rename and remove components.

Determinism and reset

On jira_sprint_board the next issue is PLAT-7 with id 10107, and a comment or an attachment continues its own seeded numbering.

The clock moves one millisecond each time a request stamps or reports a time: creating an issue, comment, worklog, attachment or sprint, editing an issue, comment or worklog, or a serverInfo read. GET /rest/api/3/serverInfo reports it as serverTime.

Nothing moves on its own. Move the clock with POST /_rystic/clock and every later created, updated and sprint completeDate reads the new time. Reset and determinism covers reset, the clock and the RNG.

Limitations

Known issues.

• A version, component or attachment seeded by a scenario can render differently from one created through the API: a seeded version carries release and start date fields a created one lacks, no seeded component uses the project-default assignee, and a seeded attachment’s author shows an email address and avatars a created one lacks.
• A JSON write sent with the wrong Content-Type (form-urlencoded) gets a 400 error collection where Jira returns 415 with a problem document. This holds for moving issues to the backlog or into or out of an epic, swapping sprints, setting an estimate and a v2 bulk create or transition. It holds too for editing an issue, creating a component, creating or editing a version, editing a v3 comment and creating or editing a remote link. Removing a version with a swap and editing a v3 component accept the write where Jira returns 415, and registering a webhook returns 403 where Jira returns 415.
• A request with no credential can get a success where Jira refuses it. Listing labels and the bulk changelog fetch return 200 where Jira returns 401. A v3 issue create returns 201 where Jira returns 400, and the create-metadata issue types read returns 200 where Jira returns 404. Deleting a board deletes it where Jira returns 401. Other requests with no credential get a different refusal. A v2 issue create or bulk create and adding a vote return 401 where Jira returns 400, and the webhook routes return 403 where Jira returns 401.
• User search with an invalid parameter (v2 and v3) and the v3 user lookup without an account id return 400 where Jira returns 403. The v3 user lookup with an unknown parameter returns 403 where Jira returns 400, and the v2 user lookup returns 404 where Jira returns 400.
• GET /rest/api/2/field, GET /rest/api/2/project and a v2 issue read’s 404 return Content-Type application/json, where Jira returns application/json;charset=UTF-8.
• An issue’s watchers list can leave out a watcher’s emailAddress, where Jira returns an address.
• Issue edit metadata leaves out the site’s custom fields, and an invalid remote-link read answers 200 where Jira answers 403.
• Assigning an unknown assignee answers 400 where Jira answers 404, and deleting a comment without permission could not be reproduced against Jira, so the simulator’s answer there is unchecked.
• The simulator does not model Jira’s linking-disabled state, where reads of issue link types answer 404.
• GET /rest/api/2/myself omits avatarUrls for an account stored without them, where Jira returns them for every account.
• Listing a project’s components through API version 2 returns each component’s leadAccountId, a write-only field that Jira leaves out of the response; version 3 returns the component the way Jira does.
• Reading an issue with expand=changelog returns no changelog, and the expanded field names and schema leave out the site’s custom fields. Workaround: Read the history from GET /rest/api/3/issue/{key}/changelog.
• A project read doesn’t list versions or components created after the simulator started. Workaround: List them through the project’s versions and components routes.
• A board created through the API has no columns or estimation, and its issue list ignores the board’s filter.
• An issue’s sprint fields stay out of date after its sprint starts, closes or is deleted.
• An issue’s votes field doesn’t follow the votes route: a vote added through the route isn’t counted in the issue.
• Creating a filter with invalid JQL succeeds where Jira answers 400, and the saved filter’s search URL names a route Jira removed.
• Following a self link from a v2 answer for an attachment, its content, an issue link, an issue type, a status or a priority answers 404. Workaround: Read these records through /rest/api/3.
• The v3 project search includes nextPage on its last page. Workaround: Stop paging when isLast is true.
• Creating, editing or deleting a worklog adds no item to the issue’s changelog, where Jira records one.
• After a v2 worklog is logged on an issue with no estimate, timetracking omits the remaining estimate, which Jira reports as 0m. Workaround: Log worklogs through /rest/api/3, or treat an absent remaining estimate as 0.
• A version create that names its project by key, without projectId, is refused with “You must specify a valid project id.”, where Jira creates the version. Workaround: Send the project’s numeric projectId.
• A component create that carries the read-only isAssigneeTypeValid member is refused, where Jira ignores it and creates the component. Workaround: Leave isAssigneeTypeValid out of the create body.
• A newly created issue has no watcher entry for its reporter: a v3 read shows watchCount 0 and isWatching false, where Jira shows the reporter watching.
• A v2 bulk create accepts an issue with no summary or an unknown parent, which Jira refuses, and can give a new issue the key of a deleted one. Workaround: Create issues one at a time, or through the v3 bulk create route.
• A transition or edit that sets a resolution by a name the site does not have stores it: a v2 transition under Done’s id, and a v3 transition or any edit as the bare name. What Jira returns is unconfirmed. Workaround: Set only the resolutions the site lists.

Beyond the known issues, 1112 of the 1282 operations in the published spec are not served, 209 documented responses have no test yet and 221 behaviors are not modeled. The details follow.

By design.

• Few permission checks. A request can act as any seeded user (Auth), but few routes refuse a user for lack of permission. Reading a saved filter by id is refused to a user it is not shared with, though a filter search and favouriting or unfavouriting by id reach every filter, and only a filter’s owner may delete it; editing a filter you do not own answers 501. The webhook routes and the issue-edit override flags are open only to a user whose accountType is app, except the failed-webhooks list, edit metadata with an override flag and the override flag on adding a v2 worklog or updating any worklog, which refuse every user. Removing another user as a watcher through /rest/api/2/ is refused when your own user record denies MANAGE_WATCHER_LIST. Any other test of what a second user may not do has nothing to run against.
• Search is a subset of JQL. Each of the four search routes, GET and POST on /rest/api/2/search/jql and on /rest/api/3/search/jql, understands its own fixed set of fields, operators and sort fields. A clause outside it answers 400 with a short message or matches nothing and answers an empty page, where Jira refuses an unknown field. GET /rest/api/3/search/jql takes key, project, issuetype, status, statusCategory, assignee, reporter and summary and has the most sort fields (created, updated, key and Rank); a clause on labels, priority, resolution, a date or text ~ matches nothing there, while GET /rest/api/2/search/jql also takes labels and id.

Release notes: Changelog