### HTTP Server Initialization

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Configure and start an HTTP server programmatically.

```APIDOC
## HTTP Server Initialization

### Description
Configure and start an HTTP server programmatically.

### Method
N/A (Programmatic Initialization)

### Endpoint
N/A (Programmatic Initialization)

### Parameters
None

### Request Example
```java
// Example usage within Java code
import eu.cloudnetservice.ext.rest.api.HttpServer;
import eu.cloudnetservice.ext.rest.api.factory.HttpComponentFactoryLoader;
import eu.cloudnetservice.ext.rest.api.config.HttpComponentConfig;
import eu.cloudnetservice.ext.rest.api.util.HostAndPort;

public class ServerExample {

  public void initializeServer() {
    // Create component configuration
    var config = HttpComponentConfig.builder()
      .build();

    // Load HTTP server factory
    var factory = HttpComponentFactoryLoader
      .getFirstComponentFactory(HttpServer.class);

    // Create server instance
    var server = factory.construct(config);

    // Register HTTP handlers
    server.annotationParser()
      .parseAndRegister(new CustomHttpHandler())
      .parseAndRegister(new AnotherHandler());

    // Add listeners (bind ports)
    server.addListener(2812).join();
    server.addListener(HostAndPort.fromParts("0.0.0.0", 8080)).join();

    System.out.println("HTTP Server started on ports 2812 and 8080");
  }
}
```

### Response
None (Programmatic Initialization)
```

--------------------------------

### Custom Authentication Provider

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Demonstrates how to implement a custom authentication provider by extending the `AuthProvider` interface. This example shows custom token validation.

```APIDOC
## Custom Authentication

### Description
This section details the implementation of a custom authentication provider that uses a specific header (`X-Custom-Auth`) for authentication.

### Method
Any (This applies globally or to specific endpoints configured to use this provider)

### Endpoint
N/A (Provider implementation)

### Authentication Logic
1. **Header Check**: Looks for the `X-Custom-Auth` header in the request.
2. **Token Validation**: Validates the format of the token (e.g., starts with `CUSTOM_` and has a minimum length).
3. **Username Extraction**: Extracts the username from the validated token.
4. **User Verification**: Verifies the existence of the user using a `RestUserManagement` instance.

### Authentication Result
- **MISSING_CREDENTIALS**: If the `X-Custom-Auth` header is not present.
- **INVALID_CREDENTIALS**: If the token format is invalid or the extracted user does not exist.
- **authenticated(user)**: If authentication is successful, returns the authenticated user object.

### Provider Details
- **Name**: `custom`
- **Priority**: `AuthProvider.DEFAULT_PRIORITY + 5`
```

--------------------------------

### Initialize HTTP Server

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Configures and starts an HTTP server programmatically. It involves creating component configuration, loading the HTTP server factory, constructing the server instance, registering HTTP handlers, and adding listeners to bind ports. Dependencies include eu.cloudnetservice.ext.rest libraries.

```java
import eu.cloudnetservice.ext.rest.api.HttpServer;
import eu.cloudnetservice.ext.rest.api.factory.HttpComponentFactoryLoader;
import eu.cloudnetservice.ext.rest.api.config.HttpComponentConfig;
import eu.cloudnetservice.ext.rest.api.util.HostAndPort;

public class ServerExample {

  public void initializeServer() {
    // Create component configuration
    var config = HttpComponentConfig.builder()
      .build();

    // Load HTTP server factory
    var factory = HttpComponentFactoryLoader
      .getFirstComponentFactory(HttpServer.class);

    // Create server instance
    var server = factory.construct(config);

    // Register HTTP handlers
    server.annotationParser()
      .parseAndRegister(new CustomHttpHandler())
      .parseAndRegister(new AnotherHandler());

    // Add listeners (bind ports)
    server.addListener(2812).join();
    server.addListener(HostAndPort.fromParts("0.0.0.0", 8080)).join();

    System.out.println("HTTP Server started on ports 2812 and 8080");
  }
}
```

--------------------------------

### Register REST Handlers with Annotations (Java)

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

This Java code snippet illustrates how to register REST endpoints using CloudNetService's annotation-based approach. It defines GET, POST, and DELETE handlers with path parameters, request bodies, and authentication scopes. Requires CloudNetService REST extension and Lombok. Input is via HTTP requests, output via JSON responses or HTTP status codes.

