/
Tutorial - Create a page in Confluence with requirements using REST API

Tutorial - Create a page in Confluence with requirements using REST API

This tutorial explains how to create requirements using Confluence API.

Long story short, you just need to create a page through Confluence’s native API, with the requirement macro in it. Requirement Yogi will work its magic and automatically index the page (We’re wired on the creation/update events).

No call to Requirement Yogi is necessary.

Pre-Requisites

Generate a token in your Confluence Profile

  1. Connect to your Confluence

  2. Click on your profile image > Profile

  3. In tab Settings, access Personal Access Tokens

  4. Create token

  5. Keep the token for later

Determine your confluence base URL

URL may look like

http://{hostname}:{port}/confluence/display/spacekey/pagename

⇒ The base URL is http://{hostname}:{port}/confluence

Create a page with a requirement macro

You must have the permission to create a page in the space

TLDR: CURL of an example request

curl --location 'http://c8.5.8.local:2001/confluence/rest/api/content' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ...' \ --header 'Cookie: JSESSIONID=...' \ --data '{ "type": "page", "title": "Rest api creating my requirements", "space": { "key": "Yogi" }, "body": { "storage": { "value": "<table class='\''wrapped'\''><colgroup><col /><col /><col /><col /><col /></colgroup><tbody><tr><th scope='\''col'\''>Key</th><th scope='\''col'\''>Description</th><th scope='\''col'\''>Status</th><th scope='\''col'\''>Links to other requirements in other space or not</th><th scope='\''col'\''>Links to JIRA</th></tr><tr><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''type'\''>DEFINITION</ac:parameter><ac:parameter ac:name='\''key'\''>REST-001</ac:parameter></ac:structured-macro></p></div></td><td>Requirement description for rest api 001</td><td>In Progress</td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\''><ac:parameter ac:name='\''spaceKey'\''>BULK</ac:parameter><ac:parameter ac:name='\''freetext'\''>Link</ac:parameter><ac:parameter ac:name='\''type'\''>LINK</ac:parameter><ac:parameter ac:name='\''key'\''>SYD-1988</ac:parameter></ac:structured-macro></p></div></td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''jira'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''server'\''>Jira</ac:parameter><ac:parameter ac:name='\''serverId'\''>93399b7f-4f2b-3b2a-a949-275c7925e37c</ac:parameter><ac:parameter ac:name='\''key'\''>YOGI-10</ac:parameter></ac:structured-macro></p></div></td></tr><tr><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''type'\''>DEFINITION</ac:parameter><ac:parameter ac:name='\''key'\''>REST-002</ac:parameter></ac:structured-macro></p></div></td><td>N/A</td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''status'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''colour'\''>Green</ac:parameter><ac:parameter ac:name='\''title'\''>Done</ac:parameter></ac:structured-macro></p></div></td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''freetext'\''>Link</ac:parameter><ac:parameter ac:name='\''type'\''>LINK</ac:parameter><ac:parameter ac:name='\''key'\''>MDK_SYS_LH_1</ac:parameter></ac:structured-macro></p></div></td><td><div class='\''content-wrapper'\''><p><br /></p></div></td></tr><tr><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''type'\''>DEFINITION</ac:parameter><ac:parameter ac:name='\''key'\''>REST-003</ac:parameter></ac:structured-macro></p></div></td><td><br /></td><td><br /></td><td><br /></td><td><br /></td></tr></tbody></table>", "representation": "storage" } } } '
<table> <tbody> <tr> <th>Key</th> <th>Description</th> <th>Status</th> <th>Links to other requirements in other space or not</th> <th>Links to JIRA</th> </tr> <tr> <td> <div> <p> <ac:structured-macro ac:name='requirement'> <ac:parameter ac:name='type'>DEFINITION</ac:parameter> <ac:parameter ac:name='key'>REST-001</ac:parameter> </ac:structured-macro> </p> </div> </td> <td>Requirement description for rest api 001</td> <td> <div class='content-wrapper'> <p> <ac:structured-macro ac:name='status'> <ac:parameter ac:name='colour'>Green</ac:parameter> <ac:parameter ac:name='title'>Done</ac:parameter> </ac:structured-macro> </p> </div> </td> <td> <div> <p> <ac:structured-macro ac:name='requirement'> <ac:parameter ac:name='spaceKey'>BULK</ac:parameter> <ac:parameter ac:name='freetext'>Link</ac:parameter> <ac:parameter ac:name='type'>LINK</ac:parameter> <ac:parameter ac:name='key'>SYD-1988</ac:parameter> </ac:structured-macro> </p> </div> </td> <td> <div> <p> <ac:structured-macro ac:name='jira'> <ac:parameter ac:name='server'>Jira</ac:parameter> <ac:parameter ac:name='serverId'>93399b7f-4f2b-3b2a-a949-275c7925e37c</ac:parameter> <ac:parameter ac:name='key'>YOGI-10</ac:parameter> </ac:structured-macro> </p> </div> </td> </tr> </tbody> </table>
image-20250402-095234.png
Created page

Check the requirement is created

…using Requirement Yogi’s REST API:

The URL is:

{your base URL}/rest/reqs/1/requirement2/spacekey?expand=all&q=page=pageid

For example:

curl --location --request GET 'http://c8.5.8.local:2001/confluence/rest/reqs/1/requirement2/Yogi?expand=all&q=page=7733267' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ...' \ --header 'Cookie: JSESSIONID=...'

Returns:

{ "count": 400, "expandable": "properties.propertyNameMeta,validations,all", "explanation": "Requirements defined on page 360482 and with status 'ACTIVE'", "limit": 600, "offset": 0, "results": [{ "key": "REST-001", "destinationUrl": "http://c9.4.0.local:2013/c-app/spaces/TEAM/pages/360482/Page+-+ACT-1201#req-REST-001", "genericUrl": "/requirements/Yogi/REST-001", "htmlExcerpt": "RNs", "htmlNeedsUpdating": false, "id": 695, "isPublicDescription": false, "issues": [], "origin": { "pageId": 360482, "title": "Page - ACT-1201", "type": "page", "url": "http://c9.4.0.local:2013/c-app/spaces/TEAM/pages/360482/Page+-+ACT-1201#req-ACT-1000" }, "properties": [{ "key": "Description", "dataType": "STRING", "type": "INLINE", "value": "RNs" }, { "key": "Property1", "dataType": "STRING", "type": "INLINE", "value": "Value 1" }], "spaceKey": "TEAM", "status": "ACTIVE" }, ... ] }

Full documentation

See also: https://developer.atlassian.com/server/confluence/rest/v923/intro/

  1. Method: POST

  2. Endpoint

{your base URL}/rest/api/content

  1. Headers

Key

Value

Key

Value

Authorization

Bearer {token}

Content-Type

application/json

  1. Body

{ "type": "page", "title": "{Page title}", "space": { "key": "{Space key}" }, "body": { "storage": { "value": "{Storage format}", "representation": "storage" } } }

{Storage format} can be extracted from Confluence page in Storage format

Edit a page with a requirement macro

Get the page content by ID

  1. Method: GET

  2. Endpoint {your base URL}/rest/api/content/{page ID}

  3. Headers

Key

Value

Key

Value

Authorization

Bearer {token}

⇒ Find the field "number": XX, you will need to increment that number to update the page

Example

As opposed to the other curl above which creates a page, this one edits the page, so there is a version number and no space key

curl --location --request PUT 'http://c8.5.8.local:2001/confluence/rest/api/content/7733267' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ...' \ --header 'Cookie: JSESSIONID=...' \ --data '{ "version":{ "number": {XX + 1} }, "type": "page", "title": "Rest api creating my requirements but with an updated name", "body": { "storage": { "value": "<table class='\''wrapped'\''><colgroup><col /><col /><col /><col /><col /></colgroup><tbody><tr><th scope='\''col'\''>Key</th><th scope='\''col'\''>Description</th><th scope='\''col'\''>Status</th><th scope='\''col'\''>Links to other requirements in other space or not</th><th scope='\''col'\''>Links to JIRA</th></tr><tr><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''type'\''>DEFINITION</ac:parameter><ac:parameter ac:name='\''key'\''>REST-001</ac:parameter></ac:structured-macro></p></div></td><td>Requirement description for rest api 001</td><td>In Progress</td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\''><ac:parameter ac:name='\''spaceKey'\''>BULK</ac:parameter><ac:parameter ac:name='\''freetext'\''>Link</ac:parameter><ac:parameter ac:name='\''type'\''>LINK</ac:parameter><ac:parameter ac:name='\''key'\''>SYD-1988</ac:parameter></ac:structured-macro></p></div></td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''jira'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''server'\''>Jira</ac:parameter><ac:parameter ac:name='\''serverId'\''>93399b7f-4f2b-3b2a-a949-275c7925e37c</ac:parameter><ac:parameter ac:name='\''key'\''>YOGI-10</ac:parameter></ac:structured-macro></p></div></td></tr><tr><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''type'\''>DEFINITION</ac:parameter><ac:parameter ac:name='\''key'\''>REST-002</ac:parameter></ac:structured-macro></p></div></td><td>N/A</td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''status'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''colour'\''>Green</ac:parameter><ac:parameter ac:name='\''title'\''>Done</ac:parameter></ac:structured-macro></p></div></td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''freetext'\''>Link</ac:parameter><ac:parameter ac:name='\''type'\''>LINK</ac:parameter><ac:parameter ac:name='\''key'\''>MDK_SYS_LH_1</ac:parameter></ac:structured-macro></p></div></td><td><div class='\''content-wrapper'\''><p><br /></p></div></td></tr><tr><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''type'\''>DEFINITION</ac:parameter><ac:parameter ac:name='\''key'\''>REST-003</ac:parameter></ac:structured-macro></p></div></td><td><br /></td><td><br /></td><td><br /></td><td><br /></td></tr></tbody></table>", "representation": "storage" } } } '

References

Confluence Data Center REST API Documentation

https://developer.atlassian.com/server/confluence/rest/v923/intro/

Requirement Yogi REST API Documentation

REST API (Data Center)