Persistent Servers API

A persistent server is one long-lived server configuration, such as a survival server. Unlike a group, it does not scale into multiple instances. Use api.persistentServer() to create and manage persistent servers.

Create a persistent server

This example creates survival-1 with a new Paper blueprint. Because the persistent server is active, SimpleCloud starts its instance and replaces it after a stop.

CreatePersistentServerRequest request = CreatePersistentServerRequest.builder()
    .name("survival-1")
    .type(GroupServerType.SERVER)
    .minMemory(2048)
    .maxMemory(4096)
    .maxPlayers(80)
    .createBlueprint(CreateBlueprintRequest.builder()
        .configurator("paper")
        .serverSoftware("paper")
        .minecraftVersion("1.21.11")
        .build())
    .active(true)
    .serverhostId("serverhost-uuid")
    .tags(List.of("survival", "production"))
    .build();

api.persistentServer().createPersistentServer(request)
    .thenAccept(server -> System.out.println(
        "Created " + server.getName() + " with ID " + server.getPersistentServerId()));

To use an existing blueprint instead, replace createBlueprint(...) with a source:

.source(SourceConfig.builder()
    .type(SourceType.BLUEPRINT)
    .blueprint("blueprint-uuid")
    .build())

Set either source or createBlueprint, not both.

CreatePersistentServerRequest fields

string

required

Persistent server name. Up to 100 characters of ASCII letters, digits, underscores, and hyphens ([A-Za-z0-9_-]). Must be unique within the network, case-insensitive — Survival-1 and survival-1 are treated as the same name. A persistent server and a group may share a name. Creating or renaming to a name that only differs by case from an existing persistent server returns 409 Conflict.

GroupServerType | null

SERVER or PROXY. Defaults to SERVER.

integer | null

Minimum memory in MB.

integer | null

Maximum memory in MB.

integer | null

Player limit. Defaults to 50.

CreateBlueprintRequest | null

Blueprint to create for this persistent server.

SourceConfig | null

Existing blueprint or container image to use. Do not set this together with createBlueprint.

boolean | null

Whether SimpleCloud should keep an instance running. Defaults to true.

integer | null

Persistent server priority.

string | null

ID of the assigned serverhost.

WorkflowsConfig | null

Lifecycle and manual workflows.

Map<String, Object> | null

Custom properties.

List<String> | null

Tags used to organize and filter persistent servers.

Find persistent servers

Find one persistent server by name or ID:

api.persistentServer().getPersistentServerByName("survival-1")
    .thenAccept(server -> System.out.println(server.getPersistentServerId()));

api.persistentServer().getPersistentServerById("persistent-server-uuid")
    .thenAccept(server -> System.out.println(server.getName()));

Both methods complete exceptionally when no persistent server matches. Name lookups are case-insensitive. Use a query to filter the list:

PersistentServerQuery query = PersistentServerQuery.create()
    .filterByActive(true)
    .filterByTags("survival", "production")
    .limit(20);

api.persistentServer().getAllPersistentServers(query)
    .thenAccept(servers -> servers.forEach(server ->
        System.out.println(server.getName() + ": " + server.getPlayerCount())));

The query can filter by tags, active state, and serverhost ID. Call getAllPersistentServers() without a query to return every persistent server.

Update a persistent server

Only fields set on UpdatePersistentServerRequest are changed:

UpdatePersistentServerRequest update = UpdatePersistentServerRequest.builder()
    .maxMemory(6144)
    .maxPlayers(100)
    .build();

api.persistentServer()
    .updatePersistentServer("persistent-server-uuid", update)
    .thenAccept(server -> System.out.println("Updated " + server.getName()));

You can update the name, type, memory, player limit, active state, priority, assigned serverhost, source, workflows, properties, and tags.

Manage properties

Use the property methods to change custom properties without updating the rest of the configuration:

api.persistentServer().updatePersistentServerProperties(
    "persistent-server-uuid",
    Map.of("gameMode", "SURVIVAL", "region", "eu-central")
).thenAccept(properties -> System.out.println("Properties: " + properties));

api.persistentServer()
    .deletePersistentServerProperty("persistent-server-uuid", "region")
    .thenAccept(properties -> System.out.println("Properties: " + properties));

updatePersistentServerProperties merges the supplied values with the existing properties. You can also update one property or delete multiple properties.

Delete a persistent server

api.persistentServer()
    .deletePersistentServer("persistent-server-uuid")
    .thenRun(() -> System.out.println("Deleted persistent server"));

Deactivate the persistent server first, stop its instance, and delete the configuration after the instance stops. Its files remain on the serverhost.

PersistentServer fields

PersistentServer extends ServerBase and provides the following fields.

string

required

Unique persistent server ID.

string

required

Persistent server name.

GroupServerType

required

SERVER, PROXY, or UNKNOWN_SERVER.

integer | null

Minimum memory in MB.

integer | null

Maximum memory in MB.

integer | null

Player limit.

boolean | null

Whether SimpleCloud should keep an instance running.

integer | null

Persistent server priority.

string | null

Assigned serverhost ID.

integer

required

Current player count, or 0 when no instance is running.

SourceConfig | null

Blueprint or container image source.

WorkflowsConfig | null

Lifecycle and manual workflows.

Map<String, Object> | null

Custom properties.

List<String> | null

Tags used for filtering and organization.

string

required

Creation timestamp in ISO 8601 format.

string

required

Last update timestamp in ISO 8601 format.

Use api.server() to work with the running instance. Its getPersistentServerId() method links it back to this configuration.

Getting Started

Cloud API

Guides

REST API Reference

Persistent Servers API

Create a persistent server

Find persistent servers

Update a persistent server

Manage properties

Delete a persistent server

PersistentServer fields

​Create a persistent server

​Find persistent servers

​Update a persistent server

​Manage properties

​Delete a persistent server

​PersistentServer fields

Create a persistent server

Find persistent servers

Update a persistent server

Manage properties

Delete a persistent server

PersistentServer fields