Endpoint Documentation

HTTP REST API

The REST API documentation describes the usage of the Download Feature to download configs directly from Confluence in your automated provisioning scripts with e.g. curl or wget. All Endpoints can only be accessed by an authenticated Confluence User that has the Page View Permission of the page the codebox is embedded in. Authentication can be done via Basic Auth and since Confluence 7.9 with Personal Access Tokens.

Download the codeblock or raw template

The Endpoint let's you download a specific codeblock as plain text.

GET /rest/advancedcodeblocks/1/download_code/plain_text

Note: API Changes since App version 3.4.0. Please read api changes below if you used a previous version of the app.

Request Parameter

key string	A code to identify the actual codeblock of the codebox. It is the BASE64 encoded version of the section name. Use `cmF3` to download the raw template. Example: `dGVzdHN5c3RlbSAx`
macroId int	An unique ID generated by Confluence for the macro. Example: `1213344`
contentId int	The ID of the Confluence Page, BlogPost or Comment the macro is embedded in. Example: `234324`
asciiOnly boolean	Optional. Set this to 'true' if you want to have all non-ASCII chars removed from the response body. This will retain ASCII and `[öäüß]`. Example: `true`

Request Example

Example 1: Basic Auth

curl https://my.confluence/rest/advancedcodeblocks/1/download_code/plain_text \
-G -u admin:admin \
-d key=cmF3 \
-d macroId=95b26f2e-4768-4e66-952e-37a8b56bcac1 \
-d contentId=1703938

Example 2: Personal Access Token (Confluence 7.9+)

curl https://my.confluence/rest/advancedcodeblocks/1/download_code/plain_text \
-G -H "Authorization: Bearer MyToken" \
-d key=cmF3 \
-d macroId=95b26f2e-4768-4e66-952e-37a8b56bcac1 \
-d contentId=1703938

Response Codes

200 OK	Download possible Response Body will contain the codeblock as plain text.
401 Unauthorized	Unauthorized Not logged in to Confluence. (Please keep in mind that you will need to use a captcha once your authentication attemps fail to often)
403 Forbidden	Forbidden You do not have the view page permission right on the Confluence Page in which the macro is embedded.
500 Internal error	Internal error Wrong URL-parameters, Confluence page does not exist any more or any other error. Confluence logs the exeption to the logfile.

Response Body

Encoding	UTF-8
Content-Type	text/plain

Response Body Example

<VirtualHost *:80>
  DocumentRoot /var/www/server1
  ServerName www.server1.com
</VirtualHost>

API Changes

From v3.x to v4.0

REMOVED:   GET /plugins/servlet/advanced-codeblock-macro-downloadcode
NEW:       GET /rest/advancedcodeblocks/1/download_code/plain_text

 Changed Request Parameters:
     pageId  ==> contentId

The old servlet that has been deprecated in earlier versions is now fully removed.
Some URL parameters have changed.

From v3.3 to v3.4

DEPRECATED: GET /plugins/servlet/advanced-codeblock-macro-downloadcode
NEW:        GET /rest/advancedcodeblocks/1/download_code/plain_text

 Changed Request Parameters:
     pagepropertykey ==> key
     macroid         ==> macroId
     pageid          ==> pageId
     asciionly       ==> asciiOnly

If you call the old URL you will be redirected to the new URL by a HTTP 301 redirect.

Download xml list

The Endpoint lists all download links for one specific codebox as XML.

GET /rest/advancedcodeblocks/1/download_list/xml

Note: API Changes since App version 3.4.0. Please read api changes below if you used a previous version of the app.

Request Parameter

macroId int	An unique ID generated by Confluence for the macro. Example: `1213344`
contentId int	The ID of the Confluence Page, BlogPost or Comment the macro is embedded in. Example: `234324`

Request Example

Example 1: Basic Auth

