Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/universeclouddev/Universe/llms.txt

Use this file to discover all available pages before exploring further.

Templates are the file trees that Universe copies into an instance’s working directory before starting it. They live under ./templates/<group>/<name>/ on each node. The Template API lets you inspect what templates exist, read and modify their files over HTTP, export or import them as zip archives, pull the latest version from a remote storage backend (e.g., S3), and trigger a cluster-wide sync via Hazelcast. All template endpoints require a Bearer token with ALL permission.
Template group and name together form the unique identity of a template (e.g., group server, name base → path ./templates/server/base/). Both are always required in path parameters.

​
Endpoints

​
GET /api/templates

Lists all templates available on this node, organized by group. Authentication: ALL permission required. 
curl http://localhost:8080/api/templates \
  -H "Authorization: Bearer YOUR_API_KEY"
Response — 200 OK An array of objects, each describing one template.
​
group
string
The template group name (e.g., server, global, lobby).
​
name
string
The template name within the group (e.g., base, default).
​
path
string
Absolute filesystem path to the template directory on this node.
[
  { "group": "server", "name": "base", "path": "/data/templates/server/base" },
  { "group": "lobby",  "name": "default", "path": "/data/templates/lobby/default" }
]
StatusMeaning
200List returned (may be empty).
401Unauthorized.

​
GET /api/templates//

Returns metadata for a specific template, including whether the template directory exists on this node. Authentication: ALL permission required. Path Parameters
​
group
string
required
Template group (e.g., server).
​
name
string
required
Template name within the group (e.g., base).
curl http://localhost:8080/api/templates/server/base \
  -H "Authorization: Bearer YOUR_API_KEY"
Response — 200 OK 
{
  "group": "server",
  "name": "base",
  "path": "/data/templates/server/base"
}
StatusMeaning
200Template found.
404Template directory does not exist on this node.
401Unauthorized.

​
GET /api/templates///files

Lists all files within the template directory as an array of relative paths. Authentication: ALL permission required. Path Parameters
​
group
string
required
Template group.
​
name
string
required
Template name.
curl http://localhost:8080/api/templates/server/base/files \
  -H "Authorization: Bearer YOUR_API_KEY"
Response — 200 OK
​
group
string
The template group.
​
name
string
The template name.
​
files
string[]
Array of relative file paths within the template directory (e.g., ["server.properties", "plugins/Universe/config.yml"]).
{
  "group": "server",
  "name": "base",
  "files": [
    "server.properties",
    "eula.txt",
    "plugins/Universe/config.yml"
  ]
}
StatusMeaning
200File list returned.
401Unauthorized.

​
GET /api/templates///files/

Returns the raw text content of a single file within the template. Responds with text/plain. Authentication: ALL permission required. Path Parameters
​
group
string
required
Template group.
​
name
string
required
Template name.
​
path
string
required
Relative path to the file within the template directory (e.g., server.properties, plugins/Universe/config.yml). Supports nested paths — Ktor captures all remaining path segments.
curl http://localhost:8080/api/templates/server/base/files/server.properties \
  -H "Authorization: Bearer YOUR_API_KEY"
Response — 200 OK — Raw file content as text/plain. 
server-port=%PORT%
online-mode=false
max-players=100
StatusMeaning
200File content returned as plain text.
404File does not exist.
401Unauthorized.

​
PATCH /api/templates///files/

Overwrites the content of an existing file in a local template (storage key local). The request body must be text/plain. Authentication: ALL permission required. Path Parameters
​
group
string
required
Template group.
​
name
string
required
Template name.
​
path
string
required
Relative path of the file to update.
curl -X PATCH http://localhost:8080/api/templates/server/base/files/server.properties \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary "server-port=%PORT%
online-mode=false
max-players=200"
Response — 200 OK 
{
  "message": "File updated",
  "path": "server.properties"
}
StatusMeaning
200File written successfully.
500Write failed (check node permissions).
401Unauthorized.

