> ## Documentation Index
> Fetch the complete documentation index at: https://new-docs.simplecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud API

> Build integrations with SimpleCloud using our Java/Kotlin API

The Cloud API is a Java library for interacting with your SimpleCloud network programmatically. Use it to manage groups, servers, players, and react to events in real-time.

## API Architecture

| Method         | Returns     | Description                         |
| -------------- | ----------- | ----------------------------------- |
| `api.group()`  | `GroupApi`  | Create, read, update, delete groups |
| `api.server()` | `ServerApi` | Start, stop, query servers          |
| `api.player()` | `PlayerApi` | Player data, connections, messaging |
| `api.event()`  | `EventApi`  | Subscribe to real-time events       |

### Event API Subcategories

| Method                           | Description                |
| -------------------------------- | -------------------------- |
| `api.event().group()`            | Group lifecycle events     |
| `api.event().server()`           | Server lifecycle events    |
| `api.event().persistentServer()` | Persistent server events   |
| `api.event().blueprint()`        | Blueprint lifecycle events |

## Key Features

* **Async-first design** - All operations return `CompletableFuture` (Java) or suspend functions (Kotlin)
* **Type-safe models** - Strongly typed domain objects for Groups, Servers, Players
* **Real-time events** - Subscribe to changes via NATS messaging
* **Adventure integration** - Players implement Adventure's `Audience` for rich text messaging
* **Environment-aware** - Auto-configuration from `SIMPLECLOUD_*` environment variables

## Quick Example

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    // Initialize the API
    CloudApi api = CloudApi.create();

    // Get all servers in a group
    api.server().getServersByGroup("lobby").thenAccept(servers -> {
        System.out.println("Lobby servers: " + servers.size());
    });

    // Request a new server start for a group
    api.group().getGroupByName("lobby")
        .thenCompose(group -> {
            if (group == null) {
                return CompletableFuture.failedFuture(
                    new IllegalArgumentException("Group not found: lobby"));
            }
            return api.group().requestServerStart(group);
        })
        .thenRun(() -> System.out.println("Start request accepted for lobby"));

    // Send a message to a player (Adventure integration)
    api.player().get(playerUUID).thenAccept(player -> {
        if (player != null) {
            player.sendMessage(Component.text("Welcome!").color(NamedTextColor.GREEN));
        }
    });

    // Subscribe to server events
    Subscription sub = api.event().server().onStarted(event -> {
        System.out.println("Server started: " + event.getServerId());
    });
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    // Initialize the API
    val api = CloudApi.create()

    // Get all servers in a group
    val servers = api.server().getServersByGroup("lobby").await()
    println("Lobby servers: ${servers.size}")

    // Request a new server start for a group
    val group = api.group().getGroupByName("lobby").await()
    requireNotNull(group) { "Group not found: lobby" }

    api.group().requestServerStart(group).await()
    println("Start request accepted for lobby")

    // Send a message to a player (Adventure integration)
    api.player().get(playerUUID).await()?.let { player ->
        player.sendMessage(Component.text("Welcome!").color(NamedTextColor.GREEN))
    }

    // Subscribe to server events
    val sub = api.event().server().onStarted { event ->
        println("Server started: ${event.serverId}")
    }
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/en/developer/installation">
    Add the Cloud API to your project
  </Card>

  <Card title="Servers API" icon="server" href="/en/developer/api/servers">
    Manage server instances
  </Card>

  <Card title="Players API" icon="users" href="/en/developer/api/players">
    Player data and messaging
  </Card>

  <Card title="Events API" icon="bell" href="/en/developer/api/events">
    React to real-time changes
  </Card>
</CardGroup>