Docs Developer Site
Developer Docs Enonic XP next Endpoints Management Management resources

Management resources

Contents

XPXP8.2.08.2.0 Resource-oriented management APIs on the management endpoint (port 4848), with per-resource, per-verb exposure control from virtual host configuration.

Overview

Every management operation is exposed as a resource with a fixed set of verbs: list, get, create, delete, load, restore, prune, watch. A resource is an API on the management endpoint, addressed by its descriptor key at the root of the port:

http://localhost:4848/server:snapshot

The legacy REST API (repo/snapshot/list, system/dump, …​) is unchanged. A virtual host selects which resources and verbs it exposes, and can switch the legacy paths off.

Authorization

Same as the rest of the management endpoint: an authenticated user with the system.admin role, by service account JWT or basic authentication. See Authorization.

Conventions

  • Queries are GET and take no body. A collection is read at the resource root (GET /server:repo), an item by name (GET /server:repo/{repo}).

  • Commands are POST with a JSON body (or PUT when they replace the state of an item, DELETE when they remove one). A command naming an existing item puts the name in the path: POST /server:dump/{name}/load.

  • Long-running commands return 202 Accepted with the id of a task to poll through server:task. Except for server:content sync, every such command is a cluster task of the system application (com.enonic.xp.app.system:dump, :export, :reindex, …​) and runs on any node of the cluster. In a cluster, $XP_HOME/data and the snapshot location must be on a file system shared by all nodes:

    {"taskId": "d9f3b1e4-..."}

  • Errors are JSON with the status and a message:

    {"status": 403, "message": "Verb [restore] of API [server:snapshot] is not exposed on this virtual host"}

    404 for an unknown path or item, 405 for a wrong method, 400 for an invalid body, 403 when the virtual host does not expose the verb.

  • Some paths have an alias, the name the operation had before. An alias behaves exactly like the path it aliases and belongs to the same verb: a virtual host that exposes prune on server:system exposes both /server:system/prune and /server:system/vacuum, and one that does not exposes neither.

Resources

Resource Verbs Purpose

server:app

list, install, pull, uninstall, start, stop, watch

Installed applications. install takes an uploaded bundle; pull fetches the bundle from a URL.

server:index

get, update, reindex

The search and storage indices of a repository: replica counts, and rebuilding the search index.

server:repo

list, get

Repository inventory.

server:export

list, create, load

Node exports under $XP_HOME/data/export.

server:dump

list, create, load, upgrade

System dumps under $XP_HOME/data/dump.

server:snapshot

list, create, restore, prune

Repository snapshots.

server:system

prune

Installation-wide maintenance (vacuum).

server:auditlog

prune

Audit log retention.

server:project

list

Content projects with their sites.

server:content

sync

Syncing inherited content from parent projects into child projects.

server:task

list, get, watch

The tasks the commands above hand out ids for.

server:scheduler

list, get, create, delete

Scheduled jobs.

server:idprovider

list

ID providers, as virtual hosts refer to them.

Universal APIs of installed applications with mount: "management" sit beside these, at /<application>:<api>, and are subject to the same virtual host policy if they choose to honour it - see Universal APIs on the management endpoint.

server:app

Installed applications.

Verb Request Description

list

GET /server:app

All installed applications with state and version: {"applications": […​]}.

install

POST /server:app/install (multipart, field file)

Installs the uploaded application bundle. Returns the application.

pull

POST /server:app/pull
alias /server:app/installUrl

Fetches and installs an application from URL; sha512 holds the expected digest. The URL must match the allow-list in com.enonic.xp.server.management.app.cfg, which also sets whether sha512 is required. That policy applies regardless of the virtual host the request arrived on.

uninstall

POST /server:app/uninstall

Uninstalls the applications named in key (a list).

start, stop

POST /server:app/start, POST /server:app/stop

Starts or stops the applications named in key.

watch

GET /server:app/watch (SSE)
alias /server:app/events

