×

You're using an outdated browser

For a better experience, keep your browser up to date. Check here for the latest version.

Manual

Export content via REST API

Nils Bier

Nils Bier Last update: Dec 20, 2018

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 

Build the export URL

  1. Open Space Tools > Add-ons > Scroll PDF 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 other export parameters as query parameters.

Example export URL:

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

Use the export URL

Authentication

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 (please note that 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 a non-browser tool like wget or curl, you'll have to use either HTTP basic authentication or URL parameters.

curl

curl is a command line tool for transferring data with URL syntax. This section describes how to use curl with the command line.

HTTP basic authentication:
curl --remote-header-name --remote-name -u admin:admin "http://example.com/confluence/plugins/servlet/scroll-pdf/api/public/1/export-sync?templateId=205721cc-6689-47ac-ae43-a98cf7f1d9ec&pageId=12345&os_authType=basic"
URL parameter based authentication:
curl --remote-header-name --remote-name "http://example.com/confluence/plugins/servlet/scroll-pdf/api/public/1/export-sync?templateId=205721cc-6689-47ac-ae43-a98cf7f1d9ec&pageId=12345&os_username=admin&os_password=admin"

wget

wget is another command line tool for transferring data with URL syntax. This section describes how to use wget with the command line.

HTTP basic authentication:
wget --content-disposition --http-user=admin --http-password=admin "http://example.com/confluence/plugins/servlet/scroll-pdf/api/public/1/export-sync?templateId=205721cc-6689-47ac-ae43-a98cf7f1d9ec&pageId=12345&os_authType=basic"
URL parameter based authentication:
wget --content-disposition "http://example.com/confluence/plugins/servlet/scroll-pdf/api/public/1/export-sync?templateId=205721cc-6689-47ac-ae43-a98cf7f1d9ec&pageId=12345&os_username=admin&os_password=admin"

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 PDF file when the export job has finished.

For more details, read on or take a look at this example Python script (tested with Python 2.7).

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

{
  "pageId":"557060",
  "scope":"current",
  "templateId":"com.k15t.scroll.pdf.default-template-article"
}

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

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

{
  "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-pdf/api/public/1/exports/<job-id>/status. The response contains a JSON object describing the status of the export job, for example:

{
  "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 PDF file can be downloaded.

Export parameters 

(info) Please make sure to follow the capitalization as stated in this table

NameRequired/
Optional
DescriptionPossible values
pageId

REQUIRED

The ID of the page or blog post to be exported.
templateId

REQUIRED

The ID of the export template to use.
scope

OPTIONAL

Controls whether the child pages of the exported page should be exported, too.
  • current
  • descendants
locale

OPTIONAL

The locale of the exporting user. This only has an effect if the template's locale is set to User Language .

You can also specify the locale through an Accept-Language header, but the locale in the export request has precedence if provided. If neither the export request nor the Accept-Language header contains an explicit locale, 'en' is used.

A valid  BCP 47  language tag, e.g. 'en-US' or 'de'.
versionId

OPTIONAL

Only use if Scroll Versions' version management functionality is activated in the space you are exporting from.

The ID of the version of the content to be exported (default value: currently published version). You can find the versionId using the following REST call: <confluence address>/rest/scroll-versions/1.0/versions/<spaceKey>

Please note that this parameter does not have a default value when exporting with a deprecated template and needs to be specified.


variantId

OPTIONAL

Only use if Scroll Versions' variant management functionality is activated in the space you are exporting from.

The ID of the variant of the content to be exported (default value: 'all').

You can find the variantId using the following REST call: <Confluence address>/rest/scroll-versions/1.0/variant/<spacekey>

Please note that this parameter does not have a default value when exporting with a deprecated template and needs to be specified.


languageKey

OPTIONAL

Only use if Scroll Versions' variant management functionality is activated in the space you are exporting from.

For use with Scroll Translations! The language key of the translation to be exported (default value: the space's default language).

Please note that this parameter does not have a default value when exporting with a deprecated template and needs to be specified.


2x4.1
We use cookies to create a secure and effective browsing experience for our website visitors and to understand how you use our site (i.e. Google Analytics). For more information: click here.
Ok