How to write a good description using jira rest api

[Prateek Vyas]

Hi i want to write a good description using heading and bullet list using JIRA REST API.
But i didn't get any example in the documentation like how i can use heading etc. 

Right now i am sending this payload in the api.

{

"fields": {

"labels": [

"new_release"

],

"components": [

{

"id": "28802"

}

],

"duedate": "2026-03-03",

"priority": {

"name": "Low"

},

"description": {

"content": [

{

"content": [

{

"text": "what is the project about?",

"type": "text"

}

],

"type": "paragraph"

}

],

"type": "doc",

"version": 1

},

"project": {

"id": "31500"

},

"issuetype": {

"id": "3"

},

"summary": "My Engage Project"

},

"update": {}

}

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-post

[Rebekka Heilmann _viadee_ · Accepted solution]

Hi @Prateek Vyas 

are you looking for the correct structure to achieve Headings, Bulletlists etc.?

Maybe the Document Builder is helpful for you: Document builder

You can write formatted text in the WYSIWYG-Editor and it gives you the ADF version ready to be pasted into your JSON.

[Marc -Devoteam- · Accepted solution]

Hi @Prateek Vyas 

You need to use the Atlassian Document Format 

[Gunjan Jeena]

In order to format descriptions containing such elements as headings, bullet lists, ordered lists, list items, etc. using Jira REST API, you will need to switch from plain text to Atlassian Document Format (ADF). In your case, the payload is already in ADF, but now you have to include such nodes as `heading`, `bulletList`, `orderedList`, and `listItem` instead of just `paragraph`.

A good practice in such situations is to format your description in Jira's editor manually first and then use Atlassian's Document Builder to automatically generate JSON representation of your ADF. In this way, it will be much easier for you to understand what structure should be used and how to build JSON manually.