```java
import eu.cloudnetservice.ext.rest.api.annotation.RequestHandler;
import eu.cloudnetservice.ext.rest.api.annotation.Authentication;
import eu.cloudnetservice.ext.rest.api.annotation.RequestPathParam;
import eu.cloudnetservice.ext.rest.api.annotation.RequestTypedBody;
import eu.cloudnetservice.ext.rest.api.HttpMethod;
import eu.cloudnetservice.ext.rest.api.response.IntoResponse;
import eu.cloudnetservice.ext.rest.api.response.type.JsonResponse;
import jakarta.inject.Singleton;
import lombok.NonNull;

@Singleton
public class CustomHttpHandler {

  // GET endpoint with path parameter
  @RequestHandler(path = "/api/v3/custom/{id}")
  @Authentication(providers = "jwt", scopes = {"custom:read"})
  public @NonNull IntoResponse<?> handleGetRequest(
    @NonNull @RequestPathParam("id") String id
  ) {
    var data = Map.of(
      "id", id,
      "message", "Retrieved successfully",
      "timestamp", System.currentTimeMillis()
    );
    return JsonResponse.builder().body(data);
  }

  // POST endpoint with request body validation
  @RequestHandler(path = "/api/v3/custom", method = HttpMethod.POST)
  @Authentication(providers = "jwt", scopes = {"custom:write"})
  public @NonNull IntoResponse<?> handleCreateRequest(
    @Valid @RequestTypedBody CustomDto dto
  ) {
    // Process the validated DTO
    processCustomData(dto);
    return HttpResponseCode.CREATED;
  }

  // DELETE endpoint with authorization
  @RequestHandler(path = "/api/v3/custom/{id}", method = HttpMethod.DELETE)
  @Authentication(providers = "jwt", scopes = {"custom:delete"})
  public @NonNull IntoResponse<?> handleDeleteRequest(
    @NonNull @RequestPathParam("id") String id
  ) {
    deleteResource(id);
    return HttpResponseCode.NO_CONTENT;
  }

  private void processCustomData(CustomDto dto) {
    // Implementation
  }

  private void deleteResource(String id) {
    // Implementation
  }
}
```

--------------------------------

### Get Player Information

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Retrieves information about online players. This includes fetching the total online player count or details of a specific player by their UUID or name. An authorization token is required.

```bash
# Get online player count
curl -X GET http://127.0.0.1:2812/api/v3/player/onlineCount \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

# Response: {"count": 42}

# Get specific online player by UUID or name
curl -X GET http://127.0.0.1:2812/api/v3/player/online/Notch \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

# Response:
{
  "uniqueId": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "name": "Notch",
  "firstLoginTimeMillis": 1735300000000,
  "lastLoginTimeMillis": 1735390080000,
  "loginService": {
    "uniqueId": "service-uuid",
    "serverName": "Proxy-1"
  },
  "connectedService": {
    "uniqueId": "service-uuid",
    "serverName": "Lobby-1"
  },
  "networkPlayerProxyInfo": {
    "online": true,
    "version": 763
  }
}
```

--------------------------------

### Custom HTTP Handler API

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Define and manage custom REST endpoints using Java annotations. Supports GET, POST, and DELETE methods with authentication and path parameters.

```APIDOC
## GET /api/v3/custom/{id}

### Description
Retrieves custom data associated with a specific ID.

### Method
GET

### Endpoint
`/api/v3/custom/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the custom data.

### Authentication
- **Providers**: jwt
- **Scopes**: custom:read

### Response
#### Success Response (200)
- **id** (string) - The identifier of the retrieved data.
- **message** (string) - A confirmation message.
- **timestamp** (integer) - The timestamp of the request.

#### Response Example
```json
{
  "id": "some-id",
  "message": "Retrieved successfully",
  "timestamp": 1678886400000
}
```

## POST /api/v3/custom

### Description
Creates new custom data. Requires a valid request body and authentication.

### Method
POST

### Endpoint
`/api/v3/custom`

### Parameters
#### Request Body
- **dto** (object) - Required - The data transfer object containing the custom data to be created. Assumed to have fields validated by `@Valid` annotation.

### Authentication
- **Providers**: jwt
- **Scopes**: custom:write

### Response
#### Success Response (201 Created)
- (No specific response body documented, typically indicates success)

## DELETE /api/v3/custom/{id}

### Description
Deletes custom data associated with a specific ID.

### Method
DELETE

### Endpoint
`/api/v3/custom/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the custom data to delete.

### Authentication
- **Providers**: jwt
- **Scopes**: custom:delete

### Response
#### Success Response (204 No Content)
- (No response body, indicates successful deletion)
```

--------------------------------

