Management Endpoint

Contents

Management commands are available at port 4848, i.e. localhost:4848 if you’re running XP locally

Authorization

All endpoints here allow basic authorization. Most clients provide an option for authorization, but in case you need to do it manually: basic auth is simply a string of the username and password separated by a colon that is base64 encoded.

Make a source string:

myusername:mysecretpassword

Encode it to base64:

bXl1c2VybmFtZTpteXNlY3JldHBhc3N3b3Jk

Add a header to your request:

Key Value

Authorization

Basic bXl1c2VybmFtZTpteXNlY3JldHBhc3N3b3Jk

Read the documentation of the client you use for more info on how to add basic authorization header to your request.

Snapshots

Commands for manipulating repository snapshots

Create

Create a snapshot of all or a single repository while running. NOTE: The first snapshot only stores markers in the repository for the current state. Subsequent snapshots stores the changes since the last snapshot.

For a clustered installation, the snapshot-location must be on a shared file-system.
Url
POST repo/snapshot
Table 1. Params
Param Type Description

repositoryId

String

the name of the repository to snapshot.

Read about authorization here
Response
{
    "Name": "2019-06-13t13-10-51.973z",
    "Reason": "",
    "State": "SUCCESS",
    "Timestamp": "2019-06-13T13:10:52.575Z",
    "Indices": [
        "search-com.enonic.cms.default",
        "storage-com.enonic.cms.default",
        "search-system-repo",
        "storage-system-repo"
    ]
}

List

List all the snapshots for the installation.

Url
GET repo/snapshot/list
Read about authorization here
Response
{
    "Results": [
        {
            "Name": "2019-06-13t13-10-51.973z",
            "Reason": "",
            "State": "SUCCESS",
            "Timestamp": "2019-06-13T13:10:52.575Z",
            "Indices": [
                "search-com.enonic.cms.default",
                "storage-com.enonic.cms.default",
                "search-system-repo",
                "storage-system-repo"
            ]
        },
        {
            "Name": "2019-06-13t13-36-35.407z",
            "Reason": "",
            "State": "SUCCESS",
            "Timestamp": "2019-06-13T13:36:35.488Z",
            "Indices": [
                "search-com.enonic.cms.default",
                "storage-com.enonic.cms.default",
                "search-system-repo",
                "storage-system-repo"
            ]
        }
    ]
}

Restore

Url
POST repo/snapshot/restore
Table 2. Params
Param Type Description

snapshotName

String

snapshot name to restore

repository

String

the name of the repository to restore

latest

Boolean

if that parameter has value true then will be restored latest snapshot, in this case to set the snapshotName parameter is not required

force

Boolean

XP XP 7.12.0 7.12.0 If true then affected indices will be removed before snapshot is applied. It is helpful when Elasticsearch indices are corrupted. Default: false

Read about authorization here
Response
{
    "Message": "Restore successfull, 4 shards restored",
    "Name": "2019-06-13t13-10-51.973z",
    "Failed": false,
    "Indices": [
        "search-com.enonic.cms.default",
        "storage-com.enonic.cms.default",
        "search-system-repo",
        "storage-system-repo"
    ]
}

Delete

Deletes a snapshot by name or date:

Url
POST repo/snapshot/delete
Table 3. Params
Param Type Description

before

Date

date to delete snapshots up to

snapshotNames

String[]

List of snapshot names to delete

Read about authorization here
Response
{
    "DeletedSnapshots": [
        "2019-06-13t13-36-35.407z"
    ]
}

Dumps

List of command for manipulating all repositories

Create

Export data from every repository. The result will be stored in the $XP_HOME/data/dump directory.

Url
POST system/dump
Table 4. Params
Param Type Description

name

String

dump name

includeVersions

Boolean

dump version-history along with current versions

maxAge

Number

max age of versions to include, in days, in addition to current version

maxVersions

Number

max number of versions to dump in addition to current version

archive XP XP 7.3.0 7.3.0

Boolean

outputs dump output to an archive (%name%.zip) file (default is false)

Read about authorization here
Response
{
"taskId": "f8565e19-3960-4bf0-8daa-f4ca77ef338f"
}
Task info can be fetched with task request.
TaskInfo.progress.info value:
{
    "Repositories": [
        {
            "RepositoryId": "com.enonic.cms.default",
            "Versions": 0,
            "Branches": [
                {
                    "Branch": "master",
                    "Successful": 3,
                    "Errors": []
                },
                {
                    "Branch": "draft",
                    "Successful": 3,
                    "Errors": []
                }
            ]
        },
        {
            "RepositoryId": "system-repo",
            "Versions": 0,
            "Branches": [
                {
                    "Branch": "master",
                    "Successful": 22,
                    "Errors": []
                }
            ]
        }
    ]
}

