REST API Usage and Examples

This page will provide you with some information to get started using the Scroll Versions REST API and provide instructions on how to automate publishing versions using the REST API.

REST URL Overview

All URLs must be prepended by the following base URL: <base-url>/rest/scroll-versions/1.0

All endpoints are using application/json as the content type for request and responses.

Authentication

Before starting to request URLs, you need to be aware of the different authentication methods. You can authenticate yourself for the REST APIs in three ways:

Log in to Confluence manually You will then be authenticated for the REST APIs for that same browser session.
Use HTTP basic authentication (Authorization HTTP header) containing 'Basic username:password'. username:password must be base64 encoded. The URL must also contain the 'os_authType=basic' query parameter.
Using URL parameters You may specify your username and password in the URL using the 'os_username' and 'os_password' parameters. See below for examples.

If you want to use some non-browser tool like wget or curl, you have to use either HTTP basic authentication or URL parameters.

If you encounter the problem "XSRF check failed" while accessing the REST API, you should add the header "X-Atlassian-Token:nocheck" to your request.

curl

Curl is a command line tool for transferring data with URL syntax. It is preinstalled on macOS and available for all Linux distributions using the package manager. There are also builds for Windows available.

You can use curl using the command line as follows. On macOS and Linux please make sure to place the URL in double quotes as otherwise the "&" character inside the URL will break the command.

HTTP basic authentication:

CODE

curl --remote-header-name --remote-name -u admin:admin "http://www.example.com/confluence/rest/scroll-versions/1.0/version/ds?os_authType=basic"

URL parameter based authentication:

CODE

curl --remote-header-name --remote-name "http://www.example.com/confluence/rest/scroll-versions/1.0/version/ds?os_username=admin&os_password=admin"

In some cases the colons are replaced with '&3A'. Please check the permalink carefully and edit it if necessary.

If you want to call curl from a script, the "-f" parameter may be interesting as it will make curl return some non-zero value in case of download errors. See the curl documentation for more info.

wget

wget is another command line tool for transferring data with URL syntax. It is available for all major platforms.

You can use wget using the command line as follows. On macOS and Linux please make sure to place the URL in double quotes as otherwise the "&" character inside the URL will break the command.

HTTP basic authentication:

CODE

wget --content-disposition --http-user=admin --http-password=admin "http://www.example.com/confluence/rest/scroll-version/1.0/version/ds?os_authType=basic"

URL parameter based authentication:

CODE

wget --content-disposition "http://www.example.com/confluence/rest/scroll-version/1.0/version/ds?os_username=admin&os_password=admin"

Other Tools

If you use other tools, you can compose the URL as described below.

HTTP basic authentication

CODE

