openapi: 3.0.1
info:
  title: Scroll Exporter Public REST API
  description: "Provides endpoints for starting, inspecting and cancelling export\
    \ jobs."
  contact:
    name: K15t Support
    url: https://support.k15t.com
    email: help@k15t.com
  version: "1.0"
externalDocs:
  description: K15t Help Center
  url: https://help.k15t.com/scroll-pdf-exporter/latest/cloud/?contentKey=export-content-via-rest-api
servers:
- url: https://scroll-pdf.us.exporter.k15t.app/api
  description: Scroll PDF Exporter for Confluence Cloud US Region
  variables: {}
- url: https://scroll-word.us.exporter.k15t.app/api
  description: Scroll Word Exporter for Confluence Cloud US Region
  variables: {}
- url: https://scroll-html.us.exporter.k15t.app/api
  description: Scroll HTML Exporter for Confluence Cloud US Region
  variables: {}
- url: https://scroll-pdf.de.exporter.k15t.app/api
  description: Scroll PDF Exporter for Confluence Cloud DE Region
  variables: {}
- url: https://scroll-word.de.exporter.k15t.app/api
  description: Scroll Word Exporter for Confluence Cloud DE Region
  variables: {}
- url: https://scroll-html.de.exporter.k15t.app/api
  description: Scroll HTML Exporter for Confluence Cloud DE Region
  variables: {}
- url: "{CONFLUENCE_BASE_URL}/plugins/servlet/scroll-pdf/api"
  description: Scroll PDF Exporter for Confluence Data Center
  variables:
    CONFLUENCE_BASE_URL:
      default: http://localhost:8090
- url: "{CONFLUENCE_BASE_URL}/plugins/servlet/scroll-office/api"
  description: Scroll Word Exporter for Confluence Data Center
  variables:
    CONFLUENCE_BASE_URL:
      default: http://localhost:8090
- url: "{CONFLUENCE_BASE_URL}/plugins/servlet/scroll-html/api"
  description: Scroll HTML Exporter for Confluence Data Center
  variables:
    CONFLUENCE_BASE_URL:
      default: http://localhost:8090
security:
- BearerAuth: []
tags:
- name: Start Export
  description: Call this first to start an export job.
- name: Get Export Status
  description: "Once started, use this to retrieve the status."
- name: Cancel Export
  description: Optional - cancels running exports.
paths:
  /public/1/exports/{exportJobId}:
    delete:
      tags:
      - Cancel Export
      summary: Cancel Export
      description: |-
        Cancels a scheduled or running export job. **This is normally not required and has no effect on completed export jobs.**

        Use this in case you realize you don't need the export result anymore while the export job is still running and you wish to save some resources. Just for your karma :-)
      operationId: cancel-export
      parameters:
      - name: exportJobId
        in: path
        required: true
        schema:
          type: string
      responses:
        "202":
          description: If cancellation of the export job has been successfully initiated.
            It might take some time to completely cancel the running export job.
        "400":
          description: If any of the provided parameters are invalid.
        "401":
          description: If no access token is provided in the request via Authorization
            header.
        "403":
          description: If the current user doesn't have permissions to cancel the
            specified export job. Only the user starting a job can cancel it.
  /public/1/exports/{exportJobId}/status:
    get:
      tags:
      - Get Export Status
      summary: Get Status
      description: |-
        Returns a status object with detailed information about the specified export job's progress.

        Once the export has completed successfully or with an error, the status object will contain a download URL for either the exported file or an error.zip file containing further details on the error.
      operationId: get-status
      parameters:
      - name: exportJobId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: The current status of the export job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportStatus'
        "400":
          description: If any of the provided parameters are invalid.
        "401":
          description: If no access token is provided in the request via Authorization
            header.
        "403":
          description: If the current user doesn't have permissions to view the specified
            export job. Only the user starting a job can view its details.
  /public/1/exports:
    post:
      tags:
      - Start Export
      summary: Start Export
      description: |-
        Starts a new export job with the provided parameters and returns its ID.
        Use the `Get Status` endpoint for progress and download details.
      operationId: start-export
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartExportRequest'
        required: true
      responses:
        "200":
          description: The ID of the new export job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartExportResponse'
        "400":
          description: If any of the provided parameters are invalid.
        "401":
          description: If no access token is provided in the request via Authorization
            header.
        "403":
          description: If the current user doesn't have permissions to start an export
            with the specified parameters.
