Skip to main content
Skip table of contents

Export Content via REST API

This page describes how to export content using the REST API. There are two ways to do this: synchronously and asynchronously.

  • Synchronous exports are easier, and are recommended for the majority of use cases. You simply build the URL for the export parameters you want (template ID, page ID, etc.), and then you can download the exported file like any other file on the web using a web browser or a tool like curl or wget.
  • Asynchronous exports are useful if your exports are extremely large or if you want to start the export job from a script and track its progress

Synchronous export 

Prepare the export URL

  1. Open Space Tools > Add-ons > Scroll HTML Exporter
  2. Find the template you want to use, open the actions dropdown menu, and click Template Information. This will open the template information dialog.
  3. Copy the URL from the REST URL field.
  4. Replace PAGE-ID with the ID of the page you want to export.
  5. (Optional) If required, you can add export parameters as query parameters.

Example export URL:

BASH
http://example.com/confluence/plugins/servlet/scroll-html/api/public/1/export-sync?templateId=205721cc-6689-47ac-ae43-a98cf7f1d9ec&pageId=12345&scope=current

Use the export URL

There are many tools to request data from HTTP servers. Here are some examples using popular tools.

Make sure to check the authentication section below.

curl

Available at https://curl.se

  • Basic Authentication

    BASH
    curl --remote-header-name --remote-name -u admin:admin "http://example.com/confluence/plugins/servlet/scroll-html/api/public/1/export-sync?templateId=205721cc-6689-47ac-ae43-a98cf7f1d9ec&pageId=12345&os_authType=basic"
  • URL Parameters

    BASH
    curl --remote-header-name --remote-name "http://example.com/confluence/plugins/servlet/scroll-html/api/public/1/export-sync?templateId=205721cc-6689-47ac-ae43-a98cf7f1d9ec&pageId=12345&os_username=admin&os_password=admin"
  • Access Token

    BASH
    curl --remote-header-name --remote-name -H "Authorization: Bearer MY_TOKEN" "http://example.com/confluence/plugins/servlet/scroll-html/api/public/1/export-sync?templateId=205721cc-6689-47ac-ae43-a98cf7f1d9ec&pageId=12345"
wget

Available at https://www.gnu.org/software/wget

  • Basic Authentication

    BASH
    wget --content-disposition --http-user=admin --http-password=admin "http://example.com/confluence/plugins/servlet/scroll-html/api/public/1/export-sync?templateId=205721cc-6689-47ac-ae43-a98cf7f1d9ec&pageId=12345&os_authType=basic"
  • URL Parameters

    BASH
    wget --content-disposition "http://example.com/confluence/plugins/servlet/scroll-html/api/public/1/export-sync?templateId=205721cc-6689-47ac-ae43-a98cf7f1d9ec&pageId=12345&os_username=admin&os_password=admin"
  • Access Token

    BASH
    wget --content-disposition --header="Authorization: Bearer MY_TOKEN" "http://example.com/confluence/plugins/servlet/scroll-html/api/public/1/export-sync?templateId=205721cc-6689-47ac-ae43-a98cf7f1d9ec&pageId=12345"

Asynchronous export 

To export content asynchronously, you have to

  1. Start the export job (the server will return the ID of the job).
  2. Fetch the status of the export job at regular intervals.
  3. Download the zipped HTML file(s) when the export job has finished.

For more details, read on or take a look at the example scripts: https://bitbucket.org/K15t/scroll-exporter-rest-api-scripts

Export job information is removed 10 minutes after the completion of the job, and this time limit is not configurable.

Send a POST request to the URL <base-url>/plugins/servlet/scroll-html/api/public/1/exports. The body of the request must contain the export parameters in a JSON object, for example:

JS
{
  "pageId":"557060",
  "scope":"current",
  "templateId":"com.k15t.scroll.html.helpcenter"
}

You can find the templateID by clicking Space Tools > Add-ons > Scroll HTML Exporter, finding the template you want to use and clicking Template Information in the actions dropdown menu.

The server will return a JSON object that contains the ID of the export job, for example:

JS
{
  "jobId": "f3c7c62b-30fb-4260-a323-10779a2b72a3"
}

Monitor the status of the export job

Fetch the status of the export job at regular intervals (we recommend every two seconds) until the job is complete. To get the status, send a GET request to the URL  <base-url>/plugins/servlet/scroll-html/api/public/1/exports/<job-id>/status. The response contains a JSON object describing the status of the export job, for example:

CODE
{
  "status": "incomplete",
  "step": 2,
  "totalSteps": 3,
  "stepProgress": 75,
  "downloadUrl": null
}

The status property is set to either

  • incomplete (the export is still running)
  • complete (the export has finished successfully)
  • error (the export stopped with an error)
  • cancelled (the export was cancelled)

The step and totalSteps properties show how many of the steps of the export job are done. The stepProgress property indicates the progress of the current step, from 0 to 100.

Download the PDF File

As soon as the status is complete, the downloadUrl property will contain the URL where the zip file can be downloaded.

Cancelling a running or queued export

It is possible to cancel exports that are still queued or are currently being processed by sending a DELETE request without body to <base-url>/plugins/servlet/scroll-html/api/public/1/exports/<job-id>.

Please note that the status retrieved by GET requests to <base-url>/plugins/servlet/scroll-html/api/public/1/exports/<job-id>/status will not immediately reflect that the job has been cancelled if the job is still queued but not currently processed.

Exporting as anonymous user

If you intend to perform an asynchronous export as anonymous user you must include the session cookie returned in the start request's response into all subsequent requests (polling and download). This is required for permission checks. We recommend to use a dedicated user for exports, though.

Multi-Node Data Center Setups

If you run a multi-node Data Center instance it is important to make sure that you're asking the correct node for the status. Additionally, any script using the REST API would also need to handle cookies returned by Confluence, because these cookies will ensure that all requests for a specific export job end up on the same node every time. Our example python script includes the necessary changes here.

Authentication

The following authentication methods are available for the REST API.

Authentication MethodUsageCompatibility

Manual Login

BROWSER UNSAFE-ONLY

Log in via the Confluence login page.

  • Can only be used when using the REST API in the browser.
  • You will be authenticated for the REST APIs for that same browser session.
All Confluence versions
HTTP Basic Authentication

Add Authorization HTTP header to the request:

CODE
Authorization: Basic <username:password>
  • The username:password combination must be base64-encoded
  • Add query parameter os_authType=basic to the REST API URL
Starting with Confluence 7.16 administrators can disable Basic Authentication.
URL Parameters

Add both username and password as URL parameters:

CODE
...&os_username=admin&os_password=admin

Not available since Confluence 7.10 unless manually enabled.

See the Confluence 7.10 Upgrade Notes for instructions.

Personal Access Tokens

RECOMMENDED

Create a token in your user profile, then add it as request header:

CODE
Authorization: Bearer my-token
Confluence 7.14 and later due to certain limitations after introduction of access tokens in Confluence 7.9

IDs used in Export Parameters

When starting an export, you may need to provide several IDs to the API. Here's how to locate them:

Page / Blog Post ID

Can be found by opening the Page Information screen via ...Advanced detailsPage Information

The ID is contained in the URL of this screen, for example: .../wiki/pages/viewinfo.action?pageId=2053799937 

Template IDCan be retrieved by inspecting the template information in the space / global template list's Action menu.
Scroll Versions: Version IDCan be retrieved using the following REST call: <BASE_URL>/rest/scroll-versions/1.0/versions/<spaceKey>
Scroll Versions: Variant IDCan be retrieved using the following REST call: <BASE_URL>/rest/scroll-versions/1.0/variant/<spacekey>
Scroll Translations: Language KeyCan be retrieved using the following REST call: <BASE_URL>/rest/scroll-versions/1.0/language/<spacekey>

OpenAPI Specs

The API specs below represent the lastest API provided by the Server and Data Center versions of Scroll PDF Exporter. You may download the OpenApi spec file specific for your app version at:

<BASE_URL>/download/resources/com.k15t.scroll.scroll-html/api-docs/1/openapi.yaml


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.