Upgrade

Upgrade a data dump from a previous version to the current version. The output of the upgrade will be placed alongside the dump that is being upgraded and will have the name <dump-name>_upgraded_<new-version>.

The current version XP installation must be running with the upgraded app deployed.
Upgrade does not work with archived dumps.
Url
POST system/upgrade
Table 5. Params
Param Type Description

name

String

dump name

Read about authorization here
Response
{
    "taskId": "549c38ac-e20a-4851-8536-3fd2b937e328"
}
Task info can be fetched with task request.
TaskInfo.progress.info value:
{
    "InitialVersion": "8.0.0",
    "UpgradedVersion": "8.0.0"
}

Load

Load data from a named system dump into Enonic XP. The dump read has to be stored in the $XP_HOME/data/dump directory.

Upgrade does not work with archived dumps.
A load will delete all existing repositories before loading the repositories present in the system-dump
Url
POST system/load
Table 6. Params
Param Type Description

name

String

dump name to load

upgrade

Boolean

upgrade the dump if necessary (default is false)

archive XP XP 7.3.0 7.3.0

Boolean

loads dump form an archive (%name%.zip) file (default is false)

Read about authorization here
Response
{
    "taskId": "a0b774dd-03f1-48fd-b500-b76a93c6b6fe"
}
Task info can be fetched with task request.
TaskInfo.progress.info value:
{
    "Repositories": [
        {
            "Repository": "system-repo",
            "Versions": {
                "Errors": [],
                "Successful": 0
            },
            "Branches": [
                {
                    "Branch": "master",
                    "Successful": 22,
                    "Errors": []
                }
            ]
        },
        {
            "Repository": "com.enonic.cms.default",
            "Versions": {
                "Errors": [],
                "Successful": 0
            },
            "Branches": [
                {
                    "Branch": "draft",
                    "Successful": 3,
                    "Errors": []
                },
                {
                    "Branch": "master",
                    "Successful": 3,
                    "Errors": []
                }
            ]
        }
    ]
}

Export

Export and import data from a given repository, branch and content path.

Create

Extract data from a given repository, branch and content path. The result will be stored in the $XP_HOME/data/export directory. This is useful to move a part of a site from one installation to another.

Exporting content will not include the version history of the content, just the current version.
Url
POST repo/export
Table 7. Params
Param Type Description

exportName

String

target name to save export

sourceRepoPath

String

path of data to export. Format: <repo-name>:<branch-name>:<node-path> e.g. cms-repo:draft:/some-content

exportWithIds

Boolean

Flag to include or skip ids in data when exporting.

includeVersions

Boolean

Flag to include or skip versions in data when exporting.

dryRun

Boolean

Show the result without making actual changes.

Read about authorization here
Response
{
"taskId": "2003993f-cf52-4aa0-aca8-66c3911e6b31"
}
Task info can be fetched with task request.
TaskInfo.progress.info value:
{
    "DryRun": false,
    "ExportedBinaries": [],
    "ExportedNodes": [
        "/",
        "/content",
        "/issues"
    ],
    "Errors": null
}

Import

Import data from a named export into Enonic XP at the desired content path. The export read has to be stored in the $XP_HOME/data/export directory.

Url
POST repo/import
Table 8. Params
Param Type Description

exportName

String

a named export to import

targetRepoPath

String

target path for import. Format: <repo-name>:<branch-name>:<node-path> e.g. cms-repo:draft:/some-content

xslSource

String

path to xsl file (relative to <XP_HOME>/data/export) for applying transformations to node.xml before importing

xslParams

JSON

parameters to pass to the XSL transformations before importing nodes. Format: {"applicationId": "com.enonic.myapp"}

importWithIds

Boolean

flag to include or skip ids when importing

importWithPermissions

Boolean

flag to include or skip permissions when importing

dry

Boolean

show the result without making actual changes.

Read about authorization here
Response
{
    "taskId": "767dad91-eecd-442b-a9f8-d3a892e1e8c4"
}
Task info can be fetched with task request.
TaskInfo.progress.info value:
{
    "AddedNodes": [],
    "UpdateNodes": [
        "/",
        "/content",
        "/issues"
    ],
    "ImportedBinaries": [],
    "ImportErrors": [],
    "DryRun": false
}