### Get Specific Service Details via REST API

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Retrieve detailed information about a specific service identified by its unique ID or name. This endpoint requires JWT authentication. The response provides comprehensive configuration and runtime state of the requested service.

```bash
# Get service by unique ID or name
curl -X GET http://127.0.0.1:2812/api/v3/service/Lobby-1 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Accept: application/json"

# Response includes full service configuration and runtime state
{
  "serviceId": {
    "taskName": "Lobby",
    "taskServiceId": 1,
    "uniqueId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "state": "RUNNING",
  "processSnapshot": {
    "pid": 12345,
    "cpuUsage": 15.5,
    "systemCpuUsage": 45.2,
    "maxHeapMemory": 536870912,
    "heapUsageMemory": 268435456
  }
}
```

--------------------------------

### Manage Service Templates (cURL)

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

These cURL commands demonstrate template management operations for CloudNetService deployments. They cover checking template existence, creating new templates, and listing directory contents within a template. Requires a running CloudNetService instance and valid authentication token. Input is via command-line arguments and headers; output is JSON.

```bash
# Check if template exists
curl -X GET "http://127.0.0.1:2812/api/v3/template/local/Lobby/default/exists" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

# Response: {"exists": true}

# Create new template
curl -X POST "http://127.0.0.1:2812/api/v3/template/local/Lobby/default/create" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

# List directory contents in template
curl -X GET "http://127.0.0.1:2812/api/v3/template/local/Lobby/default/directory/list?path=plugins" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

# Response:
{
  "files": [
    {
      "path": "plugins/CloudNet-Bridge.jar",
      "directory": false,
      "size": 2048576,
      "lastModified": 1735300000000
    }
  ]
}
```

--------------------------------

### Task Management

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Endpoints for creating and managing service task configurations.

```APIDOC
## Create Service Task

### Description
Defines and creates a new service task configuration, which CloudNet uses for automatic service provisioning.

### Method
POST

### Endpoint
/api/v3/task

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - "Bearer [JWT Access Token]"
- **Content-Type** (string) - Required - "application/json"

#### Request Body
- **name** (string) - Required - The name of the task.
- **minServiceCount** (integer) - Required - The minimum number of services to keep running for this task.
- **maintenance** (boolean) - Required - Whether the task is in maintenance mode.
- **autoDeleteOnStop** (boolean) - Required - Whether services of this task should be deleted automatically when stopped.
- **staticServices** (boolean) - Required - Whether services created by this task are static.
- **groups** (array[string]) - Required - A list of groups this task belongs to.
- **processConfiguration** (object) - Required - Configuration for the service processes.
  - **environment** (string) - Required - The runtime environment (e.g., VELOCITY, MINECRAFT_SERVER).
  - **maxHeapMemorySize** (integer) - Required - Maximum heap memory in MB.
  - **jvmOptions** (array[string]) - Optional - JVM options for the process.
- **startPort** (integer) - Optional - The starting network port for services of this task.
- **templates** (array[object]) - Required - List of templates to deploy for the services.
  - **storage** (string) - Required - The storage type for the template (e.g., "local").
  - **prefix** (string) - Required - The prefix of the template.
  - **name** (string) - Required - The name of the template.
- **deployments** (array[object]) - Optional - Deployment configurations for services.
  - **template** (object) - Required - The template to deploy.
    - **storage** (string) - Required - The storage type for the template.
    - **prefix** (string) - Required - The prefix of the template.
    - **name** (string) - Required - The name of the template.
  - **excludes** (array[string]) - Optional - A list of files/patterns to exclude from deployment.

### Request Example
```json
{
  "name": "Proxy",
  "minServiceCount": 1,
  "maintenance": false,
  "autoDeleteOnStop": true,
  "staticServices": false,
  "groups": ["proxy"],
  "processConfiguration": {
    "environment": "VELOCITY",
    "maxHeapMemorySize": 512,
    "jvmOptions": ["-XX:+UseG1GC", "-XX:MaxGCPauseMillis=50"]
  },
  "startPort": 25565,
  "templates": [
    {
      "storage": "local",
      "prefix": "Proxy",
      "name": "default"
    }
  ],
  "deployments": [
    {
      "template": {
        "storage": "local",
        "prefix": "Proxy",
        "name": "default"
      },
      "excludes": ["*.log", "*.tmp"]
    }
  ]
}
```

### Response
#### Success Response (204 No Content)
Indicates that the task configuration was successfully created or updated.

#### Error Response
- **400 Bad Request**: If the request body is invalid or missing required fields.
- **409 Conflict**: If a task with the same name already exists.
- **403 Forbidden**: If the authenticated user lacks the necessary permissions.
```