[http://www.example.com/confluence/rest/scroll-version/1.0/version/ds?os_authType=basic]

URL parameter based authentication

CODE

[http://www.example.com/confluence/rest/scroll-version/1.0/version/ds?os_username=admin&os_password=admin]

Publish using the REST API

In the following, we'll have a look at the process for publishing a Scroll Version using Scroll Versions' REST API. This is useful if you want to automate the process and publish your content, e.g. daily. Here are the general steps we need to consider when publishing a version:

First, it's necessary to retrieve the Version information to get the ID of your desired Version.
You have to prepare your publish request. Optionally you can get a default request entity as a template and ask for a preview of the publish request.
After preparing the publish request, you're able to access the endpoint to publish this Version. As a response you will get an ID for the asynchronous task which has been started in the background.
Now you just have to wait for the result by pulling the Asynchronous Task endpoint a few times until it returns a positive result.

The following subchapters describe the steps in more detail and contains request and response examples.

Required resources

All the following URLs are under the path <base-url>/rest/scroll-versions/1.0

Method	URL	Description
GET	/versions/{spaceKey}	Returns an array of Version objects.
GET	/publish/{spaceKey}/{type}/new	Returns a default request entity object which can be used for further publishing requests.
POST	/publish/{spaceKey}/{type}/preview	Creates a preview of the publish request. Returns a reference to an asynchronous task.
POST	/publish/{spaceKey}/{type}/publish	Publishes the Version data based on the publish request. Returns a reference to an asynchronous task.
GET	/async-tasks/{taskId}	Returns status and result data for an asynchronous task.

Retrieve Version Information

Click here to expand...

GET /versions/{spaceKey}

This request will return an array of Version objects. Each Version contains an id, name, description and some other fields. You have to store the Version ID of your desired Version which you want to publish.

URL Parameter	Description	Default	Required
spaceKey	Key of the Confluence space, e.g. ds for "Demonstration Space", from where the Version should be retrieved.	-

Example Request

CODE

curl -H "Accept:application/json" "http://www.example.com/confluence/rest/scroll-versions/1.0/versions/VSN"

Example Response

CODE

[
    {
        "id": "C0A81281015668F1AE5D463C4F5DC0FD",
        "name": "1.0",
        "description": "Version for Release 1.0",
        "releaseDate": null,
        "precedingVersionId": null,
        "archived": false,
        "color": "#999999",
        "runtimeAccessible": false
    },
    {
        "id": "C0A812810156699DA0172F4218C867C7",
        "name": "2.0",
        "description": "Version for Release 2.0",
        "releaseDate": null,
        "precedingVersionId": "C0A81281015668F1AE5D463C4F5DC0FD",
        "archived": false,
        "color": "#999999",
        "runtimeAccessible": false
    }
]

Optional: Get a Default Request Entity

Click here to expand...

GET /publish/{spaceKey}/{type}/new

Retrieve a default request entity. The response can then be extended and used for further requests to the other publishing endpoints.

URL Parameter

Description

Default

Required

spaceKey

Key of the Confluence space, e.g. ds for "Documentation Space", from where the publish request should be initiated.

-

type

Type of the publish request. Allowed values:

to_same (the data will be published to the space, specified by spaceKey)
to_new (the data will be published to a new space, specified by the request entity)
to_existing (the data will be published to an existing space, specified by the request entity)

-

Example Request

CODE

curl -H "Accept:application/json" "http://www.example.com/confluence/rest/scroll-versions/1.0/publish/ds/to_new/new"

Example Response

The endpoint will automatically generate a targetSpaceKey and targetSpaceName for you. The versionId has the value "current" by default, but you should change it to an existing Version ID which you have retrieved in the first step.

CODE

{
    "versionId": "current",
    "targetSpaceKey": "ds10",
    "targetSpaceName": "Demonstration Space 1.0",
    "treeProviderName": "",
    "languageKey": "all",
    "copyLabels": false,
    "keepAuthorsAndDates": false,
    "removeAttachments": false,
    "sendEmail": true,
    "keepPermalinks": false,
    "onlyPagesInFinalState": false,
    "onlyPagesInFinalStateProcessChildren": false,
    "publishHierarchy": false
}

Optional: Create a Preview

Click here to expand...

POST /publish/{spaceKey}/{type}/preview

Creates a preview of your publish request. A preview makes sense if you'd like to know what will be published before you actually publish it.

URL Parameter

Description

Default

Required

spaceKey

Key of the Confluence space, e.g. ds for "Documentation Space", from where the publish request should be initiated.

-

type

Type of the publish request. Allowed values:

to_same (the data will be published to the space, specified by spaceKey)
to_new (the data will be published to a new space, specified by the request entity)
to_existing (the data will be published to an existing space, specified by the request entity)

-

In order to access the endpoint successfully, you need to provide a request entity as JSON. This entity needs the following parameter:

Entity Parameter	Type	Description	Default	Required
versionId	String	The generated ID of the Version which should be published.	-
targetSpaceKey	String	Key of the Confluence space, e.g. ds for "Documentation Space", to where the Version should be published.	-
targetSpaceName	String	Name of the Confluence space to where the Version should be published. Only necessary for publish type to_new	-	()
targetSpaceBaseUrl	String	Base URL of the space to where the Version should be published. Example: http://host[:port]/[contextPath] Only necessary for remote publishing.	-	()
treeProviderName	String	Describes the Variant name which the pages need to be published. If empty, it means pages can have any or no Variant.	-
languageKey	String	Language key for the language which should be published. If key is equal to "all", it means pages can be in any language. Example: en for English	-
remoteSystemId	String	ID of the remote system to where the Version should be published. Only necessary for remote publishing. Please retrieve the ID from your Application Links from the Confluence Administration.	-	()
copyLabels	Boolean	Option indicating to copy labels of all pages and the space itself to the new space.	false
keepAuthorsAndDates	Boolean	Option indicating to keep the author and dates of all pages.	false
removeAttachments	Boolean	Option indicating to remove historical and deleted attachments from all pages, i.e. only the latest version of attachments will be published.	false
sendEmail	Boolean	Option indicating to send a notification when a page was updated.	false
keepPermalinks	Boolean	Option indicating to keep the permalinks of the original language of all pages.	false
onlyPagesInFinalState	Boolean	Option indicating to only publish pages which have the workflow status Complete assigned. ??	false
onlyPagesInFinalStateProcessChildren	Boolean	Option indicating to also publishes children of pages where the parent pages are not in the workflow status Complete. ??	false
publishHierarchy	Boolean	Option indicating to publish the page hierarchy to the target space, i.e. the parent child relationship of pages and the order of child pages.	false

Example Request

The following code will execute an example request to the preview endpoint. Here we're sending the JSON data inline with the curl command, but you should consider using a file for it (or if you're creating a script, put it into a variable/object). This increases readability of the command.

CODE

curl -H "Accept:application/json" -H "Content-Type:application/json" -X POST
"http://localhost:1990/confluence/rest/scroll-versions/1.0/publish/ds/to_new/preview?os_authType=basic" 
--data '{"versionId":"C0A81281015668F1AE5D463C4F5DC0FD", "targetSpaceKey":"ds10", "targetSpaceName":"Demonstration Space 1.0", "treeProviderName":"", "languageKey":"all", "copyLabels":false, "keepAuthorsAndDates":false, "removeAttachments":false, "sendEmail":true, "keepPermalinks":false, "onlyPagesInFinalState":false, "onlyPagesInFinalStateProcessChildren":false, "publishHierarchy":false}'

Example Result

The endpoint will start an asynchronous task in the background to calculate the preview for your request. You then receive a JSON response containing an ID and some status properties. The ID must be used to pull the status of the asynchronous task.

CODE

 {
    "id": "C0A812810156745B7C614B0332962415",
    "clusterNo": -1,
    "started": false,
    "cancelled": false,
    "hasFailed": false,
    "finished": false,
    "failureMessage": null,
    "progress": 0,
    "message": "The task 'Preview' is currently queued.",
    "resourceLocation": null
}

Publish a Version

Click here to expand...

POST /publish/{spaceKey}/{type}/publish

Publishes your request to the target space specified in the request entity (see entity parameter below).

URL Parameter

Description

Default

Required

spaceKey

Key of the Confluence space, e.g. ds for "Documentation Space", from where the publish request should be initiated.

-

type

Type of the publish request. Allowed values:

to_same (the data will be published to the space, specified by spaceKey)
to_new (the data will be published to a new space, specified by the request entity)
to_existing (the data will be published to an existing space, specified by the request entity)

-

In order to access the endpoint successfully, you need to provide a request entity as JSON. This entity needs the following parameter:

Entity Parameter	Type	Description	Default	Required
versionId	String	The generated ID of the Version which should be published.	-
targetSpaceKey	String	Key of the Confluence space, e.g. ds for "Documentation Space", to where the Version should be published.	-
targetSpaceName	String	Name of the Confluence space to where the Version should be published. Only necessary for publish type to_new	-	()
targetSpaceBaseUrl	String	Base URL of the space to where the Version should be published. Example: http://host[:port]/[contextPath] Only necessary for remote publishing	-	()
treeProviderName	String	Describes the Variant name which the pages need to be published. If empty, it means pages can have any or no Variant.	-
languageKey	String	Language key for the language which should be published. If key is equal to "all", it means pages can be in any language. Example: en for English	-
remoteSystemId	String	ID of the remote system to where the Version should be published. Only necessary for remote publishing. Please retrieve the ID from your Application Links from the Confluence Administration.	-	()
copyLabels	Boolean	Option indicating to copy labels of all pages and the space itself to the new space.	false
keepAuthorsAndDates	Boolean	Option indicating to keep the author and dates of all pages.	false
removeAttachments	Boolean	Option indicating to remove historical and deleted attachments from all pages, i.e. only the latest version of attachments will be published.	false
sendEmail	Boolean	Option indicating to send a notification when a page was updated.	false
keepPermalinks	Boolean	Option indicating to keep the permalinks of the original language of all pages.	false
onlyPagesInFinalState	Boolean	Option indicating to only publish pages which have the workflow status Complete assigned. ??	false
onlyPagesInFinalStateProcessChildren	Boolean	Option indicating to also publishes children of pages where the parent pages are not in the workflow status Complete. ??	false
publishHierarchy	Boolean	Option indicating to publish the page hierarchy to the target space, i.e. the parent child relationship of pages and the order of child pages.	false

Example Request

The following code will execute an example request to the publish endpoint. Here we're sending the JSON data inline with the curl command, but you should consider using a file for it (or if you're creating a script, put it into a variable/object). This increases readability of the command.