An XSL file and a set of name=value parameters can be optionally passed for applying transformations to each node.xml file, before importing it.

This option could for example be used for renaming types or fields. The .xsl file must be located in the $XP_HOME/data/export directory.

Applications

Commands to manage applications in a running Enonic XP instance.

Install from file

Installs an application from file on all nodes.

Url
POST app/install
Table 9. Params
Param Type Description

file

File

File of the application

Read about authorization here
Response
{
    "ApplicationInstalledJson": {
        "Application": {
            "DisplayName": "Content Studio",
            "Key": "com.enonic.app.contentstudio",
            "Deletable": false,
            "Editable": false,
            "Local": false,
            "MaxSystemVersion": "8.0.0",
            "MinSystemVersion": "7.0.0",
            "ModifiedTime": "2019-06-13T14:48:30.314Z",
            "State": "started",
            "Url": "",
            "VendorName": "Enonic AS",
            "VendorUrl": "http://enonic.com",
            "Version": "1.0.0.SNAPSHOT"
        }
    },
    "Failure": ""
}

Install from URL

Installs an application from url on all nodes.

Url
POST app/installUrl
Table 10. Params
Param Type Description

URL

String

application URL

sha512

String

XP XP 7.6.0 7.6.0 application file SHA-512 checksum. Optional. If provided, and checksum does not match, installation will fail.

Read about authorization here
Response
{
    "ApplicationInstalledJson": {
        "Application": {
            "DisplayName": "Content Studio",
            "Key": "com.enonic.app.contentstudio",
            "Deletable": false,
            "Editable": false,
            "Local": false,
            "MaxSystemVersion": "8.0.0",
            "MinSystemVersion": "7.0.0",
            "ModifiedTime": "2019-06-13T14:50:53.917Z",
            "State": "started",
            "Url": "",
            "VendorName": "Enonic AS",
            "VendorUrl": "http://enonic.com",
            "Version": "2.0.0"
        }
    },
    "Failure": ""
}

Start

XP XP 7.6.0 7.6.0 Starts an application with specific application key.

Url
POST app/start
Table 11. Params
Param Type Description

key

String

Application key, for instance, com.enonic.app.contentstudio.

Read about authorization here
Response
No response body

Stop

XP XP 7.6.0 7.6.0 Stops an application with specific application key.

Url
POST app/stop
Table 12. Params
Param Type Description

key

String

Application key, for instance, com.enonic.app.contentstudio.

Read about authorization here
Response
No response body

Uninstall

XP XP 7.6.0 7.6.0 Uninstalls an application with specific application key.

Url
POST app/uninstall
Table 13. Params
Param Type Description

key

String

Application key, for instance, com.enonic.app.contentstudio.

Read about authorization here
Response
No response body

Server-Sent Events

XP XP 7.6.0 7.6.0 The client initiates the SSE connection by using the media type text/event-stream in the Accept header. Then it gets updates automatically without requesting the server.

Url
GET app/events

This API supports the following events:

  • list - returns the details of applications which are already installed

  • installed - returns the details of the last applications that was installed

  • state - returns the details of the application that was just started or stopped

  • uninstalled - returns the key of the application that was just removed

Once a client is subscribed, he will receive the first event list.

Response of the list event
event: list
id: b0d64cac-811d-4f6b-9aff-50fd4d4a5ae9
data: {"applications":[{"displayName":"Content Studio","key":"com.enonic.app.contentstudio","local":false,"maxSystemVersion":"8.0.0","minSystemVersion":"7.6.0","modifiedTime":"2020-11-11T08:22:14.080Z","state":"started","url": "", "vendorName": "Enonic AS", "vendorUrl": "http://enonic.com", "version": "2.0.0"}]}
Response of the installed or state events
event: installed | state
id: f84d11ba-88cd-4cd2-9cb3-39dd181eb7e2
data: {"displayName":"Content Studio","key":"com.enonic.app.contentstudio","local":false,"maxSystemVersion":"8.0.0","minSystemVersion":"7.6.0","modifiedTime":"2020-11-11T08:22:14.080Z","state":"started","url": "", "vendorName": "Enonic AS", "vendorUrl": "http://enonic.com", "version": "2.0.0"}
Response of the uninstalled event
event: uninstalled
id: b7a0f608-631f-4a1d-bda0-5459b87a99a6
data: {"key":"com.enonic.app.contentstudio"}

CMS

Content metadata commands.

Reprocess