​
POST /api/templates///files/

Creates a new file in the template. Fails with 409 if the file already exists. Accepts any content type — use application/octet-stream for binary files such as JARs, images, or compressed archives. Authentication: ALL permission required. Path Parameters
​
group
string
required
Template group.
​
name
string
required
Template name.
​
path
string
required
Relative path for the new file. Intermediate directories are created automatically.
curl -X POST http://localhost:8080/api/templates/server/base/files/eula.txt \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "eula=true"
Response — 201 Created 
{
  "message": "File created",
  "path": "eula.txt"
}
StatusMeaning
201File created.
409File already exists. Use PATCH to update it.
401Unauthorized.

​
DELETE /api/templates///files/

Deletes a file from the template directory. Authentication: ALL permission required. Path Parameters
​
group
string
required
Template group.
​
name
string
required
Template name.
​
path
string
required
Relative path of the file to delete.
curl -X DELETE \
  http://localhost:8080/api/templates/server/base/files/old-plugin.jar \
  -H "Authorization: Bearer YOUR_API_KEY"
Response — 200 OK 
{
  "message": "File deleted",
  "path": "old-plugin.jar"
}
StatusMeaning
200File deleted.
500Delete failed.
401Unauthorized.

​
POST /api/templates///export

Exports the entire template directory as a .zip archive. The response is application/zip with a Content-Disposition: attachment header so browsers download it directly. Authentication: ALL permission required. Path Parameters
​
group
string
required
Template group.
​
name
string
required
Template name.
curl -X POST http://localhost:8080/api/templates/server/base/export \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o server-base.zip
Response — 200 OK — Binary zip content. The Content-Disposition header will be attachment; filename="server-base.zip".
StatusMeaning
200Zip archive streamed.
404Template not found.
401Unauthorized.

​
POST /api/templates///import

Imports a template from a zip archive, overwriting any existing files in the template directory. The request body must be application/zip. Authentication: ALL permission required. Path Parameters
​
group
string
required
Template group to import into.
​
name
string
required
Template name to import into.
curl -X POST http://localhost:8080/api/templates/server/base/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @server-base.zip
Response — 200 OK 
{
  "message": "Template imported",
  "group": "server",
  "name": "base"
}
StatusMeaning
200Import succeeded.
500Import failed (check zip format).
401Unauthorized.

​
POST /api/templates///sync

Downloads the latest version of a specific template from a registered remote storage provider and writes it to the local template directory. Authentication: ALL permission required. Path Parameters
​
group
string
required
Template group.
​
name
string
required
Template name.
Request Body
​
storage
string
required
Key of the registered storage provider to pull from (e.g., s3, ftp). Must match a provider registered via the TemplateStorageRegistry.
curl -X POST http://localhost:8080/api/templates/server/base/sync \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"storage": "s3"}'
Response — 200 OK 
{
  "message": "Template synced from s3",
  "group": "server",
  "name": "base",
  "storage": "s3"
}
StatusMeaning
200Sync succeeded.
400Storage provider key not found.
500Sync failed.
401Unauthorized.

​
POST /api/templates/sync

Dispatches a cluster-wide template sync task via Hazelcast. The pattern field supports glob-style matching to sync all matching templates across nodes. Authentication: ALL permission required. Request Body
​
pattern
string
required
Template sync pattern. Examples: default/* (all templates in the default group), server/base (a specific template), * (all templates).
curl -X POST http://localhost:8080/api/templates/sync \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pattern": "server/*"}'
Response — 200 OK 
{
  "message": "Sync triggered for pattern: server/*"
}
This endpoint is equivalent to running template sync server/* <node> in the Universe console. It is the recommended approach for pushing template updates to the entire cluster in one call.
StatusMeaning
200Sync task dispatched.
401Unauthorized.

Build docs developers (and LLMs) love

Get started for freeTalk to us