--------------------------------

### Template Management API

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Endpoints for creating, checking the existence of, and listing directory contents for service templates.

```APIDOC
## GET /api/v3/template/local/{node}/exists

### Description
Checks if a service template with the given name exists on the specified node.

### Method
GET

### Endpoint
`/api/v3/template/local/{node}/{templateName}/exists`

### Parameters
#### Path Parameters
- **node** (string) - Required - The name of the node where the template resides.
- **templateName** (string) - Required - The name of the template to check.

### Response
#### Success Response (200)
- **exists** (boolean) - Indicates whether the template exists.

#### Response Example
```json
{
  "exists": true
}
```

## POST /api/v3/template/local/{node}/{templateName}/create

### Description
Creates a new local service template on the specified node.

### Method
POST

### Endpoint
`/api/v3/template/local/{node}/{templateName}/create`

### Parameters
#### Path Parameters
- **node** (string) - Required - The name of the node to create the template on.
- **templateName** (string) - Required - The name of the template to create.

### Response
#### Success Response (200/201)
- (No specific response body documented, typically indicates success)

## GET /api/v3/template/local/{node}/{templateName}/directory/list

### Description
Lists the contents of a directory within a specified service template on a given node.

### Method
GET

### Endpoint
`/api/v3/template/local/{node}/{templateName}/directory/list`

### Parameters
#### Path Parameters
- **node** (string) - Required - The name of the node where the template resides.
- **templateName** (string) - Required - The name of the template.
#### Query Parameters
- **path** (string) - Required - The path to the directory within the template whose contents should be listed.

### Response
#### Success Response (200)
- **files** (array) - A list of file objects within the specified directory.
  - **path** (string) - The path of the file or directory.
  - **directory** (boolean) - True if the entry is a directory, false otherwise.
  - **size** (integer) - The size of the file in bytes.
  - **lastModified** (integer) - The last modified timestamp of the file or directory.

#### Response Example
```json
{
  "files": [
    {
      "path": "plugins/CloudNet-Bridge.jar",
      "directory": false,
      "size": 2048576,
      "lastModified": 1735300000000
    }
  ]
}
```
```

--------------------------------

### Implement Custom Authentication Provider (Java)

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

This Java code demonstrates implementing a custom authentication provider for CloudNetService's REST API. It extends the `AuthProvider` interface to handle custom authentication headers ('X-Custom-Auth'), validate tokens, and extract user information. Requires CloudNetService REST extension and Lombok. Authentication logic is custom, and the priority can be adjusted.

```java
import eu.cloudnetservice.ext.rest.api.auth.AuthProvider;
import eu.cloudnetservice.ext.rest.api.auth.AuthenticationResult;
import eu.cloudnetservice.ext.rest.api.auth.RestUserManagement;
import eu.cloudnetservice.ext.rest.api.HttpContext;
import lombok.NonNull;

public class CustomAuthProvider implements AuthProvider {

  @Override
  public @NonNull String name() {
    return "custom";
  }

  @Override
  public @NonNull AuthenticationResult tryAuthenticate(
    @NonNull HttpContext context,
    @NonNull RestUserManagement userManagement
  ) {
    // Extract custom authentication header
    var authHeader = context.request().header("X-Custom-Auth");
    if (authHeader == null) {
      return AuthenticationResult.MISSING_CREDENTIALS;
    }

    // Validate custom token format
    if (!isValidCustomToken(authHeader)) {
      return AuthenticationResult.INVALID_CREDENTIALS;
    }

    // Extract user from token and validate
    var username = extractUsername(authHeader);
    var user = userManagement.user(username);

    if (user == null) {
      return AuthenticationResult.INVALID_CREDENTIALS;
    }

    // Return authenticated user
    return AuthenticationResult.authenticated(user);
  }

  @Override
  public int priority() {
    return AuthProvider.DEFAULT_PRIORITY + 5;
  }

  private boolean isValidCustomToken(String token) {
    // Custom validation logic
    return token.startsWith("CUSTOM_") && token.length() > 20;
  }

  private String extractUsername(String token) {
    // Extract username from custom token
    return token.substring(7, token.indexOf('_', 7));
  }
}
```

--------------------------------

### Create Service Task Configuration via REST API

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Define a new service task configuration for automatic service provisioning. This endpoint requires JWT authentication and a JSON payload detailing the task's properties, including name, process configuration, templates, and deployments.