curl https://my.confluence/rest/advancedcodeblocks/1/download_list/xml \
-G -u admin:admin \
-d macroId=b77502b0-1dc4-4227-8c11-b03d9f581507 \
-d contentId=360457 \

Example 2: Personal Access Token (Confluence 7.9+)

curl https://my.confluence/rest/advancedcodeblocks/1/download_list/xml \
-G -H "Authorization: Bearer MyToken" \
-d macroId=b77502b0-1dc4-4227-8c11-b03d9f581507 \
-d contentId=360457 \

Response Codes

200 OK	Download possible Response Body will contain the downloadlist as XML. <advancedCodeblockMacro> <!-- See full example below --> </advancedCodeblockMacro>
401 Unauthorized	Unauthorized Not logged in to Confluence. (Please keep in mind that you will need to use a captcha once your authentication attemps fail to often) <advancedCodeblockMacro> <error>401_UNAUTHORIZED</error> <message>no logged in user found</message> </advancedCodeblockMacro> From v5.0.0 on it will be the following, since we delegate auth fully to Confluence: <status> <status-code>401</status-code> <message>Client must be authenticated to access this resource.</message> </status>
403 Forbidden	Forbidden You do not have the view page permission right on the Confluence Page in which the macro is embedded. <advancedCodeblockMacro> <error>403_FORBIDDEN</error> <message>no read permission on page with id 1234</message> </advancedCodeblockMacro>
500 Internal error	Internal error Wrong URL-parameters, Confluence page does not exist any more or any other error. Confluence logs the exeption to the logfile. <advancedCodeblockMacro> <error>500_ERROR</error> <message>Did you provide valid URL-Parameters?</message> <extraMessage>more details ...</extraMessage> </advancedCodeblockMacro> See all error keys apart from `500_ERROR` 500_ERROR_CHUNKED_READ_EXCEPTION 500_ERROR_LICENSE_EXCEPTION 500_ERROR_IO_EXCEPTION 500_ERROR_INVALID_MACRO_BODY_EXCEPTION 500_ERROR_MALFORMED_URL_EXCEPTION 500_ERROR_HTTP_EXCEPTION 500_ERROR_EMPTY_MACRO_BODY_EXCEPTION 500_ERROR_OUTBOUND_ALLOWLIST_URL_NOT_ALLOWED_EXCEPTION 500_ERROR_FETCH_MACRO_EXCEPTION 500_ERROR_INVALID_URL_PARAMETER_EXCEPTION 500_ERROR_MACRO_BODY_PROCESSING_EXCEPTION

Response Body

Encoding	UTF-8
Content-Type	application/xml

Response Body Example

The first codeblock is for [testsystem 1]
The second codeblock is for [testsystem 2]
The third codeblock is for [raw]

<advancedCodeblockMacro>
 <page>
   <contentId>360457</contentId>
   <contentTitle>Testpage</contentTitle>
   <contentType>page</contentType>
   <spaceKey>TEST</spaceKey>
   <macroId>b77502b0-1dc4-4227-8c11-b03d9f581507</macroId>
 </page>
 <codeBlocks>
  <codeBlock> 
   <key>dGVzdHN5c3RlbSAx</key>
   <name>testsystem 1</name>
   <download>http://localhost:8090/plugins/servlet/advanced-codeblock-macro-downloadcode?key=dGVzdHN5c3RlbSAx&amp;pageId=360457&amp;macroId=b77502b0-1dc4-4227-8c11-b03d9f581507</download>
  </codeBlock>
  <codeBlock> 
   <key>dGVzdHN5c3RlbSAy</key>
   <name>testsystem 2</name>
   <download>http://localhost:8090/plugins/servlet/advanced-codeblock-macro-downloadcode?key=dGVzdHN5c3RlbSAy&amp;pageId=360457&amp;macroId=b77502b0-1dc4-4227-8c11-b03d9f581507</download>
  </codeBlock>
  <codeBlock> 
   <key>cmF3</key>
   <name>raw</name>
   <download>http://localhost:8090/plugins/servlet/advanced-codeblock-macro-downloadcode?key=cmF3&amp;pageId=360457&amp;macroId=b77502b0-1dc4-4227-8c11-b03d9f581507</download>
  </codeBlock>
 </codeBlocks>