components:
  schemas:
    ExportStatus:
      type: object
      properties:
        status:
          type: string
          description: |-
            A summary of the status.
            * Initially export jobs are in status `incomplete`.
            * After finishing they are in status `complete` or `error`.
            * If cancelled by the user the status will be `cancelled`.
          enum:
          - incomplete
          - complete
          - cancelled
          - error
        step:
          type: integer
          description: |
            One of:
            * 1 - Initial step, while collecting pages to export.
            * 2 - While exporting and processing page content from Confluence.
            * 3 - While converting the content to the output format.
          format: int32
        totalSteps:
          type: integer
          description: Always 3. This might change in case additional export steps
            will be added in the future.
          format: int32
        stepProgress:
          type: integer
          description: The progress of the current step (0-100%).
          format: int32
        downloadUrl:
          type: string
          description: "Only set if the status is `complete` or `error`. Clients must\
            \ use this URL to download the exported file, or error.zip in case of\
            \ an export error."
    StartExportResponse:
      type: object
      properties:
        jobId:
          type: string
          description: The unique ID of the new export job. Use with the `Get Status`
            or `Cancel Export` endpoints.
    StartExportRequest:
      required:
      - pageId
      - templateId
      type: object
      properties:
        pageId:
          type: string
          description: The ID of the page or blog post that the export should start
            from.
          example: "123456"
        scope:
          type: string
          description: |-
            Defines what pages will be exported:
            * `descendants` will export the specified page and its descendants.
            * `current` will only export the specified page.
            * `document` will export the whole Scroll Documents document that the specified page belongs to.

            When not specified, the default export scope of the specified template will be used. If the template does not specify such a default scope then `descendants` will be used.
          example: current
          enum:
          - descendants
          - current
          - document
        templateId:
          type: string
          description: The ID of the template to use for this export. Template IDs
            can be retrieved by inspecting the template information in the space /
            global template list's 'Action' menu.
          example: com.k15t.scroll.pdf.default-template-confluence
        versionId:
          type: string
          description: The ID of the Scroll Versions version to export. Ignored on
            Cloud.
        variantId:
          type: string
          description: Either the ID of a Scroll Documents or Scroll Versions variant.
            If specified only content belonging to that variant will be exported.
        languageKey:
          type: string
          description: The key of the Scroll Translations language to export. Ignored
            on Cloud.
        locale:
          type: string
          description: |-
            A BCP 47 language tag (`en`, `en-US`, `de`, `de-DE`, ...) specifying the locale to use when generating placeholder content like dates.

            If not specified the locale from the request's `Accept-Language` header will be used. Defaults to English if neither is available.
          example: en-US
        timeZone:
          type: string
          description: |-
            An IANA time zone database name (`Etc/UTC`, `Europe/Berlin`, `Asia/Hong_Kong`) specifying the time zone to use when generating placeholder content like dates.

            Defaults to the user time zone if not available.
          example: Europe/Berlin
  securitySchemes:
    BearerAuth:
      type: http
      description: |-
        API authentication requires an API token for the respective exporter.

        * Cloud: Create an exporter-specific API token for your Confluence instance: [PDF](https://help.k15t.com/scroll-pdf-exporter/latest/cloud/?contentKey=export-content-via-rest-api) [Word](https://help.k15t.com/scroll-word-exporter/latest/cloud/?contentKey=export-content-via-rest-api)
         [HTML](https://help.k15t.com/scroll-html-exporter/latest/cloud/?contentKey=export-content-via-rest-api)
        * Server/Datacenter: Create a [personal access token](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html) for your user account.
      scheme: bearer