```bash
# Create a new task configuration
curl -X POST http://127.0.0.1:2812/api/v3/task \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Proxy",
    "minServiceCount": 1,
    "maintenance": false,
    "autoDeleteOnStop": true,
    "staticServices": false,
    "groups": ["proxy"],
    "processConfiguration": {
      "environment": "VELOCITY",
      "maxHeapMemorySize": 512,
      "jvmOptions": ["-XX:+UseG1GC", "-XX:MaxGCPauseMillis=50"]
    },
    "startPort": 25565,
    "templates": [
      {
        "storage": "local",
        "prefix": "Proxy",
        "name": "default"
      }
    ],
    "deployments": [
      {
        "template": {
          "storage": "local",
          "prefix": "Proxy",
          "name": "default"
        },
        "excludes": ["*.log", "*.tmp"]
      }
    ]
  }'

# Response: 204 No Content (success)
```

--------------------------------

### Manage REST Users

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Enables the creation and management of REST API users. Users can be created with specific scopes to control their access permissions. Existing users can be listed and their scopes updated. Requires authorization.

```bash
# Create new REST user
curl -X POST http://127.0.0.1:2812/api/v3/user \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{ 
    "username": "api_user",
    "password": "securePassword456",
    "scopes": [
      "cloudnet_rest:service_read",
      "cloudnet_rest:service_list",
      "cloudnet_rest:task_read"
    ]
  }'

# Response:
{
  "uniqueId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "username": "api_user",
  "scopes": [
    "cloudnet_rest:service_read",
    "cloudnet_rest:service_list",
    "cloudnet_rest:task_read"
  ],
  "createdAt": "2025-12-28T13:08:00Z"
}

# List all REST users
curl -X GET http://127.0.0.1:2812/api/v3/user \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

# Update user scopes
curl -X PUT http://127.0.0.1:2812/api/v3/user/b2c3d4e5-f6a7-8901-bcde-f23456789012 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{ 
    "username": "api_user",
    "password": "securePassword456",
    "scopes": [
      "cloudnet_rest:service_read",
      "cloudnet_rest:service_write",
      "cloudnet_rest:task_read",
      "cloudnet_rest:task_write"
    ]
  }'
```

--------------------------------

### List Service Tasks

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Retrieves a list of all configured service tasks within the CloudNet environment.

```APIDOC
## List Service Tasks

### Description
Retrieve all configured service tasks.

### Method
GET

### Endpoint
/api/v3/task

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET http://127.0.0.1:2812/api/v3/task \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **tasks** (array) - An array of task objects.
  - **name** (string) - The name of the task.
  - **minServiceCount** (integer) - The minimum number of services to run for this task.
  - **maintenance** (boolean) - Whether the task is in maintenance mode.
  - **autoDeleteOnStop** (boolean) - Whether services should be auto-deleted when stopped.
  - **processConfiguration** (object) - Configuration for the service processes.
    - **environment** (string) - The environment of the service process (e.g., MINECRAFT_SERVER).
    - **maxHeapMemorySize** (integer) - The maximum heap memory size for the process.
  - **startPort** (integer) - The starting port for services in this task.
  - **groups** (array) - An array of group names associated with the task.

#### Response Example
```json
{
  "tasks": [
    {
      "name": "Lobby",
      "minServiceCount": 2,
      "maintenance": false,
      "autoDeleteOnStop": true,
      "processConfiguration": {
        "environment": "MINECRAFT_SERVER",
        "maxHeapMemorySize": 512
      },
      "startPort": 30000
    },
    {
      "name": "Proxy",
      "minServiceCount": 1,
      "maintenance": false,
      "groups": ["proxy"]
    }
  ]
}
```
```

--------------------------------

### List All Services via REST API

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Retrieve a list of all running services within the CloudNet cluster. This endpoint requires JWT authentication. The response contains an array of service objects, each detailing a running service.

```bash
# List all services using JWT authentication
curl -X GET http://127.0.0.1:2812/api/v3/service \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Accept: application/json"

# Response:
{
  "services": [
    {
      "serviceId": {
        "taskName": "Lobby",
        "taskServiceId": 1,
        "nodeUniqueId": "Node-1",
        "uniqueId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "nameSplitter": "-",
        "allowedNodes": []
      },
      "state": "RUNNING",
      "configuration": {
        "processConfig": {
          "environment": "MINECRAFT_SERVER",
          "maxHeapMemorySize": 512,
          "jvmOptions": ["-XX:+UseG1GC"]
        },
        "port": 25565,
        "autoDeleteOnStop": false,
        "staticService": false
      },
      "connectedTime": 1735390080000,
      "lifeCycle": "RUNNING"
    }
  ]
}
```

