> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Jira

> A stateful replica of Jira Cloud's REST API v3 and Agile API: projects, issues, JQL search, comments, transitions, links, watchers, users, boards and sprints.

The Jira replica implements 57 endpoints of Jira Cloud's REST API v3 and Agile API 1.0 for team-managed projects with the simplified workflow To Do, In Progress, In Review and Done. Its key is `jira`. Atlassian publishes no official JavaScript client, so the replica was tested over HTTP with Basic authentication.

## Connect

| Variable | Value |
| - | - |
| `JIRA_BASE_URL` | The site URL, standing in for `https://<site>.atlassian.net`. Paths start with `/rest/api/3/` and `/rest/agile/1.0/`. |
| `JIRA_EMAIL`, `JIRA_API_TOKEN` | Fake account email and API token. Send them as HTTP Basic: `Authorization: Basic base64(email:token)`. |

```js Node theme={null}
const auth = 'Basic ' + Buffer.from(process.env.JIRA_EMAIL + ':' + process.env.JIRA_API_TOKEN).toString('base64');
const response = await fetch(process.env.JIRA_BASE_URL + '/rest/api/3/search/jql?jql=' + encodeURIComponent('project = SUP AND statusCategory != Done') + '&fields=summary,status,assignee', { headers: { Authorization: auth, Accept: 'application/json' } });
const { issues } = await response.json();
```

This is what `ancha connect jira --lang ts` prints. Keep `fields=` on searches: without it `/search/jql` returns only issue IDs, as live Jira does.

## Endpoints

| Method | Path | Support |
| - | - | - |
| `GET` | `/rest/api/3/myself`, `/rest/api/3/serverInfo` | supported |
| `GET`, `POST` | `/rest/api/3/search/jql` | partial: a JQL subset; `fields` defaults to `id` only, as in Jira; `nextPageToken` paging |
| `POST` | `/rest/api/3/search/approximate-count` | supported |
| `GET`, `POST` | `/rest/api/3/search` | supported: answers 410, as live Jira does since Atlassian removed it |
| `POST` | `/rest/api/3/issue` | partial: system fields, parent, sprint and story points; components and versions do not exist on these projects; attachments and time tracking are gaps |
| `POST` | `/rest/api/3/issue/bulk` | partial: always a gap |
| `GET` | `/rest/api/3/issue/:key` | supported: `fields`, `expand=renderedFields,names,transitions,changelog` |
| `PUT` | `/rest/api/3/issue/:key` | partial: as create; status changes only through transitions, as in Jira |
| `DELETE` | `/rest/api/3/issue/:key` | supported |
| `PUT` | `/rest/api/3/issue/:key/assignee` | supported |
| `GET` | `/rest/api/3/issue/:key/transitions` | supported: the simplified workflow, any status to any other |
| `POST` | `/rest/api/3/issue/:key/transitions` | supported: a resolution on Done; a comment through `update` |
| `GET` | `/rest/api/3/issue/:key/changelog` | supported |
| `GET`, `POST` | `/rest/api/3/issue/:key/comment` | supported: visibility is stored, not enforced |
| `GET`, `PUT`, `DELETE` | `/rest/api/3/issue/:key/comment/:id` | supported |
| `GET`, `POST`, `DELETE` | `/rest/api/3/issue/:key/watchers` | supported |
| `POST` | `/rest/api/3/issueLink` | supported: Blocks, Relates, Duplicate and Cloners |
| `GET`, `DELETE` | `/rest/api/3/issueLink/:id` | supported |
| `GET` | `/rest/api/3/user`, `/rest/api/3/user/search`, `/rest/api/3/user/assignable/search` | supported: by display name or email prefix, or `accountId` |
| `GET` | `/rest/api/3/project`, `/rest/api/3/project/search`, `/rest/api/3/project/:key`, `/rest/api/3/project/:key/statuses` | supported |
| `GET` | `/rest/api/3/project/:key/components`, `/rest/api/3/project/:key/versions` | supported: the projects have none |
| `GET` | `/rest/api/3/issue/createmeta/:key/issuetypes`, `/rest/api/3/issue/createmeta/:key/issuetypes/:type` | supported |
| `GET` | `/rest/api/3/issuetype`, `/rest/api/3/priority`, `/rest/api/3/status`, `/rest/api/3/statuscategory`, `/rest/api/3/resolution`, `/rest/api/3/issueLinkType`, `/rest/api/3/field`, `/rest/api/3/label` | supported |
| `GET` | `/rest/agile/1.0/board`, `/rest/agile/1.0/board/:id`, `/rest/agile/1.0/board/:id/sprint`, `/rest/agile/1.0/board/:id/issue`, `/rest/agile/1.0/board/:id/backlog` | supported |
| `GET` | `/rest/agile/1.0/sprint/:id`, `/rest/agile/1.0/sprint/:id/issue` | supported |
| `POST` | `/rest/agile/1.0/sprint/:id/issue` | supported: up to 50 issues; rank options are a gap |
| `POST` | `/rest/agile/1.0/backlog/issue` | supported |
| `POST` | `/rest/agile/1.0/sprint`, `/rest/agile/1.0/sprint/:id` | partial: always a gap; sprints cannot be created, started, completed or renamed |