Server-sent events: a list event on connect, then installed, state and uninstalled events as applications change.
Pull an application
POST /server:app/pull
{
  "URL": "https://repo.enonic.com/public/com/enonic/app/contentstudio/6.0.0/contentstudio-6.0.0.jar",
  "sha512": "5b3c..."
}

server:index

The two Elasticsearch indices of a repository: search, holding the searchable representation, and storage, holding versions, branches and commits. The API exposes their replica settings.

Verb Request Description

get

GET /server:index/{repo}

Replica settings of both indices.

update

PUT /server:index/{repo}

Replaces the replica settings of both indices. Both keys are required. A value is either a number of replicas as a string ("2") or an Elasticsearch auto-expand range ("0-all", "0-1"); any other value is rejected with 400.

reindex

POST /server:index/{repo}/reindex

Rebuilds the search index from storage. branches limits the rebuild (default: every branch of the repository); initialize: true drops the index first. Returns a task.
Replicas
GET /server:index/com.enonic.cms.default

{"replicas": {"search": "1", "storage": "0-all"}}
Reindex the master branch
POST /server:index/com.enonic.cms.default/reindex
{"branches": ["master"], "initialize": false}
Index settings other than replicas are not exposed.

server:repo

Verb Request Description

list

GET /server:repo

Every repository with its branches: {"repositories": [{"id": "…​", "branches": ["draft", "master"]}]}.

get

GET /server:repo/{repo}

One repository.

server:export

Exports of a repository path, written to and read from $XP_HOME/data/export/<name>.zip. The API names an export without the .zip suffix; an archive copied into the directory under that name is what load reads.

Verb Request Description

list

GET /server:export

The exports on disk: {"exports": [{"name": "…​"}]}.

create

POST /server:export

Exports sourceRepoPath (<repository>:<branch>:<path>) as exportName. Optional batchSize. Returns a task.

load

POST /server:export/{name}/load

Imports the export into targetRepoPath. Optional importWithIds and importWithPermissions (default true). No XSLT transformation is applied; the legacy xslSource and xslParams keys are accepted and ignored. Returns a task.
Export and load
POST /server:export
{"sourceRepoPath": "com.enonic.cms.default:draft:/content/mysite", "exportName": "mysite"}

POST /server:export/mysite/load
{"targetRepoPath": "com.enonic.cms.staging:draft:/content", "importWithIds": true}

server:dump

System dumps under $XP_HOME/data/dump/<name>.

Verb Request Description

list

GET /server:dump

The dumps on disk with timestamp, version and size.

create

POST /server:dump

Dumps all repositories (or repositories) as name. includeVersions, maxAge, maxVersions as for the legacy API. Returns a task.

load

POST /server:dump/{name}/load

Loads the dump, replacing the current data. Optional body: upgrade, repositories. Returns a task.

upgrade

POST /server:dump/{name}/upgrade

Upgrades the dump on disk to the current model version. Returns a task.

server:snapshot

Verb Request Description

list

GET /server:snapshot

Every snapshot in the snapshot repository.

create

POST /server:snapshot

Snapshots all repositories, or repositoryId. Optional snapshotName. Returns a task.

restore

POST /server:snapshot/{name}/restore
POST /server:snapshot/restore with {"latest": true}

Restores a snapshot, replacing the current data. Optional repository, force. Returns a task.

prune

DELETE /server:snapshot/{name}
DELETE /server:snapshot?before=<ISO date-time>

Deletes one snapshot, or every snapshot taken before an instant.

server:system

Verb Request Description

prune

POST /server:system/prune
alias /server:system/vacuum

Removes unused blobs and old versions. Optional ageThreshold (ISO duration, e.g. PT48H) and tasks (the vacuum tasks to run). Returns a task.

server:auditlog

Verb Request Description

prune

POST /server:auditlog/prune
alias /server:auditlog/cleanup

Deletes audit log records older than ageThreshold (ISO duration, required). Returns a task.

