Turn a Jira Cloud issue into a PDF, or a JQL query into release notes with a contents page (Python script)

Setup: an API token, a PaperType key, one command

Create a free API key at /signup. On the Jira side you need an Atlassian API token (the page "Manage API tokens for your Atlassian account", support.atlassian.com, fetched 2026-10-25): log in at id.atlassian.com/manage-profile/security/api-tokens, Create API token, name it, pick an expiry ("1 to 365 days"; new tokens expire after a year by default), Create, Copy to clipboard; "you can't recover the API token after you're done with this step". The token is used with HTTP basic authentication, your account email as the user name (Atlassian's own example: curl https://mysite.atlassian.net --user me@example.com:my-api-token). Atlassian recommends the newer API token with scopes; those must be sent to https://api.atlassian.com/ex/jira/{cloudId} instead of your site URL, so set JIRA_SITE to that address if you use one. The basic-auth reference adds that Jira does not send an authentication challenge, so a client has to send the header on the first request; the script always does.

export JIRA_SITE=https://your-domain.atlassian.net
export JIRA_EMAIL=me@example.com
export JIRA_API_TOKEN=...                 # id.atlassian.com → Security → API tokens
export PAPERTYPE_API_KEY=dp_...           # from /signup
curl -sO https://papertype.dev/static/jira/papertype-jira.py

python3 papertype-jira.py PROJ-123
#  PROJ-123-Checkout-fails-with-Apple-Pay.pdf  2 page(s)

python3 papertype-jira.py https://your-domain.atlassian.net/browse/PROJ-123 issue.pdf --theme report --page-size Letter
python3 papertype-jira.py PROJ-123 --fields customfield_10020,customfield_10016 --footer "Confidential"   # add Sprint, Story points
python3 papertype-jira.py PROJ-123 --url     # print a 24-hour download link instead of saving

The argument is an issue key or any Jira URL that contains one (the browse URL, a board URL with selectedIssue=); from a URL the site is taken too, so JIRA_SITE is optional then. What the script sends to Jira, all GET, each quoted from the REST API v3 reference fetched 2026-10-25:

• /rest/api/3/issue/{key}?expand=renderedFields,names&fields=summary,issuetype,status,…,description,environment. The reference: renderedFields "returns field values rendered in HTML format" and names "returns the display name of each field", which is where the table's labels come from (Fix versions, Story point estimate, your custom field's name). Needs the Browse projects permission; classic scope read:jira-work.
• /rest/api/3/issue/{key}/comment?expand=renderedBody&maxResults=100&startAt=…&orderBy=created → {comments: [{author, body, renderedBody, created, updated}], startAt, maxResults, total}; renderedBody is "the rendered version of the comment". The script pages with startAt until total.
• /rest/api/3/attachment/content/{id}?redirect=false for images: without the flag Jira answers 303 to the file store; with it, "returned if the request is successful when redirect is set to false" is a 200 with the bytes. Needs Browse projects on the issue.
• /rest/api/3/search/jql?jql=…&fields=…&expand=renderedFields,names&maxResults=100&nextPageToken=… for --jql, see below.

Then one POST to https://papertype.dev/v1/pdf with the HTML the script built, the html field rather than markdown because the description arrives as HTML:

{
  "html": "<h1>PROJ-123: Checkout fails with Apple Pay</h1><p class='lead'><strong>Bug · In Progress · High · Assignee Mia Krystof</strong></p><table class='meta-table'><tr><th>Status</th><td>In Progress</td></tr>…</table><h2>Description</h2><p>Main order flow broken.</p><p><img src=\"data:image/png;base64,…\" alt=\"picture.png\"></p>…<h2>Comments (2)</h2>…",
  "css": "table.issues td, table.issues th { font-size: 9pt; } a.pg::after { content: target-counter(attr(href), page); } section.issue { page-break-before: always; } …",
  "title": "PROJ-123: Checkout fails with Apple Pay",
  "theme": "clean",
  "page_size": "A4",
  "page_numbers": true,
  "filename": "PROJ-123-Checkout-fails-with-Apple-Pay.pdf",
  "output": "pdf"
}