Anything else returns HTTP 501 with Jira's error shape and `x-ancha-gap: 1`.

## Starter data

The `jira-starter` dataset is the site **acme** (America/Los\_Angeles). The token belongs to the user `ancha`; the other users are Ben Carter, Rachel Moore, Mike Turner, Greg Wilson, Laura Kim, Tom Hughes, Ellen Price, Victor Lane, Anna Fischer and the app user "Automation for Jira".

| Project | Lead | Issues |
| - | - | - |
| `OPS` Platform Operations (with a board) | Rachel Moore | The epic "Orders API reliability" with "Investigate slow requests on /orders" (Done, with Rachel's root-cause comment), "Runbook: rollout instructions for the orders API" (In Review, Ben), "Alert on the orders.errors rate" (To Do), plus "Retry policy for payment webhooks" (In Progress, Greg) and "Load test the export pipeline before the scheduled reports beta" (To Do, due 2026-11-13). |
| `SUP` Customer Escalations | Laura Kim | "Kestrel Credit Union: dashboard shows yesterday's numbers twice" (Done), "Bluefield Logistics: SCIM provisioning with Okta" (In Progress), "Helix Manufacturing: billing emails bounce" (In Progress, Anna), "Pinecrest Health: 20 more seats mid-contract" (To Do) and "Ridgeway Robotics cannot find last month's CSV export" (To Do, created 34 minutes before start, assigned to Mike). |
| `DATA` Data Platform | Greg Wilson | "Warehouse sync: incremental loads" (In Progress, Victor) and "Data platform access for Victor" (To Do). |

Sprints on the OPS board: Sprint 41 (closed), Sprint 42 (active, "Ship the orders API reliability fixes") and Sprint 43 (future). Two issue links: the Ridgeway escalation relates to the load test, and the slow-requests bug blocks the alert task.

## Checks

Jira has no state checks. Use trace checks, for example `{ called: "POST /rest/api/3/issue" }` or `{ called: "POST /rest/api/3/issue/*/transitions" }`.

## Limits

* Atlassian publishes no official JavaScript client: call `JIRA_BASE_URL/rest/api/3/...` with HTTP Basic. `/rest/api/3/search` is gone, as on live Jira; `/search/jql` returns only issue IDs unless you request fields.
* Team-managed projects with the simplified workflow. Attachments, worklogs, webhooks, sprint changes and JQL history operators are gaps.


## Related topics

- [Tools](https://docs.ancha.io/tools/overview.md)
- [Test file (scene.yaml)](https://docs.ancha.io/reference/test-file.md)
- [Troubleshooting](https://docs.ancha.io/troubleshooting.md)
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)
- [Introduction](https://docs.ancha.io/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.