server:project

Verb Request Description

list

GET /server:project

Every content project with its draft and master branches and the sites on each.

server:content

Verb Request Description

sync

POST /server:content/sync

Syncs inherited content from parent projects into child projects, parents first. Optional projects limits the sync to the named projects; without it every project is synced. Runs as a local task on the node that received the request. Returns a task.
Sync two projects
POST /server:content/sync
{"projects": ["intranet", "intranet-no"]}

server:task

Verb Request Description

list

GET /server:task
GET /server:task?running=true

All tasks on the cluster, or only the running ones.

get

GET /server:task/{id}

State, progress and description of one task - the id every 202 response returns.

watch

GET /server:task/watch (SSE)
GET /server:task/{id}/watch (SSE)
alias /events for both

Server-sent events. Without an id: a list event on connect whose data is {"tasks": [...]}, the shape of list, then submitted, updated, finished, failed and removed events for every task on the cluster. With an id: a task event with the task on connect, then the events of that task. The data of every event but list has the shape of get.
Watch one task
GET /server:task/d9f3b1e4-.../watch
Accept: text/event-stream

event: task
data: {"id":"d9f3b1e4-...","state":"RUNNING","progress":{"current":3,"total":10,"info":""},...}

event: finished
data: {"id":"d9f3b1e4-...","state":"FINISHED",...}

server:scheduler

Verb Request Description

list

GET /server:scheduler

Every scheduled job: {"jobs": […​]}, each with name, descriptor, calendar, enabled, config, user, lastRun, lastTaskId.

get

GET /server:scheduler/{name}

One scheduled job.

create

POST /server:scheduler

Creates a job. name, descriptor (the task to run) and schedule are required; description, config (the task’s config), enabled (default true) and user (the principal the task runs as) are optional. schedule.type is CRON (value a cron expression, timeZone required), ONE_TIME (value an ISO instant, optional deleteAfterRun) or FIXED_RATE (value an ISO duration). Returns 201 with the job.

delete

DELETE /server:scheduler/{name}

Deletes the job.
Dump every night at 03:00
POST /server:scheduler
{
  "name": "nightly-dump",
  "descriptor": "com.enonic.xp.app.system:dump",
  "schedule": {"type": "CRON", "value": "0 3 * * *", "timeZone": "Europe/Oslo"},
  "config": {"name": "nightly", "includeVersions": true},
  "user": "user:system:su"
}

server:idprovider

Verb Request Description

list

GET /server:idprovider

Every id provider: key, displayName, description and the applicationKey of the application implementing it. The provider configuration is never included.

Legacy REST API

The legacy endpoints are unchanged. They map to the resources as follows:

Legacy Resource Note

POST app/install, app/installUrl, app/start, app/stop, app/uninstall, GET app/events

server:app

installUrl and events remain as aliases of pull and watch.

POST repo/index/reindexTask

server:index reindex

POST repo/index/reindex

-

Deprecated. Synchronous; use server:index reindex.

POST repo/index/updateSettings

server:index update

Deprecated. Only replicas are exposed through server:index update.

GET repo/list

server:repo list

POST repo/export, repo/import

server:export create, load

Listing exports is new.

GET system/dump, POST system/dump, system/load, system/upgrade

server:dump

POST repo/snapshot, repo/snapshot/restore, repo/snapshot/delete, GET repo/snapshot/list

server:snapshot

POST system/vacuum

server:system prune

vacuum remains as an alias.

POST auditlog/cleanup

server:auditlog prune

cleanup remains as an alias.

GET content/projects/list

server:project list

POST content/syncAll

server:content sync

sync accepts a list of projects.

GET task/{taskId}

server:task get

Listing and watching tasks are new.

GET idproviders/list

server:idprovider list

GET scheduler/list

server:scheduler list

get, create and delete are new.

GET webapps/list

-

Not migrated; installed applications are node state.

Contents

Contents