Live result on 2026-10-25 for the test issue (fifteen fields, a description with an inline image, a sub-task, a linked issue, two attachments, two comments): 200, 2 pages with the report theme; the text read back from the PDF had the key and summary, the status, the assignee, the sprint name, the sub-task, the linked issue, the attachment's file name, both comments and the footer.

What goes on the page

Title KEY: summary; one bold line with type, status, priority and assignee; a table of every field that has a value, labelled with the names your Jira uses (type, status, priority, resolution, assignee, reporter, created, updated, resolved, due date, labels, components, fix versions, affects versions, parent, plus anything in --fields); Description; Environment when set; Sub-tasks and Linked issues as lists with each one's status ("is depended by PR-2 Payment SDK upgrade (Open)"); an Attachments table (file, size, who, when) with image attachments shown below it; Comments (n) in creation order with author, date and an edited marker; a footer line with the key, the site and the date. Rules, each exercised by the script's test:

• Rendered HTML first, ADF second. The description and comments use Jira's own HTML rendering when renderedFields / renderedBody carry one. When the rendered value is null (the test's second issue), the script converts the Atlassian Document Format itself: headings, paragraphs, bullet and numbered lists, task lists (☑ / ☐), code blocks, quotes, panels, tables, rules, links, mentions, dates, status lozenges, emoji as their :short_name: (the renderer has no colour-emoji font), and a [attachment name] placeholder for media, whose ADF ids are not attachment ids. A custom field holding ADF prints as plain text in the table.
• Values. Users print as their display name; options, statuses, versions and components as their name; lists comma-joined; the parent and linked issues as KEY summary; 2026-10-06T07:32:47.000+0000 as 2026-10-06 07:32 +0000 (the zone Jira sent, unchanged); plain dates stay; numbers drop trailing zeros; booleans are Yes/No. Fields with no value are not rows.
• Safety. Everything from a field is HTML-escaped; from the rendered HTML the script removes <script>, <style> and on*= attributes, and makes site-relative links absolute so /browse/EX-10 in a comment is clickable in the PDF.
• Extra fields. --fields customfield_10020,customfield_10016 adds any field by its REST id, custom fields included; the label is whatever Jira's names map says. The id is visible in the issue's JSON (…/rest/api/3/issue/KEY in a browser) or in Jira's custom-field admin screen; which screen shows it was not checked for this page.
• Not included. Worklogs, the changelog (history), issue properties, votes and watchers are not read; --fields cannot add them because they are expansions, not fields. If you need one, read_issue is the function to extend, and tell us what you needed.

Release notes, sprint reports, audits: --jql

--jql renders every issue a JQL query matches. The default is one document: a title, the count and the query, an issue table (key, summary, type, status, priority, assignee, resolved, plus --fields) whose last column is the page each issue starts on, then a section per issue on a new page with the same content as a single-issue PDF. The page numbers are not guessed: the table's links point at each section's anchor and the CSS the script sends uses target-counter(attr(href), page), which the renderer resolves at layout time; the test read the first page back and checked that the three numbers ascend and start at 2.

python3 papertype-jira.py --jql 'fixVersion = 2.4.0 ORDER BY key' --title "Release 2.4.0" release.pdf
#  release.pdf  5 page(s)
python3 papertype-jira.py --jql 'sprint in openSprints() AND project = PROJ' --table-only sprint.pdf      # the table alone
python3 papertype-jira.py --jql 'project = PROJ AND resolved >= -7d' --comments weekly.pdf              # sections with comments
python3 papertype-jira.py --jql 'project = PROJ AND resolved >= -7d' --separate --outdir pdfs             # one file per issue
#  3 issue(s) match
#  pdfs/PROJ-121-Checkout-fails-with-Apple-Pay.pdf  2 page(s)
#  …