--------------------------------

### List Service Tasks

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Retrieves a list of all configured service tasks within the CloudNet cluster. This endpoint requires an active authorization token. The response includes details about each task's configuration.

```bash
# List all tasks
curl -X GET http://127.0.0.1:2812/api/v3/task \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Accept: application/json"

# Response:
{
  "tasks": [
    {
      "name": "Lobby",
      "minServiceCount": 2,
      "maintenance": false,
      "autoDeleteOnStop": true,
      "processConfiguration": {
        "environment": "MINECRAFT_SERVER",
        "maxHeapMemorySize": 512
      },
      "startPort": 30000
    },
    {
      "name": "Proxy",
      "minServiceCount": 1,
      "maintenance": false,
      "groups": ["proxy"]
    }
  ]
}
```

--------------------------------

### JWT Authentication and Token Generation

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Authenticate using Basic Auth credentials to obtain JWT access and refresh tokens. These tokens are required for subsequent authenticated API requests. The request body specifies the desired scopes for the tokens.

```bash
# Create a REST user first (execute on CloudNet console)
rest user create admin secretPassword123

# Authenticate and get JWT tokens
curl -X POST http://127.0.0.1:2812/api/v3/auth \
  -H "Authorization: Basic YWRtaW46c2VjcmV0UGFzc3dvcmQxMjM=" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["cloudnet_rest:service_read", "cloudnet_rest:service_write"]
  }'

# Response:
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2025-12-29T13:08:00Z",
  "tokenType": "Bearer"
}
```

--------------------------------

### REST User Management API

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

API for creating, listing, and updating REST users, managing their scopes for API access.

```APIDOC
## Create REST User

### Description
Creates a new REST user with specified username, password, and scopes.

### Method
POST

### Endpoint
/api/v3/user

### Parameters
#### Request Body
- **username** (string) - Required - The username for the new REST user.
- **password** (string) - Required - The password for the new REST user.
- **scopes** (array of strings) - Required - A list of scopes to grant to the user.

### Request Example
```bash
curl -X POST http://127.0.0.1:2812/api/v3/user \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{ "username": "api_user", "password": "securePassword456", "scopes": ["cloudnet_rest:service_read", "cloudnet_rest:service_list", "cloudnet_rest:task_read"] }'
```

### Response
#### Success Response (201 Created)
- **uniqueId** (string) - The unique ID of the newly created user.
- **username** (string) - The username of the created user.
- **scopes** (array of strings) - The scopes granted to the user.
- **createdAt** (string) - The timestamp when the user was created (ISO 8601 format).

#### Response Example
```json
{
  "uniqueId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "username": "api_user",
  "scopes": [
    "cloudnet_rest:service_read",
    "cloudnet_rest:service_list",
    "cloudnet_rest:task_read"
  ],
  "createdAt": "2025-12-28T13:08:00Z"
}
```

---

## List REST Users

### Description
Retrieves a list of all configured REST users.

### Method
GET

### Endpoint
/api/v3/user

### Parameters
None

### Request Example
```bash
curl -X GET http://127.0.0.1:2812/api/v3/user \
  -H "Authorization: Bearer <your_jwt_token>"
```

### Response
#### Success Response (200)
- An array of user objects, each containing `uniqueId`, `username`, `scopes`, and `createdAt`.

---

## Update REST User

### Description
Updates an existing REST user's details, including password and scopes.

### Method
PUT

### Endpoint
/api/v3/user/{user_unique_id}

### Parameters
#### Path Parameters
- **user_unique_id** (string) - Required - The unique ID of the user to update.

#### Request Body
- **username** (string) - Optional - The updated username.
- **password** (string) - Optional - The updated password.
- **scopes** (array of strings) - Optional - The updated list of scopes.

### Request Example
```bash
curl -X PUT http://127.0.0.1:2812/api/v3/user/b2c3d4e5-f6a7-8901-bcde-f23456789012 \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{ "username": "api_user", "password": "securePassword456", "scopes": ["cloudnet_rest:service_read", "cloudnet_rest:service_write", "cloudnet_rest:task_read", "cloudnet_rest:task_write"] }'
```

### Response
#### Success Response (200)
- The updated user object, containing `uniqueId`, `username`, `scopes`, and `createdAt`.
```

--------------------------------

### Player Information API

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Provides endpoints to retrieve information about online players and manage their connections.

