Scaffolding REST API

Introduced in Scaffolding version 8.10.0, the Scaffolding REST API uses JSON and provides access to the schema of a page's form that can be used to write content into that form.

For code examples, visit our Scaffolding REST API Code Examples page.

Authentication

The Scaffolding REST API uses the same authentication as the Confluence API authentication. For more information, consult the Atlassian Developers documentation.

GET Method

Retrieving the Scaffolding Structure

Using the GET method, the Scaffolding REST API is able to return the structure of a Scaffolding page when requested with the Confluence pageid endpoint parameter.

{CONFLUENCE-BASE-URL}/rest/scaffolding/1.0/api/form/meta/{pageid}

A successful basic request will return:

Response

[
  {
    "macro": "text-data",
    "macroId": "ca6bab92-2039-4847-b85b-8c0a2ca7820c",
    "minLength": null,
    "name": "name",
    "pattern": null,
    "language": null,
    "content": null,
    "required": null,
    "maxLength": null
  }
]

Retrieving Scaffolding Data

The following endpoint is used to retrieve Scaffolding data from a page with a pageid parameter.

{CONFLUENCE-BASE-URL}/rest/scaffolding/1.0/api/form/{pageid}

A successful request will return something like this:

Response

[
  {
    "macro": "text-data",
    "name": "text data field",
    "value": "<strong>Hello world</strong>"
  },
  {
    "macro": "number-data",
    "name": "number data field",
    "value": 2
  },
  {
    "macro": "date-data",
    "name": "date data field",
    "value": "2017-04-02 11:11:11"
  },
  {
    "macro": "list-data",
    "name": "list data field",
    "value": ["option 1"]
  },
{
    "macro": "attachment-data",
    "name": "attachmentData",
    "value": "picker.png"
  }
]

Endpoint Parameters

key	required	value
`pageid`	yes	The pageid of a Confluence page. Consult the Confluence documentation for more information.

PUT Method

Using the PUT method, the Scaffolding REST API is able to import Scaffolding data. View Parameters section below to see what macros are supported.

Take note that this method only works if there are existing Scaffolding macros with matching names on the page.

If the "value" parameter is not provided or is null, the API will assume the field value to be empty.

{CONFLUENCE-BASE-URL}/rest/scaffolding/1.0/api/form/{pageId}

Endpoint Parameters

key	required	value
`pageid`	yes	The pageid of a Confluence page. Consult the Confluence documentation for more information.

JSON example for text-data, number-data, date-data, list-data, attachment-data

[
  {
    "macro": "text-data",
    "name": "text data field",
    "value": "<strong>Hello world</strong>"
  },
  {
    "macro": "number-data",
    "name": "number data field",
    "value": 2
  },
  {
    "macro": "date-data",
    "name": "date data field",
    "value": "2017-04-02 11:11:11"
  },
  {
    "macro": "list-data",
    "name": "list data field",
    "value": ["option 1"]
  },
{
    "macro": "attachment-data",
    "name": "attachmentData",
    "value": "picker.png"
  }
]

JSON example for table-data and repeating-data

[
  {
    "name": "table",
    "macro": "table-data",
    "type": "looping",
    "value": {
      0 : [
        {
          "macro": "text-data",
    	  "name": "text data field",
          "value": "<strong>Hello world</strong>"
        }
      ],
      1 : [
        {
          "macro": "text-data",
    	  "name": "text data field",
          "value": "<strong>Hello world</strong>"
        }
      ]
    }
  },
  {
    "name": "repeat",
    "macro": "repeating-data",
    "value": {
      0 : [
        {
          "macro": "text-data",
    	  "name": "text data field",
          "value": "<strong>Hello world</strong>"
        }
      ],
      1 : [
        {
          "macro": "text-data",
    	  "name": "text data field",
          "value": "<strong>Hello world</strong>"
        }
      ]
    }
  }
]

JSON example for group-data

[
{
    "macro": "group-data",
    "name": "myGroup",
    "value": [
      {
        "macro": "text-data",
        "name": "justText",
        "value": "Name is in group data API"
      },
      {
        "macro": "number-data",
        "name": "age",
        "value": 12
      }
    ]
  }
]

For Table Data and Repeating Data, row number key starts from 0 and can be any positive integer.

Parameters

macro (required)	name (required)	value (required)
`Text Data`	user defined	string
`Date Data`	user defined	string with date format "`yyyy-MM-dd HH:mm:ss`" **Note: For version 8.22.0 and above, Date Data will save the date and time as the authenticated user's timezone
`Number Data`	user defined	number
`List Data`	user defined	array of strings (see Options Parameter table below)
`Table Data`	user defined	an object containing a row number mapped to an array of parameters
`Repeating Data`	user defined	an object containing a row number mapped to an array of parameters
`Excerpt Data`	user defined	string
`Group Data`	user defined	array of parameters

Options Parameters

option	value (required)
`List Option`	user defined value
`Content Options`	pageid
`User Options`	user key / username
`Label Options`	label name
`Attachment Options`	attachment name

Code Examples

Support Terms & Conditions

We provide support for the API itself (bug fixes and improvements) but do not provide support for implementation of the API and/or customization on your instance.

Got Feedback?

We would love to hear from you! Email your feedback to atlassian-addons@servicerocket.com.