# Jira Vein

Status: **live**

Connects soleprint to Jira Cloud. Fetches tickets, sprints, backlogs, and epics. Supports text and JSON output formats.

---

## What It Does

- Query your assigned tickets, project backlogs, and current sprints
- Fetch full ticket details with comments, attachments, and child work items
- Process entire epics: fetch the epic and all children, save to local storage
- Search with raw JQL
- Stream attachment content directly from Jira

## Configuration

Create a `.env` file in the vein directory or set environment variables:

```env
JIRA_URL=https://your-org.atlassian.net
JIRA_EMAIL=you@example.com
JIRA_API_TOKEN=your-api-token
API_PORT=8001
```

`JIRA_EMAIL` and `JIRA_API_TOKEN` are optional in config. They can be provided per-request via HTTP headers instead, allowing one vein instance to serve multiple users.

Generate an API token at [id.atlassian.net/manage-profile/security/api-tokens](https://id.atlassian.net/manage-profile/security/api-tokens).

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/health` | Test connection, returns authenticated user |
| GET | `/mine` | Your assigned open tickets |
| GET | `/backlog?project=KEY` | Project backlog |
| GET | `/sprint?project=KEY` | Current sprint tickets |
| GET | `/ticket/{key}` | Full ticket detail with comments and children |
| POST | `/search` | Raw JQL query |
| POST | `/epic/{key}/process` | Fetch entire epic tree, save to files (streaming) |
| GET | `/epic/{key}/status` | Check if epic has been processed |
| GET | `/attachment/{id}` | Stream attachment content |

All list endpoints support `page`, `page_size`, and `text=true` for plain-text output.

## Authentication

Credentials resolve in order:

1. HTTP headers (`X-Jira-Email`, `X-Jira-Token`)
2. `.env` file values

## Text Mode

Pass `?text=true` to any query endpoint. Returns formatted plain text instead of JSON. Useful for piping into other tools or AI prompts.

## Epic Processing

The `/epic/{key}/process` endpoint streams progress as NDJSON. It fetches the epic, then each child ticket with a short delay between requests. All tickets are saved as JSON files to `artery/larder/jira_epics/{key}/`.

## Running Standalone

```bash
cd soleprint/artery/veins/jira
python run.py
# Runs on port 8001
```

Or through soleprint, where it is mounted under `/artery/jira/`.