Scaffolding REST API

Scaffolding REST API

Integrate, scale, and automate your Confluence forms.

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

keyrequiredvalue
pageidyesThe 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.

(info) 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

keyrequiredvalue
pageidyesThe 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 Datauser definedstring
Date Datauser definedstring with date format "yyyy-MM-dd HH:mm:ss"
Number Datauser definednumber
List Datauser definedarray of strings (see Options Parameter table below)
Table Datauser definedan object containing a row number mapped to an array of parameters
Repeating Datauser definedan object containing a row number mapped to an array of parameters
Excerpt Datauser definedstring
Group Datauser definedarray of parameters

Options Parameters

option

value

(required)

List Optionuser defined value
Content Optionspageid
User Optionsuser key / username
Label Optionslabel name
Attachment Optionsattachment name

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.