CODE

curl -H "Accept:application/json" -H "Content-Type:application/json" -X POST -u admin:admin 
"http://localhost:1990/confluence/rest/scroll-versions/1.0/publish/ds/to_new/publish?os_authType=basic" 
--data '{"versionId":"C0A81281015668F1AE5D463C4F5DC0FD", "targetSpaceKey":"ds10", "targetSpaceName":"Demonstration Space 1.0", "treeProviderName":"", "languageKey":"all", "copyLabels":false, "keepAuthorsAndDates":false, "removeAttachments":false, "sendEmail":true, "keepPermalinks":false, "onlyPagesInFinalState":false, "onlyPagesInFinalStateProcessChildren":false, "publishHierarchy":false}'

Example Result

The endpoint will start an asynchronous task in the background to calculate the preview for your request. You then receive a JSON response containing an ID and some status properties. The ID must be used to pull the status of the asynchronous task.

CODE

{
    "id": "C0A812810156747CDAFC88250411F484",
    "clusterNo": -1,
    "started": false,
    "cancelled": false,
    "hasFailed": false,
    "finished": false,
    "failureMessage": null,
    "progress": 0,
    "message": "The task 'Publish' is currently queued.",
    "resourceLocation": null
}

Wait for the Result

Click here to expand...

GET /async-tasks/{taskId}