```APIDOC
## Get Player Information

### Description
Retrieve information about online players.

### Method
GET

### Endpoint
/api/v3/player/onlineCount

### Parameters
None

### Request Example
```bash
curl -X GET http://127.0.0.1:2812/api/v3/player/onlineCount \
  -H "Authorization: Bearer <your_jwt_token>"
```

### Response
#### Success Response (200)
- **count** (integer) - The number of currently online players.

#### Response Example
```json
{"count": 42}
```

---

## Get Specific Online Player

### Description
Retrieve information about a specific online player by their UUID or name.

### Method
GET

### Endpoint
/api/v3/player/online/{name_or_uuid}

### Parameters
#### Path Parameters
- **name_or_uuid** (string) - The name or UUID of the player.

### Request Example
```bash
curl -X GET http://127.0.0.1:2812/api/v3/player/online/Notch \
  -H "Authorization: Bearer <your_jwt_token>"
```

### Response
#### Success Response (200)
- **uniqueId** (string) - The unique ID of the player.
- **name** (string) - The name of the player.
- **firstLoginTimeMillis** (integer) - Timestamp of the player's first login in milliseconds.
- **lastLoginTimeMillis** (integer) - Timestamp of the player's last login in milliseconds.
- **loginService** (object) - Information about the service the player logged into.
  - **uniqueId** (string) - The unique ID of the login service.
  - **serverName** (string) - The name of the login server.
- **connectedService** (object) - Information about the service the player is currently connected to.
  - **uniqueId** (string) - The unique ID of the connected service.
  - **serverName** (string) - The name of the connected server.
- **networkPlayerProxyInfo** (object) - Network proxy information.
  - **online** (boolean) - Whether the player is online.
  - **version** (integer) - The client version of the player.

#### Response Example
```json
{
  "uniqueId": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "name": "Notch",
  "firstLoginTimeMillis": 1735300000000,
  "lastLoginTimeMillis": 1735390080000,
  "loginService": {
    "uniqueId": "service-uuid",
    "serverName": "Proxy-1"
  },
  "connectedService": {
    "uniqueId": "service-uuid",
    "serverName": "Lobby-1"
  },
  "networkPlayerProxyInfo": {
    "online": true,
    "version": 763
  }
}
```
```

--------------------------------

### Authentication Ticket API

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Allows for the generation of short-lived authentication tickets for temporary API access.

```APIDOC
## Generate Authentication Ticket

### Description
Creates a short-lived authentication ticket for temporary API access with specified scopes.

### Method
POST

### Endpoint
/api/v3/auth/ticket

### Parameters
#### Request Body
- **scopes** (array of strings) - Required - The scopes to be granted to this ticket.

### Request Example
```bash
curl -X POST http://127.0.0.1:2812/api/v3/auth/ticket \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["cloudnet_rest:service_read"] }'
```

### Response
#### Success Response (200)
- **ticket** (string) - The generated authentication ticket.
- **expiresAt** (string) - The expiration timestamp of the ticket (ISO 8601 format).

#### Response Example
```json
{
  "ticket": "tkt_a1b2c3d4e5f67890abcdef1234567890",
  "expiresAt": "2025-12-28T13:13:00Z"
}
```

---

## Use Authentication Ticket

### Description
Use the generated ticket in the Authorization header for subsequent API requests.

### Method
GET (example for a GET request)

### Endpoint
Any API endpoint (e.g., /api/v3/service)

### Request Example
```bash
curl -X GET http://127.0.0.1:2812/api/v3/service \
  -H "Authorization: Ticket <your_generated_ticket>"
```
```

--------------------------------

### Service Management

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Endpoints for managing services within the CloudNet cluster, including listing, retrieving details, and deletion.