What the reference says about the search endpoint, and what the script does with it: the query goes to GET /rest/api/3/search/jql (the older /rest/api/3/search is marked "currently being removed"); the JQL must be bounded, "a query with a search restriction" (assignee = currentUser() ORDER BY key yes, ORDER BY key alone no); fields defaults to id only, so the script names every field it needs; pages come back with nextPageToken and isLast, the token "will expire in 7 days" and is absent on the last page; maxResults is "max 5000" but "API may return fewer items per page where a large number of fields or properties are requested", so the script asks for 100 and follows the token until isLast. --separate searches for keys only and then reads each issue in full (comments included); --comments on the combined document fetches each issue's comments, one request per issue. A 400 from Jira for an invalid or unbounded query surfaces as Jira 400 on GET /rest/api/3/search/jql: <Jira's errorMessages>.

Images and attachments

The renderer never fetches from the web, so every image has to travel inside the request. The script inlines images that live on your Jira site as data: URIs: an <img> in the rendered description or a comment whose src is site-relative or on the site's host is fetched with your token (attachment URLs get ?redirect=false so the bytes come back directly), and image attachments from the issue's attachment list are fetched the same way and shown under the table. The budget is 1.2 MB of image bytes per document, which is about 1.6 MB as base64 and leaves room under the 2 MB request limit; past it, and for any image on another host (for example api.media.atlassian.com, which needs its own token), the image becomes a link labelled [image: name] and the script prints how many it linked. --no-images links all of them and makes no attachment requests at all. Non-image attachments are listed, never fetched.

What was not observed first-hand: the exact HTML Jira's renderer emits around an attached image (the OpenAPI document gives the attachment object, not the rendered markup; the script handles a plain <img src> with a site-relative or site-absolute URL, wrapped in anything) and whether renderedFields is populated for a custom ADF field (the ADF fallback covers the case it is not). If either differs on your site, the symptom is an image shown as a link or a field printed as plain text, not a failed render; tell support@papertype.dev and the page gets fixed.

Limits that matter

• Jira rate limits (rate-limiting page, 2026-10-25): a points-based model where "each request starts with a base cost of 1 point" and heavier operations cost more; over the limit "Jira returns an HTTP 429 Too Many Requests response" and asks clients to respect Retry-After. The script waits for Retry-After (else 10 s) and retries three times. One issue costs 2 requests plus one per 100 comments plus one per inlined image; a --jql document costs one search page per 100 issues plus the images, or plus one comments request per issue with --comments.
• Our quota. Free-plan output carries a small papertype.dev footer mark. Paid plans (from $9/month) do not. The free plan is 50 documents a month and the API returns 429 at the limit; a nightly --separate over 60 issues needs the $9 plan (500 documents). A combined --jql document is one document however many issues it holds. Failed renders are not counted.
• 2 MB of source per request, 300 pages per document, 2 concurrent renders per account. Images are the only thing that approaches the 2 MB request limit, hence the 1.2 MB image budget; a long issue's text is kilobytes.
• Errors. Jira errors surface as Jira <status> on GET <path>: <errorMessages> using the errorMessages and errors of Jira's error body (an unknown key gives "Issue does not exist or you do not have permission to see it.", as the test checked); a 401 with an empty body says to check JIRA_EMAIL and the token. Ours surface as PaperType <status>: <detail>; a bad key gives PaperType 401: Missing or invalid API key.
• What is stored, and where the token goes. With the default output the PDF is the response and nothing is kept on our side. With --url the finished PDF (never the issue data as text) is kept at a public, unguessable link for 24 hours, as the privacy policy describes. The Atlassian token is sent only to your Jira site (or api.atlassian.com for a scoped token); what reaches us is the HTML the script built, over TLS, inlined images included. The script never writes to Jira, so a read-only scope is enough.
• Fonts. Installed fonts: DejaVu, Liberation, Noto, Carlito and Caladea. Embed any other font with an @font-face rule whose src is a data: URI.

Related

• Turn a HubSpot deal into a PDF: a deal summary, or an invoice from its line items (Python script)
• Export a Coda page or a whole doc to PDF with the API (Python script)
• Generate a PDF in GitHub Actions
• HTML to PDF API
• Email a PDF for every form submission

All guides