Reprocesses content in the repository and regenerates metadata for the media attachments. Only content of a media type (super-type = base:media) are processed. Unless the skipChildren flag is specified, it processes all descendants of the specified content path.

This command should be used after migrating content from Enonic CMS using the cms2xp tool.
Url
POST content/reprocess
Table 14. Params
Param Type Description

sourceBranchPath

String

target content path to be reprocessed. Format: <branch-name>:<content-path>. e.g draft:/

skipChildren

Boolean

flag to skip processing of content children

Read about authorization here
Response
{
    "Errors": [],
    "UpdatedContent": []
}

Reprocess Task

Calls reprocess endpoint as a task.

This command should be used after migrating content from Enonic CMS using the cms2xp tool.
Url
POST content/reprocessTask
Table 15. Params
Param Type Description

sourceBranchPath

String

target content path to be reprocessed. Format: <branch-name>:<content-path>. e.g draft:/

skipChildren

Boolean

flag to skip processing of content children

Response
{
    "taskId": "07500a00-8d60-4084-9657-af6725dc587d"
}
Task info can be fetched with task request.

Projects

Project related commands.

List

XP XP 7.13.0 7.13.0

Lists all projects together with their sites.

Url
GET content/projects/list
Response
[
  {
    "description" : "Testing features for Enonic XP",
    "displayName" : "Features",
    "name" : "features",
    "parent" : "default",
    "branches" : [
      {
        "name" : "draft",
        "sites" : [
          {
            "displayName" : "Features",
            "language" : "en",
            "path" : "/features"
          },
          {
            "displayName" : "AuditLogsDemo",
            "language" : null,
            "path" : "/features/js-libraries/audit-logs"
          }
        ]
      },
      {
        "name" : "master",
        "sites" : [
          {
            "name": "master",
            "sites": [
              {
                "displayName": "Features",
                "language": null,
                "path": "/features"
              }
            ]
          }
        ]
      }
    ]
  },
  {
    "description" : null,
    "displayName" : "Default",
    "name" : "default",
    "parent" : null,
    "branches" : [
      {
        "name" : "draft",
        "sites" : []
      },
      {
        "name" : "master",
        "sites" : []
      }
    ]
  }
]

SyncAll

XP XP 7.6.0 7.6.0

Calls forced content sync for all available projects.

Url
POST content/syncAll
Read about authorization here
Response
{
    "taskId": "767dad91-eecd-442b-a9f8-d3a892e1e8c4"
}

ID Providers

XP XP 7.13.0 7.13.0

Id providers related commands.

List

Lists all the id providers.

Url
GET idproviders/list
Response
[
  {
    "description" : null,
    "displayName" : "Auth ID Provider",
    "key" : "auth-id-provider"
  },
  {
    "description" : "Azure connection",
    "displayName" : "Azure ID Provider",
    "key" : "azure-id-provider"
  },
  {
    "description" : null,
    "displayName" : "System Id Provider",
    "key" : "system"
  }
]

Webapps

XP XP 7.13.0 7.13.0

Web apps related commands.

List

Lists all the web apps.

Url
GET webapps/list
Response
[
    {
      "name": "com.enonic.cloud.console"
    },
    {
      "name": "com.enonic.cloud.api"
    }
]

Repository

Commands for configuring and managing repositories.

Reindex

Reindex the content in the search indices for the given repository and branches. This is usually required after upgrades and may be useful in many other cases.

Url
POST repo/index/reindex
Table 16. Params
Param Type Description

branches

String

a comma-separated list of branches to be reindexed

repository

String

the name of the repository to reindex

initialize

Boolean

if true, the indices will be deleted before recreated

Read about authorization here
Response
{
    "RepositoryId": "com.enonic.cms.default",
    "Branches": [
        "draft",
        "master"
    ],
    "NumberReindexed": 3,
    "StartTime": "2019-06-14T07:58:38.663Z",
    "EndTime": "2019-06-14T07:58:38.719Z",
    "Duration": "PT-0.056S"
}

Reindex Task

Calls reindex endpoint as a task.

Url
POST repo/index/reindex
Table 17. Params
Param Type Description

branches

String

a comma-separated list of branches to be reindexed

repository

String

the name of the repository to reindex

initialize

Boolean

if true, the indices will be deleted before recreated

Response
{
    "taskId": "cb1b4e06-22ad-4235-8876-a443c88c290b"
}
Task info can be fetched with task request.

Settings

Update settings for a specified repository.

Url
POST repo/index/updateSettings
Table 18. Params
Param Type Description

