Persistent servers API

Create a persistent server

A persistent server keeps one server configuration and does not scale to multiple instances like a group. The examples use the shared CloudApi client created in Installation and belong inside your plugin’s methods. 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

Use up to 100 ASCII letters, digits, underscores, or hyphens ([A-Za-z0-9_-]). Persistent server names are unique within the network.Name matching is case-insensitive, so Survival-1 and survival-1 identify the same persistent server. Creating or renaming a persistent server to a case-only variation of an existing name returns 409 Conflict.A persistent server and a group may share a name.

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.

Persistent server model

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

Persistent server model

​Create a persistent server

​Find persistent servers

​Update a persistent server

​Manage properties

​Delete a persistent server

​Persistent server model

Create a persistent server

Find persistent servers

Update a persistent server

Manage properties

Delete a persistent server

Persistent server model