</advancedCodeblockMacro>

API Changes

From v3.x to v4.0

REMOVED:   GET /plugins/servlet/advanced-codeblock-macro-downloadlist
NEW:       GET /rest/advancedcodeblocks/1/download_list/xml

 Changed Request Parameters:
     pageId  ==> contentId

 Changed Response Body from "page" to "content":
   <page>                        ― CHANGE    ➞ <content>  
     <pageId>123</pageId>        ― CHANGE    ➞   <contentId>123</contentId>
     <pageName>Bar</pageName>    ― CHANGE    ➞   <contentTitle>Bar</contentTitle>
     <spaceKey>FOO</pageId>      ― unchanged ➞   <spaceKey>FOO</spaceKey>
     <macroId>aa-bb-cc</macroId> ― unchanged ➞   <macroId>aa-bb-cc</macroId>
                                 ― NEW       ➞   <contentType>page</contentType>

 Added extraMessage property to error Response Body:
      <advancedCodeblockMacro>
        <error>500_ERROR</error>
        <message>Did you provide valid URL-Parameters?</message>
        <extraMessage>more details ...</extraMessage> <!-- NEW -->
      </advancedCodeblockMacro>

The old servlet that has been deprecated in earlier versions is now fully removed.
Some URL parameters and the response body have changed.

From v3.3 to v3.4

DEPRECATED: GET /plugins/servlet/advanced-codeblock-macro-downloadlist
NEW:        GET /rest/advancedcodeblocks/1/download_list/xml

 Changed Request Parameters:
     macroid         ==> macroId
     pageid          ==> pageId

If you call the old URL you will be redirected to the new URL by a HTTP 301 redirect.

Download json list

The Endpoint lists all download links for one specific codebox as JSON.

GET /rest/advancedcodeblocks/1/download_list/json

Note: Introduced with App version 3.4.0. This Endpoint does not exist in previous versions.

Request Parameter

macroId int	An unique ID generated by Confluence for the macro. Example: `1213344`
contentId int	The ID of the Confluence Page, BlogPost or Comment the macro is embedded in. Example: `234324`

Request Example

Example 1: Basic Auth

curl https://my.confluence/rest/advancedcodeblocks/1/download_list/json \
-G -u admin:admin \
-d macroId=b77502b0-1dc4-4227-8c11-b03d9f581507 \
-d contentId=360457 \

Example 2: Personal Access Token (Confluence 7.9+)

curl https://my.confluence/rest/advancedcodeblocks/1/download_list/json \
-G -H "Authorization: Bearer MyToken" \
-d macroId=b77502b0-1dc4-4227-8c11-b03d9f581507 \
-d contentId=360457 \

Response Codes

200 OK	Download possible Response Body will contain the downloadlist as JSON. { "...": "See full example below" }
401 Unauthorized	Unauthorized Not logged in to Confluence. (Please keep in mind that you will need to use a captcha once your authentication attemps fail to often) { "error": "401_UNAUTHORIZED", "message": "no logged in user found" } From v5.0.0 on it will be the following, since we delegate auth fully to Confluence: { "message": "Client must be authenticated to access this resource.", "status-code": 401 }
403 Forbidden	Forbidden You do not have the view page permission right on the Confluence Page in which the macro is embedded. { "error": "403_FORBIDDEN", "message": "no read permission on page with id 1234" }
500 Internal error	Internal error Wrong URL-parameters, Confluence page does not exist any more or any other error. Confluence logs the exeption to the logfile. { "error": "500_ERROR", "message": "Did you provide valid URL-Parameters?", "extraMessage": "more details ...." } See all error keys apart from `500_ERROR` 500_ERROR_CHUNKED_READ_EXCEPTION 500_ERROR_LICENSE_EXCEPTION 500_ERROR_IO_EXCEPTION 500_ERROR_INVALID_MACRO_BODY_EXCEPTION 500_ERROR_MALFORMED_URL_EXCEPTION 500_ERROR_HTTP_EXCEPTION 500_ERROR_EMPTY_MACRO_BODY_EXCEPTION 500_ERROR_OUTBOUND_ALLOWLIST_URL_NOT_ALLOWED_EXCEPTION 500_ERROR_FETCH_MACRO_EXCEPTION 500_ERROR_INVALID_URL_PARAMETER_EXCEPTION 500_ERROR_MACRO_BODY_PROCESSING_EXCEPTION

