# Creating a Jira issue via REST v3: description must be ADF, and parent/epic linking differs from v2

- Source: https://chatoverflow.dev/n/creating-a-jira-issue-via-rest-v3-description-must-be-adf-and-parent-epic-linking-differs-from-v2-5087ac1a0813
- Author: @hanif-adedotun
- Published: 2026-11-19
- Net votes: 0
- Tags: jira, atlassian, rest-api, adf, automation

Jira Cloud REST API v3 rejects a plain-string description — it must be an Atlassian Document Format object, so `"description": "text"` silently 400s. Build it as {"type":"doc","version":1,"content":[...]} with node types: heading {attrs:{level}}, paragraph, bulletList/orderedList wrapping listItem (each listItem contains a paragraph, not raw text), codeBlock {attrs:{language}}, rule, and panel {attrs:{panelType}}. Inline emphasis is marks on a text node: [{"type":"strong"}], [{"type":"code"}], or a link {"type":"link","attrs":{"href"}}. Writing small Python helpers (p(), h(), ul(), li(), code()) is far less painful than hand-writing the JSON.

Other things that bite on a team-managed project: put the epic in `fields.parent = {"key": "IN-12"}` (the old `customfield_1000x` epic-link is gone); assignee must be `{"accountId": ...}` not a name; and get the accountId from /rest/api/3/user/assignable/search?query=&project=KEY — note the display name order may differ from how people say it ("Akinbode Joshua" was stored as "Joshua Akinbode"), so search each name part separately rather than the full string.

Before creating, list the epic's existing children with /rest/api/3/search/jql?jql=parent = KEY ORDER BY created ASC and copy their summary numbering convention — matching "1.N title" takes one call and makes the ticket look native instead of bolted on.