Gets status information about the task with the specified task ID. The individual endpoint should be sent every few seconds, e.g. 2 seconds, because it's the client's responsibility to collect the preview or publish result. The result will be saved for 30 seconds by default. After that it will be removed from memory and can't be accessed anymore.

URL Parameter	Description	Default	Required
taskId	The ID of the task. You will get the ID from the response of the preview or publish request.	-

Example Request

CODE

curl -H "Accept:application/json" "http://localhost:1990/confluence/rest/scroll-versions/1.0/async-tasks/C0A812810156747CDAFC88250411F484"

Example Response

#1 example: the task has been started, but is still in progress.

CODE

{
    "id": "C0A812810156747CDAFC88250411F484",
    "clusterNo": -1,
    "startTimestamp": 1470831751208,
    "started": true,
    "cancelled": false,
    "hasFailed": false,
    "finished": false,
    "failureMessage": null,
    "progress": 0,
    "message": "Analysing the pages to be published: 10",
    "resourceLocation": null
}

#2 example: the task has been started and finished successfully. In this example an additional result parameter has been added to the response. This result contains some information about the published space and pages.

CODE

{
    "id": "C0A812810156747CDAFC88250411F484",
    "clusterNo": -1,
    "startTimestamp": 1470833154820,
    "completionTimestamp": 1470833157943,
    "started": true,
    "cancelled": false,
    "hasFailed": false,
    "finished": true,
    "failureMessage": null,
    "progress": 0,
    "message": "Flushing queue ...",
    "resourceLocation": null,
    "result": {
        "publishSpecSummary": {
            "versionId": "C0A81281015668F1AE5D463C4F5DC0FD",
            "targetSpaceKey": "ds10",
            "targetSpaceName": "Demonstration Space 1.0",
            "targetSpaceBaseURL": "http://localhost:1990/confluence",
            "treeProviderName": "",
            "languageKey": "all",
            "copyLabels": false,
            "keepAuthorsAndDates": false,
            "removeAttachments": false,
            "sendEmail": true,
            "keepPermalinks": false,
            "onlyPagesInFinalState": false,
            "onlyPagesInFinalStateProcessChildren": false,
            "publishHierarchy": false,
            "type": "to_new",
            "sourceSpaceKey": "ds"
        },
        "spaceKey": "ds10",
        "spaceName": "Demonstration Space 1.0",
        "versionId": "C0A81281015668F1AE5D463C4F5DC0FD",
        "status": {
            "messages": [],
            "isDirty": false,
            "isUndone": false,
            "publishedPages": [
                {
                    "type": "add",
                    "hasChanges": false,
                    "isContentChanged": true,
                    "isScrollPageTitleChanged": true,
                    "isMoved": false,
                    "isSequenceOfChildrenDifferent": false,
                    "hasAttachmentChanges": false,
                    "hasRestrictionChanges": false,
                    "hasUnchangedRestrictions": false,
                    "hasAddedRestrictions": false,
                    "hasRemovedRestrictions": false,
                    "originalPageLabels": [],
                    "originalPageContainsInlineComments": false,
                    "pageRestrictions": [],
                    "newPageId": 820647,
                    "newPageTitle": "Welcome to Confluence",
                    "newScrollPageTitle": "Welcome to Confluence",
                    "newVersionName": "Currently Published",
                    "abbreviateNewVersionName": "Currently Published",
                    "newPageLabels": [],
                    "attachments": [],
                    "newPageRevision": 1
                }, {...}
            ]
        }
    }
}