```APIDOC
## List All Services

### Description
Retrieves a list of all currently running services in the CloudNet cluster.

### Method
GET

### Endpoint
/api/v3/service

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - "Bearer [JWT Access Token]"
- **Accept** (string) - Optional - "application/json"

### Response
#### Success Response (200 OK)
- **services** (array[object]) - An array of service objects.
  - **serviceId** (object) - Unique identifier for the service.
    - **taskName** (string) - The name of the task the service belongs to.
    - **taskServiceId** (integer) - The sequential ID of the service within its task.
    - **nodeUniqueId** (string) - The unique ID of the node the service is running on.
    - **uniqueId** (string) - The globally unique ID of the service.
    - **nameSplitter** (string) - The splitter used in the service name.
    - **allowedNodes** (array[string]) - List of nodes where this service is allowed to run.
  - **state** (string) - The current state of the service (e.g., RUNNING, STOPPED).
  - **configuration** (object) - The configuration of the service.
    - **processConfig** (object) - Process-specific configuration.
      - **environment** (string) - The runtime environment (e.g., MINECRAFT_SERVER).
      - **maxHeapMemorySize** (integer) - Maximum heap memory in MB.
      - **jvmOptions** (array[string]) - JVM options.
    - **port** (integer) - The network port the service is listening on.
    - **autoDeleteOnStop** (boolean) - Whether the service should be deleted when stopped.
    - **staticService** (boolean) - Whether the service is a static service.
  - **connectedTime** (integer) - Timestamp when the service connected.
  - **lifeCycle** (string) - The lifecycle state of the service.

#### Response Example
```json
{
  "services": [
    {
      "serviceId": {
        "taskName": "Lobby",
        "taskServiceId": 1,
        "nodeUniqueId": "Node-1",
        "uniqueId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "nameSplitter": "-",
        "allowedNodes": []
      },
      "state": "RUNNING",
      "configuration": {
        "processConfig": {
          "environment": "MINECRAFT_SERVER",
          "maxHeapMemorySize": 512,
          "jvmOptions": ["-XX:+UseG1GC"]
        },
        "port": 25565,
        "autoDeleteOnStop": false,
        "staticService": false
      },
      "connectedTime": 1735390080000,
      "lifeCycle": "RUNNING"
    }
  ]
}
```

---

## Get Specific Service

### Description
Retrieves detailed information about a specific service identified by its unique ID or name.

### Method
GET

### Endpoint
/api/v3/service/{serviceIdOrName}

### Parameters
#### Path Parameters
- **serviceIdOrName** (string) - Required - The unique ID or name of the service.

#### Header Parameters
- **Authorization** (string) - Required - "Bearer [JWT Access Token]"
- **Accept** (string) - Optional - "application/json"

### Response
#### Success Response (200 OK)
- Returns a detailed service object, including `serviceId`, `state`, and `processSnapshot` (if available).
  - **processSnapshot** (object) - Snapshot of the service's process information.
    - **pid** (integer) - Process ID.
    - **cpuUsage** (number) - CPU usage percentage.
    - **systemCpuUsage** (number) - System CPU usage percentage.
    - **maxHeapMemory** (integer) - Maximum heap memory in bytes.
    - **heapUsageMemory** (integer) - Current heap memory usage in bytes.

#### Response Example
```json
{
  "serviceId": {
    "taskName": "Lobby",
    "taskServiceId": 1,
    "uniqueId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "state": "RUNNING",
  "processSnapshot": {
    "pid": 12345,
    "cpuUsage": 15.5,
    "systemCpuUsage": 45.2,
    "maxHeapMemory": 536870912,
    "heapUsageMemory": 268435456
  }
}
```

---

## Delete Service

### Description
Stops and deletes a specified service from the CloudNet cluster.

### Method
DELETE

### Endpoint
/api/v3/service/{serviceIdOrName}

### Parameters
#### Path Parameters
- **serviceIdOrName** (string) - Required - The unique ID or name of the service to delete.

#### Header Parameters
- **Authorization** (string) - Required - "Bearer [JWT Access Token]"

### Response
#### Success Response (204 No Content)
Indicates that the service was successfully stopped and deleted.

#### Error Response
- **404 Not Found**: If the specified service does not exist.
- **403 Forbidden**: If the authenticated user lacks the necessary permissions.
```

--------------------------------

### JWT Authentication

Source: https://context7.com/cloudnetservice/module-rest/llms.txt

Authenticate using Basic Auth credentials to obtain JWT access and refresh tokens for subsequent API requests. Requires a REST user to be created first.

```APIDOC
## JWT Authentication

### Description
Authenticates a REST user via Basic Auth and returns JWT access and refresh tokens. These tokens are then used for authorizing subsequent API calls.

### Method
POST

### Endpoint
/api/v3/auth

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - "Basic [base64 encoded username:password]"
- **Content-Type** (string) - Required - "application/json"

#### Request Body
- **scopes** (array[string]) - Required - A list of scopes the token should have.

### Request Example
```json
{
  "scopes": ["cloudnet_rest:service_read", "cloudnet_rest:service_write"]
}
```

### Response
#### Success Response (200 OK)
- **accessToken** (string) - The JWT access token.
- **refreshToken** (string) - The JWT refresh token.
- **expiresAt** (string) - The expiration timestamp of the access token (ISO 8601 format).
- **tokenType** (string) - The type of token, typically "Bearer".

#### Response Example
```json
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2025-12-29T13:08:00Z",
  "tokenType": "Bearer"
}
```
```