Scaffolding REST API

Overview

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, refer to Scaffolding REST API Code Examples.

Authentication

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

On this page:

1 Overview
2 Authentication
3 GET method
- 3.1 Retrieve the Scaffolding structure
  - 3.1.1 Response
- 3.2 Retrieve Scaffolding data
  - 3.2.1 Response
- 3.3 Endpoint parameters
4 PUT method
- 4.1 Endpoint parameters
5 Parameters
6 Option parameters
7 Code examples
8 Support terms and conditions
9 Questions? Feedback?

On this page:

1 Overview
2 Authentication
3 GET method
- 3.1 Retrieve the Scaffolding structure
  - 3.1.1 Response
- 3.2 Retrieve Scaffolding data
  - 3.2.1 Response
- 3.3 Endpoint parameters
4 PUT method
- 4.1 Endpoint parameters
5 Parameters
6 Option parameters
7 Code examples
8 Support terms and conditions
9 Questions? Feedback?

GET method

Retrieve 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 page ID endpoint parameter.

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

A successful basic request returns the following response.

Response

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

Retrieve Scaffolding data

The following endpoint retrieves scaffolding data from a page using a pageid parameter.

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

A successful request returns a response similar to the following.

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

key	required	value
`pageid`	yes	The page ID of a Confluence page. For details, refer to the Confluence documentation.

PUT method

Using the PUT method, the Scaffolding REST API is able to import Scaffolding data.

View the Parameters section later on this page to see what macros are supported.

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

key	required	value
`pageid`	yes	The page ID of a Confluence page. For details, refer to the Confluence documentation.

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, the row number key starts from 0 and can be any positive integer.

Parameters

Macro (required)	Name (required)	Value (required)

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` For version 8.22.0 and later, Date Data saves the date and time as the authenticated user's timezone.
`Number Data`	user-defined	Number
`List Data`	user-defined	Array of strings (see the Options parameter table later on this page)
`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	An array of parameters

Option parameters

Option	Value (required)

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 and conditions

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

Questions? Feedback?

Contact our support team.