repositoryId

String

single repository to toggle read-only mode for

settings

JSON

settings object, see below

Read about authorization here
Available settings options
{
    "index": {
        "blocks.write": true, (1)
        "number_of_replicas": 3 (2)
    }
}
1 Toggle read-only mode.
2 Set the number of replicas in the cluster.
Response
{
    "UpdatedIndexes": [
        "search-com.enonic.cms.default",
        "storage-com.enonic.cms.default",
        "search-system-repo",
        "storage-system-repo"
    ]
}

Repository List

List available repositories.

Url
GET repo/list
Read about authorization here
Response
{
    "Repositories": [
        {
            "Branches": [
                "master",
                "draft"
            ],
            "Id": "com.enonic.cms.default"
        },
        {
            "Branches": [
                "master"
            ],
            "Id": "system-repo"
        }
    ]
}

Vacuum

Deletes unused blobs and binaries from blobstore.

Make sure you have a backup of the installation available before doing a vacuum.
Read about authorization here
Url
POST system/vacuum
Table 19. Params
Param Type Description

ageThreshold

String

Age of data to be removed. The format is based on the ISO-8601 duration format PnDTnHnMn.nS with days considered to be exactly 24 hours. Default is defined by ageThreshold property in Vacuum config file

tasks

String[]

List of vacuum task to be run. Default : ["SegmentVacuumTask", "VersionTableVacuumTask"]

This API supports the following tasks:
SegmentVacuumTask - removes unused repositories.
VersionTableVacuumTask - removes unused and non-commited versions together with it’s blobs.
BinaryBlobVacuumTask - checks all binary blobs and removes unused.
NodeBlobVacuumTask - checks all node blobs and removes unused.

Read about authorization here
Response
{
    "taskId": "cb1b4e06-22ad-4235-8876-a443c88c290b"
}
Task info can be fetched with task request.
TaskInfo.progress.info value:
{
     "TaskResults": [
        {
            "Deleted": 0,
            "Failed": 0,
            "InUse": 13,
            "Processed": 13,
            "TaskName": "SegmentVacuumTask"
        },
        {
            "Deleted": 4,
            "Failed": 0,
            "InUse": 96,
            "Processed": 100,
            "TaskName": "VersionTableVacuumTask"
        }
    ]
}

Clean Up Audit Log

Deletes records from audit log repository.

Make sure you have a backup of the installation available before running a cleanup.
Url
POST auditlog/cleanup
Table 20. Params
Param Type Description

ageThreshold

String

Age of records to be removed. The format based on the ISO-8601 duration format PnDTnHnMn.nS with days considered to be exactly 24 hours.

Request Body Example
{
    "ageThreshold" : "PT10H" //all records older than 10 hours will be removed
}
Response
{
    "taskId": "cb1b4e06-22ad-4235-8876-a443c88c290b"
}

Task

Fetches particular Task information.

Url
GET task/{taskId}
Table 21. Params
Param Type Description

taskId

String

particular task id

Response

TaskInfo object.

Scheduled Jobs List

XP XP 7.7.0 7.7.0

List scheduled jobs.

Read about authorization here
Url
GET scheduler/list
Response
[
  {
    "calendar": {
      "cronValue": "* * * * *",
      "timeZone": "GMT+03:00",
      "type": "CRON"
    },
    "config": [
      {
        "name": "string",
        "type": "String",
        "values": [
          {
            "v": "value"
          }
        ]
      }
    ],
    "createdTime": "2010-01-01T00:00:00Z",
    "creator": "user:system:creator",
    "description": "description",
    "descriptor": "com.enonic.app.features:landing",
    "enabled": true,
    "lastRun": "2012-01-01T00:00:00Z",
    "lastTaskId": "task-id",
    "modifiedTime": "2011-02-01T00:00:00Z",
    "modifier": "user:system:creator",
    "name": "test1",
    "user": "user:system:user"
  },
  {
    "calendar": {
      "type": "ONE_TIME",
      "value": "2016-11-02T10:36:00Z"
    },
    "config": [],
    "createdTime": "2010-01-01T00:00:00Z",
    "creator": "user:system:creator",
    "description": null,
    "descriptor": "com.enonic.app.features:landing",
    "enabled": false,
    "lastRun": null,
    "lastTaskId": null,
    "modifiedTime": "2011-02-01T00:00:00Z",
    "modifier": "user:system:creator",
    "name": "test2",
    "user": null
  }
]

Contents

Contents