Management API

Category: API Reference

openapi: 3.1.0 info: title: PowBot Desktop API description: | RESTful API for managing PowBot Desktop instances, accounts, and proxies.

This API provides endpoints for:
- Managing game client instances (create, update, stop, monitor)
- Managing accounts (OAuth and Legacy)
- Managing proxy configurations

All endpoints use JSON for request/response bodies and follow RESTful conventions.

version: 1.0.0 contact: name: PowBot Desktop API Support servers:

url: http://localhost:39344/api/v1 description: Server running in PowBot Desktop tags:
name: Health description: Health check and status endpoints
name: Instances description: Game client instance management
name: Accounts description: Account management (OAuth and Legacy)
name: Proxies description: Proxy configuration management paths: /health: get: tags: - Health summary: Health check description: | Check the health status of the API server.
```
Returns the current status and version information.
Useful for monitoring and service discovery.
```
operationId: healthCheck responses: '200': description: Service is healthy content: application/json: schema: $ref: '#/components/schemas/HealthResponse' example: status: ok version: 0.1.0 /instances: get: tags: - Instances summary: List instances description: | Retrieve a list of all game client instances.
```
Returns summary information for each instance including status, script information, and runtime.
```
operationId: listInstances responses: '200': description: Successful response content: application/json: schema: type: array items: $ref: '#/components/schemas/InstanceSummary' example: - id: 550e8400-e29b-41d4-a716-446655440000 name: 'Pow Instance 1 (OAuth: PlayerName)' status: running created_at: '2024-01-15T10:30:00Z' script: /scripts/mining.lua script_state: running script_name: Progressive Miner script_started_at: '2024-01-15T10:35:00Z' script_runtime_seconds: 1234.56 script_stats_rows: - 'Runtime: 20m 34s' - 'Ores mined: 150' runtime_seconds: 3600 last_event: Instance running pid: 12345 '500': $ref: '#/components/responses/InternalServerError' /instances/{id}: get: tags: - Instances summary: Get instance description: | Retrieve detailed information about a specific instance.
```
Returns full instance details including logs and notes.
```
operationId: getInstance parameters: - $ref: '#/components/parameters/InstanceId' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/InstanceDetail' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' delete: tags: - Instances summary: Terminate instance description: | Terminate an instance.
```
This will permanently delete the instance and all associated data.
The game client process will be terminated if it's still running.
```
operationId: terminateInstance parameters: - $ref: '#/components/parameters/InstanceId' responses: '204': description: Instance terminated successfully '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' /instances/{id}/stop: put: tags: - Instances summary: Stop script description: | Stop the currently running script on an instance.
```
This will stop script execution but keep the instance running.
The script state will be updated to "stopped".
```
operationId: stopScript parameters: - $ref: '#/components/parameters/InstanceId' responses: '200': description: Script stopped successfully content: application/json: schema: $ref: '#/components/schemas/InstanceSummary' '400': description: Script is not in a stoppable state content: application/json: schema: $ref: '#/components/schemas/Error' example: error: No script is currently running code: BAD_REQUEST '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' /instances/{id}/pause: put: tags: - Instances summary: Pause script description: | Pause the currently running script on an instance.
```
This will pause script execution but keep the instance running.
The script state will be updated to "paused" and can be resumed later.
```
operationId: pauseScript parameters: - $ref: '#/components/parameters/InstanceId' responses: '200': description: Script paused successfully content: application/json: schema: $ref: '#/components/schemas/InstanceSummary' '400': description: Script is not in a pausable state content: application/json: schema: $ref: '#/components/schemas/Error' example: error: No script is currently running code: BAD_REQUEST '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' /instances/{id}/resume: put: tags: - Instances summary: Resume script description: | Resume a paused script on an instance.
```
This will resume script execution from the paused state.
The script state will be updated to "running".
```
operationId: resumeScript parameters: - $ref: '#/components/parameters/InstanceId' responses: '200': description: Script resumed successfully content: application/json: schema: $ref: '#/components/schemas/InstanceSummary' '400': description: Script is not in a resumable state content: application/json: schema: $ref: '#/components/schemas/Error' example: error: No script is currently paused code: BAD_REQUEST '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' /instances/{id}/start: put: tags: - Instances summary: Start script description: | Start a script on an instance.
```
This will start script execution on the instance. The script must be specified
via the script_id in the request body. Optionally, a profile_id can be provided
to use a specific script profile.
```
operationId: startScript parameters: - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartScriptRequest' example: script_id: 550e8400-e29b-41d4-a716-446655440000 profile_id: 660e8400-e29b-41d4-a716-446655440001 responses: '200': description: Script started successfully content: application/json: schema: $ref: '#/components/schemas/InstanceSummary' '400': description: Invalid request or instance is not in a startable state content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Instance is not running code: BAD_REQUEST '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' /instances/{id}/logs: get: tags: - Instances summary: Get instance logs description: | Retrieve log entries for an instance.
```
Returns a paginated list of log entries, with the most recent entries first.
Use the `limit` query parameter to control how many entries are returned.
```
operationId: getInstanceLogs parameters: - $ref: '#/components/parameters/InstanceId' - $ref: '#/components/parameters/LogLimit' responses: '200': description: Successful response content: application/json: schema: type: array items: $ref: '#/components/schemas/InstanceLogEntry' example: - id: 660e8400-e29b-41d4-a716-446655440001 level: info message: Instance started timestamp: '2024-01-15T10:30:00Z' - id: 660e8400-e29b-41d4-a716-446655440002 level: warn message: Script paused timestamp: '2024-01-15T10:31:00Z' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' /instances/{id}/logs/tail: get: tags: - Instances summary: Tail instance logs description: | Stream instance logs in real-time.
```
This endpoint maintains a persistent connection and sends log entries as they are generated.
Each log entry is sent as a JSON object on a new line (newline-delimited JSON).

The connection will remain open until the instance is stopped or the client disconnects.
```
operationId: tailInstanceLogs parameters: - $ref: '#/components/parameters/InstanceId' - $ref: '#/components/parameters/LogLimit' responses: '200': description: Stream of log entries (newline-delimited JSON) content: text/event-stream: schema: type: string format: binary examples: log_entry: summary: Example log entry value: | {"id":"660e8400-e29b-41d4-a716-446655440001","level":"info","message":"Instance started","timestamp":"2024-01-15T10:30:00Z"} '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' /instances/{id}/execute: post: tags: - Instances summary: Execute Lua code description: | Execute Lua code in a running instance.
```
This endpoint sends Lua code to the instance's REPL (Read-Eval-Print Loop)
and returns the execution result. The code is executed asynchronously and
the result is returned when available (with a timeout).
```
operationId: executeInstanceLua parameters: - $ref: '#/components/parameters/InstanceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExecuteLuaRequest' example: code: print('Hello from Lua') responses: '200': description: Lua execution completed content: application/json: schema: $ref: '#/components/schemas/ExecuteLuaResponse' example: session_id: session-12345 result: Hello from Lua error: null '400': description: Instance is not running or invalid request content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Instance is not running code: BAD_REQUEST '404': $ref: '#/components/responses/NotFound' '408': description: Execution timed out content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Lua execution timed out code: TIMEOUT '500': $ref: '#/components/responses/InternalServerError' /instances/{id}/events: get: tags: - Instances summary: Instance events description: | Stream instance events in real-time.
```
This endpoint maintains a persistent connection and sends events as they occur:
- Status changes (starting, running, paused, stopped, error)
- Script updates (assignment, state changes)
- Break schedule updates
- Other instance state changes

Each event is sent as a JSON object on a new line (newline-delimited JSON).

The connection will remain open until the instance is deleted or the client disconnects.
```
operationId: streamInstanceEvents parameters: - $ref: '#/components/parameters/InstanceId' responses: '200': description: Stream of instance events (newline-delimited JSON) content: text/event-stream: schema: type: string format: binary examples: status_change: summary: Example status change event value: | {"type":"status_change","instance_id":"550e8400-e29b-41d4-a716-446655440000","data":{"status":"running","message":"Instance started"},"timestamp":"2024-01-15T10:30:00Z"} script_update: summary: Example script update event value: | {"type":"script_update","instance_id":"550e8400-e29b-41d4-a716-446655440000","data":{"script":"/scripts/mining.lua","script_name":"Progressive Miner"},"timestamp":"2024-01-15T10:35:00Z"} '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' /instances/launch: post: tags: - Instances summary: Launch instance description: | Launch a new game client instance with an account ID (or without an account).
```
Provide an `account_id` to use an existing account (OAuth or Legacy).
If `account_id` is not provided, the instance will be created without an account (manual login).

Optionally specify a `proxy_id` to route traffic through a proxy.
```
operationId: launchInstance requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LaunchInstanceRequest' responses: '201': description: Instance launched successfully content: application/json: schema: $ref: '#/components/schemas/InstanceSummary' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalServerError' /instances/launch_legacy_account: post: tags: - Instances summary: Launch instance with legacy account description: | Launch a new game client instance with legacy account credentials (username/password).
```
The account will be created if it doesn't exist, or updated if it does.

Optionally specify a `proxy_id` to route traffic through a proxy.
```
operationId: launchLegacyAccount requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LaunchLegacyAccountRequest' responses: '201': description: Instance launched successfully content: application/json: schema: $ref: '#/components/schemas/InstanceSummary' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalServerError' /instances/launch_jagex_account: post: tags: - Instances summary: Launch instance with Jagex account description: | Launch a new game client instance with Jagex account credentials (OAuth-based).
```
Requires session_id, display_name, character_id, refresh_token, and access_token.
The account will be created if it doesn't exist, or updated if it does.

Optionally specify a `proxy_id` to route traffic through a proxy.
```
operationId: launchJagexAccount requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LaunchJagexAccountRequest' responses: '201': description: Instance launched successfully content: application/json: schema: $ref: '#/components/schemas/InstanceSummary' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalServerError' /accounts: get: tags: - Accounts summary: List accounts description: | Retrieve a list of all accounts (OAuth and Legacy) with their characters.
```
Each account includes a characters array. For OAuth accounts, this array contains all characters
associated with the account. For Legacy accounts, the characters array will be empty.
```
operationId: listAccounts responses: '200': description: Successful response content: application/json: schema: type: array items: $ref: '#/components/schemas/Account' example: - id: acc-550e8400-e29b-41d4-a716-446655440000 account_type: OAuth display_name: PlayerName email: [email protected] has_saved_password: false last_used: '2024-01-15T10:30:00Z' created_at: '2024-01-01T00:00:00Z' needs_refresh: false proxy_id: proxy-123 bank_pin: null characters: - id: char-660e8400-e29b-41d4-a716-446655440001 display_name: MyCharacter account_id: acc-550e8400-e29b-41d4-a716-446655440000 - id: acc-660e8400-e29b-41d4-a716-446655440001 account_type: Legacy display_name: LegacyAccount username: LegacyAccount email: null has_saved_password: true last_used: '2024-01-14T15:20:00Z' created_at: '2024-01-01T00:00:00Z' needs_refresh: false proxy_id: null bank_pin: null characters: [] '500': $ref: '#/components/responses/InternalServerError' post: tags: - Accounts summary: Create account description: | Create a new account.
```
Supports both OAuth and Legacy account types:
- **OAuth**: Requires display_name and optionally email
- **Legacy**: Requires display_name

Both types can optionally specify a proxy_id to associate with the account.
```
operationId: createAccount requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAccountRequest' examples: oauth: summary: OAuth account value: account_type: OAuth display_name: PlayerName email: [email protected] proxy_id: proxy-123 legacy: summary: Legacy account value: account_type: Legacy display_name: LegacyAccount proxy_id: null responses: '201': description: Account created successfully content: application/json: schema: $ref: '#/components/schemas/Account' '400': $ref: '#/components/responses/BadRequest' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' /accounts/{id}: get: tags: - Accounts summary: Get account description: | Retrieve detailed information about a specific account. operationId: getAccount parameters: - $ref: '#/components/parameters/AccountId' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Account' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' put: tags: - Accounts summary: Update account description: | Update an account's properties.
```
Supports partial updates. Only provided fields will be updated.
Can update display_name, email, has_saved_password, and proxy_id.
```
operationId: updateAccount parameters: - $ref: '#/components/parameters/AccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAccountRequest' example: display_name: Updated Player Name email: [email protected] proxy_id: proxy-456 responses: '200': description: Account updated successfully content: application/json: schema: $ref: '#/components/schemas/Account' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' delete: tags: - Accounts summary: Delete account description: | Delete an account.
```
This will permanently remove the account from the system.
If the account is currently in use by an instance, the deletion may fail.
```
operationId: deleteAccount parameters: - $ref: '#/components/parameters/AccountId' responses: '204': description: Account deleted successfully '404': $ref: '#/components/responses/NotFound' '409': description: Account is in use and cannot be deleted content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Account is currently in use by an instance code: CONFLICT '500': $ref: '#/components/responses/InternalServerError' /proxies: get: tags: - Proxies summary: List proxies description: | Retrieve a list of all proxy configurations.
```
Returns proxy information including host, port, authentication, and enabled status.
```
operationId: listProxies responses: '200': description: Successful response content: application/json: schema: type: array items: $ref: '#/components/schemas/Proxy' example: - id: proxy-550e8400-e29b-41d4-a716-446655440000 name: US East Proxy enabled: true host: proxy.example.com port: 1080 username: proxyuser - id: proxy-660e8400-e29b-41d4-a716-446655440001 name: EU West Proxy enabled: false host: eu-proxy.example.com port: 8080 username: null '500': $ref: '#/components/responses/InternalServerError' post: tags: - Proxies summary: Create proxy description: | Create a new proxy configuration.
```
Requires name, host, and port. Username is optional for authentication.
The proxy will be enabled by default unless specified otherwise.
```
operationId: createProxy requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateProxyRequest' example: name: US East Proxy enabled: true host: proxy.example.com port: 1080 username: proxyuser responses: '201': description: Proxy created successfully content: application/json: schema: $ref: '#/components/schemas/Proxy' '400': $ref: '#/components/responses/BadRequest' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' /proxies/{id}: get: tags: - Proxies summary: Get proxy description: | Retrieve detailed information about a specific proxy configuration. operationId: getProxy parameters: - $ref: '#/components/parameters/ProxyId' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Proxy' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' put: tags: - Proxies summary: Update proxy description: | Update a proxy's properties.
```
Supports partial updates. Only provided fields will be updated.
Can update name, enabled status, host, port, and username.
```
operationId: updateProxy parameters: - $ref: '#/components/parameters/ProxyId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateProxyRequest' example: name: Updated Proxy Name enabled: false host: newproxy.example.com port: 8080 responses: '200': description: Proxy updated successfully content: application/json: schema: $ref: '#/components/schemas/Proxy' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' delete: tags: - Proxies summary: Delete proxy description: | Delete a proxy configuration.
```
This will permanently remove the proxy from the system.
If the proxy is currently in use by an instance or account, the deletion may fail.
```
operationId: deleteProxy parameters: - $ref: '#/components/parameters/ProxyId' responses: '204': description: Proxy deleted successfully '404': $ref: '#/components/responses/NotFound' '409': description: Proxy is in use and cannot be deleted content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Proxy is currently in use by an instance or account code: CONFLICT '500': $ref: '#/components/responses/InternalServerError' components: schemas: InstanceStatus: type: string enum: - starting - running - paused - stopped - error - unknown description: Operational status of a game instance example: running LogLevel: type: string enum: - info - warn - error - debug description: Severity level for log entries example: info AccountType: type: string enum: - OAuth - Legacy description: Type of account example: OAuth OAuthTokens: type: object description: OAuth token set for creating OAuth accounts properties: access_token: type: string description: OAuth access token (required) example: eyJhbGciOiJSUzI1NiIs... refresh_token: type: string nullable: true description: OAuth refresh token (optional, for token refresh) example: refresh_token_here id_token: type: string nullable: true description: OAuth ID token (optional, contains account info) example: eyJhbGciOiJSUzI1NiIs... expires_in: type: integer format: int64 description: Token expiration time in seconds from now example: 3600 scope: type: string nullable: true description: OAuth scope (e.g. "openid offline") example: openid offline cookie_jar_path: type: string nullable: true description: Path to cookie jar file (optional, for session persistence) example: /path/to/cookies.txt required: - access_token - expires_in OAuthAccountCredentials: type: object description: OAuth account credentials for creating accounts (tokens only, no session_id) properties: email: type: string nullable: true description: Email address for the Jagex account (optional) example: [email protected] oauth_tokens: $ref: '#/components/schemas/OAuthTokens' description: OAuth tokens for authentication bank_pin: type: string nullable: true description: Bank PIN (4 digits) example: '1234' required: - oauth_tokens RenderMode: type: string enum: - all - none - script description: Rendering mode for the game client example: all ScriptState: type: string enum: - idle - configuring - starting - running - paused - stopping - stopped - error description: Current script execution state example: running InstanceSummary: type: object description: Summary view of an instance for list displays properties: id: type: string format: uuid description: Unique identifier for this instance example: 550e8400-e29b-41d4-a716-446655440000 name: type: string description: Human-readable display name example: 'Pow Instance 1 (OAuth: PlayerName)' status: $ref: '#/components/schemas/InstanceStatus' created_at: type: string format: date-time description: ISO 8601 timestamp of creation example: '2024-01-15T10:30:00Z' script_id: type: string format: uuid nullable: true description: ID of currently loaded script (if any) example: 550e8400-e29b-41d4-a716-446655440000 script_state: $ref: '#/components/schemas/ScriptState' nullable: true script_name: type: string nullable: true description: Display name of the currently running script example: Progressive Miner script_started_at: type: string format: date-time nullable: true description: ISO timestamp when script started executing example: '2024-01-15T10:35:00Z' script_runtime_seconds: type: number format: double nullable: true description: Script runtime in seconds example: 1234.56 script_stats_rows: type: array items: type: string description: Paint overlay statistics rows from script example: - 'Runtime: 20m 34s' - 'Ores mined: 150' runtime_seconds: type: integer format: int64 nullable: true description: Total instance runtime in seconds (excluding paused periods) example: 3600 last_event: $ref: '#/components/schemas/InstanceEvent' nullable: true pid: type: integer format: int32 nullable: true description: Process ID of the game client (if running) example: 12345 active_break_schedule: $ref: '#/components/schemas/BreakSchedule' active_break_profile_name: type: string nullable: true description: Name of saved break profile (if applicable) example: Standard Breaks required: - id - name - status - created_at - script_stats_rows InstanceDetail: type: object description: Detailed view of an instance including logs and notes allOf: - $ref: '#/components/schemas/InstanceSummary' - type: object properties: notes: type: string nullable: true description: User notes about this instance example: Used for testing new mining script logs: type: array items: $ref: '#/components/schemas/InstanceLogEntry' description: Log entries (newest first) required: - logs InstanceLogEntry: type: object description: A log entry for an instance properties: id: type: string format: uuid description: Unique identifier for this log entry example: 660e8400-e29b-41d4-a716-446655440001 level: $ref: '#/components/schemas/LogLevel' message: type: string description: Log message content example: Instance started timestamp: type: string format: date-time description: ISO 8601 timestamp when this log entry was created example: '2024-01-15T10:30:00Z' required: - id - level - message - timestamp InstanceEvent: type: string enum: - started - waiting_for_configuration - stopping_script - waiting_for_client_boot - waiting_for_dll_handshake - runtime_paused - client_terminated - script_awaiting_deployment - script_selection_cancelled - script_running description: Most recent status event type example: waiting_for_dll_handshake ServerSentEvent: type: object description: Server-Sent Event for instance updates properties: type: type: string description: Event type enum: - status_change - log - script_update - break_schedule_update example: status_change instance_id: type: string format: uuid description: ID of the instance example: 550e8400-e29b-41d4-a716-446655440000 data: type: object additionalProperties: true description: Event-specific data example: status: running message: Instance started timestamp: type: string format: date-time description: ISO timestamp of the event example: '2024-01-15T10:30:00Z' required: - type - instance_id - timestamp BreakSchedule: type: object description: Break schedule configuration properties: breaks: type: array items: $ref: '#/components/schemas/BreakPeriod' description: List of break periods enabled: type: boolean description: Whether the break schedule is active example: true required: - breaks - enabled BreakPeriod: type: object description: A single break period properties: start_time: type: string description: Start time in HH:MM format example: '14:00' duration_minutes: type: integer description: Duration of break in minutes example: 15 required: - start_time - duration_minutes Account: type: object description: Account information properties: id: type: string description: Unique identifier for this account example: acc-550e8400-e29b-41d4-a716-446655440000 account_type: $ref: '#/components/schemas/AccountType' display_name: type: string description: Human-readable display name example: PlayerName username: type: string nullable: true description: Username (for Legacy accounts) example: PlayerName email: type: string nullable: true description: Email address (for OAuth accounts) example: [email protected] has_saved_password: type: boolean description: Whether password is saved (for Legacy accounts) example: false last_used: type: string format: date-time nullable: true description: ISO timestamp of last use example: '2024-01-15T10:30:00Z' created_at: type: string format: date-time description: ISO timestamp of creation example: '2024-01-01T00:00:00Z' needs_refresh: type: boolean description: Whether OAuth token needs refresh example: false proxy_id: type: string nullable: true description: ID of associated proxy (if any) example: proxy-123 bank_pin: type: string nullable: true description: Bank PIN for the account (4 digits) example: '1234' characters: type: array description: List of characters associated with this account (OAuth accounts only) items: $ref: '#/components/schemas/Character' required: - id - account_type - display_name - has_saved_password - created_at - needs_refresh - characters Character: type: object description: Character information for OAuth accounts properties: id: type: string description: Unique identifier for the character example: char-660e8400-e29b-41d4-a716-446655440001 display_name: type: string description: Display name of the character example: MyCharacter account_id: type: string description: ID of the account this character belongs to example: acc-550e8400-e29b-41d4-a716-446655440000 required: - id - display_name - account_id Proxy: type: object description: Proxy configuration properties: id: type: string description: Unique identifier for this proxy example: proxy-550e8400-e29b-41d4-a716-446655440000 name: type: string description: Human-readable name example: US East Proxy enabled: type: boolean description: Whether this proxy is enabled example: true host: type: string description: Proxy server hostname or IP address example: proxy.example.com port: type: integer format: int32 description: Proxy server port example: 1080 username: type: string nullable: true description: Username for proxy authentication (if required) example: proxyuser required: - id - name - enabled - host - port ProxySpec: type: object description: Inline proxy specification (alternative to proxy_id). If provided, the system will resolve the proxy by host + port + username. If a matching proxy exists, its ID will be used. Otherwise, a new proxy will be created. properties: host: type: string description: Proxy server hostname or IP address example: proxy.example.com port: type: integer format: int32 description: Proxy server port example: 1080 username: type: string nullable: true description: Username for proxy authentication (if required) example: proxyuser required: - host - port Error: type: object description: Standard error response properties: error: type: string description: Error message example: Instance not found code: type: string nullable: true description: Error code example: NOT_FOUND details: type: object nullable: true additionalProperties: true description: Additional error details required: - error HealthResponse: type: object description: Health check response properties: status: type: string description: Service status example: ok version: type: string description: Application version example: 0.1.0 required: - status - version ExecuteLuaResponse: type: object description: Response from Lua execution properties: session_id: type: string description: Session ID for this execution example: session-12345 result: type: string nullable: true description: Execution result (if successful) example: Hello from Lua error: type: string nullable: true description: Error message (if execution failed) example: Syntax error at line 1 required: - session_id LaunchInstanceRequest: type: object description: Request to launch an instance with an account ID (or without an account) properties: account_id: type: string nullable: true description: ID of the account to use for this instance. If not provided, instance will be created without an account (manual login). example: acc-550e8400-e29b-41d4-a716-446655440000 character_id: type: string nullable: true description: ID of the character to use for OAuth accounts. If not provided and account_id is an OAuth account, the first available character will be used. example: char-550e8400-e29b-41d4-a716-446655440000 proxy_id: type: string nullable: true description: ID of proxy to use (from proxy list). Mutually exclusive with proxy. example: proxy-123 proxy: $ref: '#/components/schemas/ProxySpec' nullable: true description: Inline proxy specification. The system will resolve the proxy by host + port + username. If a matching proxy exists, its ID will be used. Otherwise, a new proxy will be created. Mutually exclusive with proxy_id. script: $ref: '#/components/schemas/StartScriptRequest' nullable: true description: Script to start after instance launch. If provided, the script will be started automatically. example: account_id: acc-550e8400-e29b-41d4-a716-446655440000 proxy_id: proxy-123 examples: with_account: summary: Launch instance with account ID value: account_id: acc-550e8400-e29b-41d4-a716-446655440000 proxy_id: proxy-123 without_account: summary: Launch instance without account (manual login) value: proxy_id: proxy-123 minimal: summary: Minimal launch (no account, no proxy) value: {} with_inline_proxy: summary: Launch instance with inline proxy specification value: account_id: acc-550e8400-e29b-41d4-a716-446655440000 proxy: host: proxy.example.com port: 1080 username: proxyuser LaunchLegacyAccountRequest: type: object description: Request to launch an instance with legacy account credentials properties: username: type: string description: Username for the legacy account example: PlayerName password: type: string description: Password for the legacy account example: password123 bank_pin: type: string nullable: true description: Bank PIN (4 digits) example: '1234' proxy_id: type: string nullable: true description: ID of proxy to use (from proxy list). Mutually exclusive with proxy. example: proxy-123 proxy: $ref: '#/components/schemas/ProxySpec' nullable: true description: Inline proxy specification. The system will resolve the proxy by host + port + username. If a matching proxy exists, its ID will be used. Otherwise, a new proxy will be created. Mutually exclusive with proxy_id. script: $ref: '#/components/schemas/StartScriptRequest' nullable: true description: Script to start after instance launch. If provided, the script will be started automatically. required: - username - password example: username: PlayerName password: password123 bank_pin: '1234' proxy_id: proxy-123 examples: with_proxy_id: summary: Launch with proxy ID value: username: PlayerName password: password123 bank_pin: '1234' proxy_id: proxy-123 with_inline_proxy: summary: Launch with inline proxy specification value: username: PlayerName password: password123 bank_pin: '1234' proxy: host: proxy.example.com port: 1080 username: proxyuser LaunchJagexAccountRequest: type: object description: Request to launch an instance with Jagex account credentials properties: session_id: type: string description: Session ID for the Jagex account example: session-550e8400-e29b-41d4-a716-446655440000 display_name: type: string description: Display name for the account example: PlayerName character_id: type: string description: ID of the character to use example: char-550e8400-e29b-41d4-a716-446655440000 refresh_token: type: string description: OAuth refresh token example: refresh_token_here access_token: type: string description: OAuth access token example: eyJhbGciOiJSUzI1NiIs... bank_pin: type: string nullable: true description: Bank PIN (4 digits) example: '1234' proxy_id: type: string nullable: true description: ID of proxy to use (from proxy list). Mutually exclusive with proxy. example: proxy-123 proxy: $ref: '#/components/schemas/ProxySpec' nullable: true description: Inline proxy specification. The system will resolve the proxy by host + port + username. If a matching proxy exists, its ID will be used. Otherwise, a new proxy will be created. Mutually exclusive with proxy_id. script: $ref: '#/components/schemas/StartScriptRequest' nullable: true description: Script to start after instance launch. If provided, the script will be started automatically. required: - session_id - display_name - character_id - refresh_token - access_token example: session_id: session-550e8400-e29b-41d4-a716-446655440000 display_name: PlayerName character_id: char-550e8400-e29b-41d4-a716-446655440000 refresh_token: refresh_token_here access_token: eyJhbGciOiJSUzI1NiIs... bank_pin: '1234' proxy_id: proxy-123 examples: with_proxy_id: summary: Launch with proxy ID value: session_id: session-550e8400-e29b-41d4-a716-446655440000 display_name: PlayerName character_id: char-550e8400-e29b-41d4-a716-446655440000 refresh_token: refresh_token_here access_token: eyJhbGciOiJSUzI1NiIs... bank_pin: '1234' proxy_id: proxy-123 with_inline_proxy: summary: Launch with inline proxy specification value: session_id: session-550e8400-e29b-41d4-a716-446655440000 display_name: PlayerName character_id: char-550e8400-e29b-41d4-a716-446655440000 refresh_token: refresh_token_here access_token: eyJhbGciOiJSUzI1NiIs... bank_pin: '1234' proxy: host: proxy.example.com port: 1080 username: proxyuser UpdateInstanceRequest: type: object description: Request to update an instance properties: name: type: string description: Update the instance name example: Updated Instance Name notes: type: string nullable: true description: Update user notes example: Updated notes script: type: string nullable: true description: Assign a script to the instance example: /scripts/mining.lua example: name: My Updated Instance notes: Testing new features CreateAccountRequest: type: object description: Request to create a new account properties: account_type: $ref: '#/components/schemas/AccountType' display_name: type: string description: Human-readable display name example: PlayerName legacyAccount: $ref: '#/components/schemas/LegacyAccount' nullable: true description: Legacy account credentials (username/password). Required when account_type is Legacy. jagexAccount: $ref: '#/components/schemas/OAuthAccountCredentials' nullable: true description: OAuth account credentials (tokens only). Required when account_type is OAuth. proxy_id: type: string nullable: true description: ID of proxy to associate with this account example: proxy-123 required: - account_type - display_name examples: legacy_account: summary: Create a legacy account value: account_type: Legacy display_name: PlayerName legacyAccount: username: PlayerName password: password123 bank_pin: '1234' proxy_id: proxy-123 oauth_account: summary: Create an OAuth account value: account_type: OAuth display_name: PlayerName jagexAccount: email: [email protected] oauth_tokens: access_token: eyJhbGciOiJSUzI1NiIs... refresh_token: refresh_token_here expires_in: 3600 bank_pin: '1234' proxy_id: proxy-123 UpdateAccountRequest: type: object description: Request to update an account properties: display_name: type: string description: Update the display name example: Updated Player Name email: type: string nullable: true description: Update email address example: [email protected] has_saved_password: type: boolean description: Update whether password is saved example: true proxy_id: type: string nullable: true description: Update associated proxy ID example: proxy-456 bank_pin: type: string nullable: true description: Update bank PIN (4 digits) example: '1234' example: display_name: Updated Name proxy_id: proxy-456 bank_pin: '1234' CreateProxyRequest: type: object description: Request to create a new proxy properties: name: type: string description: Human-readable name example: US East Proxy enabled: type: boolean description: Whether this proxy is enabled default: true host: type: string description: Proxy server hostname or IP address example: proxy.example.com port: type: integer format: int32 description: Proxy server port example: 1080 username: type: string nullable: true description: Username for proxy authentication (if required) example: proxyuser required: - name - host - port UpdateProxyRequest: type: object description: Request to update a proxy properties: name: type: string description: Update the proxy name example: Updated Proxy Name enabled: type: boolean description: Update whether proxy is enabled example: false host: type: string description: Update proxy host example: newproxy.example.com port: type: integer format: int32 description: Update proxy port example: 8080 username: type: string nullable: true description: Update proxy username example: newuser example: name: Updated Proxy enabled: false ExecuteLuaRequest: type: object description: Request to execute Lua code in an instance properties: code: type: string description: Lua code to execute example: print('Hello from Lua') required: - code StartScriptRequest: type: object description: Request to start a script on an instance properties: script_id: type: string nullable: true description: ID of the script to start. Mutually exclusive with script_path and script_code. example: 550e8400-e29b-41d4-a716-446655440000 script_path: type: string nullable: true description: File system path to the script directory. If provided, the script will be loaded from this path and started automatically. Mutually exclusive with script_id and script_code. example: C:\Scripts\MyScript script_code: type: string nullable: true description: Base64-encoded ZIP file containing all script files (possibly including manifest.json). If provided, the script will be extracted and started automatically. Mutually exclusive with script_id and script_path. example: UEsDBBQAAAAIA... profile_id: type: string nullable: true description: Optional profile ID to use with the script. Mutually exclusive with options. example: 660e8400-e29b-41d4-a716-446655440001 options: type: object nullable: true description: Optional script configuration options (key-value pairs). Mutually exclusive with profile_id. If both are provided, profile_id takes precedence. additionalProperties: true example: setting1: value1 setting2: 42 options_data: type: object nullable: true description: Optional script configuration data (for complex options like tables). Mutually exclusive with profile_id. additionalProperties: true example: table_data: {} LegacyAccount: type: object description: Legacy account credentials (username/password) properties: username: type: string description: Username for the legacy account example: PlayerName password: type: string description: Password for the legacy account example: password123 bank_pin: type: string nullable: true description: Bank PIN (4 digits) example: '1234' display_name: type: string nullable: true description: Display name for the account example: My Account required: - username - password responses: InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: An internal error occurred code: INTERNAL_ERROR NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Resource not found code: NOT_FOUND BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid request parameters code: BAD_REQUEST Conflict: description: Resource conflict (e.g., duplicate) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Resource already exists code: CONFLICT parameters: InstanceId: name: id in: path required: true description: Unique identifier of the instance schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 LogLimit: name: limit in: query required: false description: Maximum number of log entries to return schema: type: integer format: int32 minimum: 1 maximum: 1000 default: 50 example: 100 AccountId: name: id in: path required: true description: Unique identifier of the account schema: type: string example: acc-550e8400-e29b-41d4-a716-446655440000 ProxyId: name: id in: path required: true description: Unique identifier of the proxy schema: type: string example: proxy-550e8400-e29b-41d4-a716-446655440000