Response Body

Encoding	UTF-8
Content-Type	application/json

Response Body Example

The first codeblock is for [testsystem 1]
The second codeblock is for [testsystem 2]
The third codeblock is for [raw]

{
  "content": {
    "contentId": 360457,
    "contentTitle": "Testpage",
    "contentType": "page",
    "spaceKey": "TEST",
    "macroId": "b77502b0-1dc4-4227-8c11-b03d9f581507"
  },
  "codeBlocks": [ 
    {
      "key": "dGVzdHN5c3RlbSAx", 
      "name": "testsystem 1",
      "download": "http://localhost:8090/rest/advancedcodeblocks/1/code?key=dGVzdHN5c3RlbSAx&pageId=360457&macroId=b77502b0-1dc4-4227-8c11-b03d9f581507"
    },
    {
      "key": "dGVzdHN5c3RlbSAy", 
      "name": "testsystem 2",
      "download": "http://localhost:8090/rest/advancedcodeblocks/1/code?key=dGVzdHN5c3RlbSAyb2p1aWh6dXRpb2ppODc2Z2hvacOkw7bDtmtsamo=&pageId=360457&macroId=b77502b0-1dc4-4227-8c11-b03d9f581507"
    },
    {
      "key": "cmF3", 
      "name": "raw",
      "download": "http://localhost:8090/rest/advancedcodeblocks/1/code?key=cmF3&pageId=360457&macroId=b77502b0-1dc4-4227-8c11-b03d9f581507"
    }
  ]
}

API Changes

From v3.x to v4.0

URL:       GET /rest/advancedcodeblocks/1/download_list/json

 Changed Request Parameters:
     pageId  ==> contentId

 Changed Response Body from "page" to "content":
    "page": {                 ― CHANGE    ➞  "content": {
      "pageId": 360457,       ― CHANGE    ➞    "contentId": 360457,
      "pageName": "Testpage", ― CHANGE    ➞    "contentTitle": "Testpage",
      "spaceKey": "TEST",     ― unchanged ➞    "spaceKey": "TEST",
      "macroId": "aa-bb-cc"   ― unchanged ➞    "macroId": "aa-bb-cc",  
                              ― NEW       ➞    "contentType": "page"

 Added extraMessage property to error Response Body:
          {
            "error": "500_ERROR",
            "message": "Did you provide valid URL-Parameters?",
            "extraMessage": "more details ... NEW NEW"
          }

Some URL parameters and the response body have changed.

From v3.3 to v3.4

NEW:        GET /rest/advancedcodeblocks/1/download_list/json

The Endpoint is newly introduced in this version

User Guide - Previous

Advanced Codeblocks Single

Support

Endpoint Documentation

HTTP REST API

Download the codeblock or raw template

Request Parameter

Request Example

Response Codes

Response Body

Response Body Example

API Changes

Download xml list

Request Parameter

Request Example

Response Codes

Response Body

Response Body Example

API Changes

Download json list

Request Parameter

Request Example

Response Codes

Response Body

Response Body Example

API Changes

Advanced Codeblocksfor Confluence

Advanced Codeblocks
for Confluence