{ "openapi": "3.0.3", "info": { "title": "SoulFire HTTP API", "version": "2.7.1-SNAPSHOT", "description": "Generated from SoulFire's Armeria gRPC metadata.\n\nThis document only covers HTTP-accessible unary operations:\n- unframed JSON POST routes generated from gRPC services\n- additional HTTP/JSON transcoding routes exposed by Armeria\n\nIt does not describe streaming RPCs, gRPC-Web framing, reflection, or other non-HTTP transports.\n\nAuthorization:\n- Bearer: `Authorization: Bearer `\n- Basic: `Authorization: Basic `\n\n`LoginService` is public. Every other operation requires an API token audience accepted by SoulFire.\n" }, "servers": [ { "url": "http://127.0.0.1:38765", "description": "Configured SoulFire public API address" } ], "tags": [ { "name": "AutomationService" }, { "name": "BotService", "description": "Service for managing and controlling Minecraft bots.\nProvides comprehensive APIs for bot monitoring, movement control,\ninventory management, and interaction with server dialogs.\n\nPermissions:\n- READ_BOT_INFO: Required for GetBotList, GetBotInfo, GetInventoryState,\nRenderBotPov, GetDialog\n- UPDATE_BOT_CONFIG: Required for all other operations that modify bot state\n\nError Handling:\n- NOT_FOUND: Instance or bot does not exist\n- FAILED_PRECONDITION: Bot is not online or required game state is unavailable\n- INTERNAL: Unexpected server errors (check server logs for details)" }, { "name": "ClientService", "description": "Service for managing client/user-specific operations.\nAll methods in this service operate on the currently authenticated user,\nidentified via the JWT token in the Authorization header.\nEach method requires a specific GlobalPermission to be granted to the user." }, { "name": "CommandService", "description": "Service for executing server commands and retrieving tab-completion suggestions.\nCommands are executed using the Brigadier command framework and support various\noperations including bot control, pathfinding, inventory management, and administration.\nAll operations require appropriate permissions based on the specified command scope." }, { "name": "DownloadService", "description": "Service for downloading content from remote URLs through the SoulFire server.\nThis service acts as a proxy, allowing clients to fetch remote resources using\nthe server's network connection and optionally through a configured proxy.\n\nUse cases include:\n- Downloading resources that may be blocked from the client's network\n- Fetching content through a specific proxy for anonymity or geo-unlocking\n- Centralizing external API calls through the server\n\nThe service uses a Reactor Netty HTTP client with:\n- 5-second response timeout\n- Automatic compression support\n- Default Accept, Accept-Language, and User-Agent headers\n\nAuthorization:\n- Requires a valid JWT token\n- Caller must have DOWNLOAD_URL permission for the specified instance\n\nError handling:\n- Returns gRPC INTERNAL status on network errors, timeouts, or server failures\n- The error description contains details about the failure" }, { "name": "InstanceService", "description": "Service for managing SoulFire instances.\nAn instance represents a collection of Minecraft bots that can be started,\nstopped, and configured together. Each instance has its own configuration\nincluding settings, Minecraft accounts, and proxies.\n\nAll operations require appropriate permissions:\n- CREATE_INSTANCE (global): Required to create new instances\n- READ_INSTANCE: Required to list and view instance details\n- UPDATE_INSTANCE_META: Required to change instance name/icon\n- UPDATE_INSTANCE_CONFIG: Required to modify settings, accounts, and proxies\n- DELETE_INSTANCE: Required to delete an instance\n- CHANGE_INSTANCE_STATE: Required to start/stop/pause the instance\n- READ_INSTANCE_AUDIT_LOGS: Required to view audit logs\n- READ_BOT_INFO: Required to read account metadata" }, { "name": "LoginService", "description": "Service for authenticating users via email-based passwordless login.\n\nAuthentication Flow:\n1. Client calls Login with the user's email address\n2. If the email is registered, a six-digit code is sent to that email\n3. Client receives an auth_flow_token and EmailCode response\n4. User enters the code from their email\n5. Client calls EmailCode with the auth_flow_token and the code\n6. If valid, client receives a JWT token; if invalid, receives a Failure\n\nSecurity Features:\n- Rate limited to 20 requests per 10 minutes per origin to prevent brute force attacks\n- Auth flow tokens expire after 15 minutes\n- Same response for registered and unregistered emails to prevent email enumeration\n- Invalid codes return the same error as expired/invalid flow tokens to prevent timing attacks\n\nError Handling:\n- RESOURCE_EXHAUSTED: Rate limit exceeded (too many login attempts)\n- UNAUTHENTICATED: No origin header provided (required for rate limiting)\n- INTERNAL: Unexpected server error during processing" }, { "name": "LogsService", "description": "Service for accessing SoulFire server logs.\nProvides both historical log retrieval and real-time log streaming capabilities.\nAll methods require appropriate authentication and permissions based on the requested scope." }, { "name": "MCAuthService", "description": "Service for authenticating Minecraft accounts for use with SoulFire bots.\nSupports multiple authentication methods including Microsoft OAuth (credentials\nand device code flows) and offline mode. All methods require the caller to\nhave AUTHENTICATE_MC_ACCOUNT permission for the target instance.\n\nAuthentication may optionally use proxies if configured in instance settings\n(USE_PROXIES_FOR_ACCOUNT_AUTH). All authentication operations have timeouts\nto prevent indefinite hangs (2 minutes for credentials/refresh, 15 minutes\nfor device code flow)." }, { "name": "MetricsService", "description": "Service for retrieving instance metrics and monitoring data.\nMetrics are collected server-side and stored in a ring buffer.\nAll operations require appropriate permissions." }, { "name": "ScriptService", "description": "ScriptService provides management and execution capabilities for visual node-based\nautomation scripts within SoulFire.\n\nThe visual scripting system allows users to create automation workflows by connecting\nnodes in a graph. Each node represents an action, condition, or event trigger.\nNodes are connected by edges that define execution flow and data transfer.\n\nSCRIPT LIFECYCLE:\n1. Create a script using CreateScript with initial nodes/edges or empty graph\n2. Edit the script using UpdateScript to modify the node graph\n3. Activate the script using ActivateScript to register event listeners\n4. Monitor execution via SubscribeScriptEvents or GetScriptStatus\n5. Deactivate using DeactivateScript when done\n6. Delete unused scripts with DeleteScript\n\nScripts are reactive state machines - they don't \"run\" but rather listen for\ntrigger events and execute node chains in response. Activation registers the\nlisteners, deactivation removes them and cancels any pending async operations.\n\nPERMISSIONS: Script operations require appropriate instance permissions.\nThe specific permissions are TBD but will likely include:\n- READ_SCRIPT: View script definitions and status\n- UPDATE_SCRIPT: Create, modify, and delete scripts\n- EXECUTE_SCRIPT: Activate and deactivate scripts\n\nLOGGING: Script execution logs can be streamed via SubscribeScriptLogs or\nfiltered using InstanceScriptLogScope in the LogsService (see logs.proto)." }, { "name": "ServerService", "description": "ServerService provides gRPC methods for managing server-level configuration\nin SoulFire. This service handles global settings that affect the entire\nSoulFire server instance, including debug logging, plugin configurations,\nand other server-wide preferences.\n\nConfiguration changes are persisted to a database and trigger runtime hooks\nto apply settings immediately (e.g., adjusting log levels for SoulFire,\nMinecraft, Netty, gRPC, Hibernate, and Via components).\n\nAll methods require appropriate permissions:\n- GetServerInfo requires READ_SERVER_CONFIG permission\n- UpdateServerConfig requires UPDATE_SERVER_CONFIG permission\n- UpdateServerConfigEntry requires UPDATE_SERVER_CONFIG permission\n\nErrors:\n- PERMISSION_DENIED: If the caller lacks the required permission\n- INTERNAL: If a database or processing error occurs" }, { "name": "UserService", "description": "UserService provides user management functionality for the SoulFire system.\nAll methods require authentication via JWT token in the request metadata.\nMost methods require specific global permissions (CREATE_USER, READ_USER, UPDATE_USER,\nDELETE_USER, INVALIDATE_SESSIONS, or GENERATE_API_TOKEN).\nAdmin users automatically have all permissions.\nNote: The root user (ID: 00000000-0000-0000-0000-000000000000) cannot be modified or deleted.\nNote: Users cannot modify their own account through this service (use self-service endpoints instead)." } ], "paths": { "/v1/instances/p0/automation:applyPreset": { "post": { "summary": "Apply automation preset", "operationId": "soulfire_v1_AutomationService_ApplyAutomationPreset_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "ApplyAutomationPreset", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Updates instance automation coordination settings and selected bots' automation defaults." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "bot_ids": { "type": "array", "items": { "type": "string" }, "format": "uuid" }, "preset": { "type": "object", "additionalProperties": true } }, "required": ["preset"] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.ApplyAutomationPresetResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/automation/bots/:bot_id": { "get": { "summary": "Get automation bot state", "operationId": "soulfire_v1_AutomationService_GetAutomationBotState_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "GetAutomationBotState", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["READ_BOT_INFO"], "x-soulfire-scope": "instance.bot", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GetAutomationBotStateResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/automation/coordination": { "get": { "summary": "Get automation coordination state", "operationId": "soulfire_v1_AutomationService_GetAutomationCoordinationState_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "GetAutomationCoordinationState", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["READ_BOT_INFO"], "x-soulfire-scope": "instance", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "max_entries", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GetAutomationCoordinationStateResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/automation/bots/:bot_id/memory": { "get": { "summary": "Get automation memory state", "operationId": "soulfire_v1_AutomationService_GetAutomationMemoryState_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "GetAutomationMemoryState", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["READ_BOT_INFO"], "x-soulfire-scope": "instance.bot", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "max_entries", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GetAutomationMemoryStateResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/automation": { "get": { "summary": "Get automation team state", "operationId": "soulfire_v1_AutomationService_GetAutomationTeamState_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "GetAutomationTeamState", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["READ_BOT_INFO"], "x-soulfire-scope": "instance", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GetAutomationTeamStateResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:pause": { "post": { "summary": "Pause automation", "operationId": "soulfire_v1_AutomationService_PauseAutomation_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "PauseAutomation", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["INSTANCE_COMMAND_EXECUTION"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Pauses automation without clearing the current goal." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "bot_ids": { "type": "array", "items": { "type": "string" }, "format": "uuid" } }, "required": [] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.AutomationActionResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:releaseBotClaims": { "post": { "summary": "Release automation bot claims", "operationId": "soulfire_v1_AutomationService_ReleaseAutomationBotClaims_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "ReleaseAutomationBotClaims", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["INSTANCE_COMMAND_EXECUTION"], "x-soulfire-scope": "instance.bot", "x-soulfire-side-effects": [ "Releases shared automation claims owned by the selected connected bots." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "bot_ids": { "type": "array", "items": { "type": "string" }, "format": "uuid" } }, "required": [] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.ReleaseAutomationBotClaimsResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:releaseClaim": { "post": { "summary": "Release automation claim", "operationId": "soulfire_v1_AutomationService_ReleaseAutomationClaim_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "ReleaseAutomationClaim", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["INSTANCE_COMMAND_EXECUTION"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Releases one shared automation claim by exact key." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "key": { "type": "string" } }, "required": ["key"] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.ReleaseAutomationClaimResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:resetCoordination": { "post": { "summary": "Reset automation coordination state", "operationId": "soulfire_v1_AutomationService_ResetAutomationCoordinationState_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "ResetAutomationCoordinationState", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["INSTANCE_COMMAND_EXECUTION"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Clears shared automation claims, shared structure intelligence, and eye samples for the instance." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.ResetAutomationCoordinationStateResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:resetMemory": { "post": { "summary": "Reset automation memory", "operationId": "soulfire_v1_AutomationService_ResetAutomationMemory_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "ResetAutomationMemory", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["INSTANCE_COMMAND_EXECUTION"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Clears remembered automation world state for the selected connected bots and forces replanning." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "bot_ids": { "type": "array", "items": { "type": "string" }, "format": "uuid" } }, "required": [] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.ResetAutomationMemoryResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:resume": { "post": { "summary": "Resume automation", "operationId": "soulfire_v1_AutomationService_ResumeAutomation_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "ResumeAutomation", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["INSTANCE_COMMAND_EXECUTION"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Resumes automation for the selected connected bots." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "bot_ids": { "type": "array", "items": { "type": "string" }, "format": "uuid" } }, "required": [] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.AutomationActionResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:setCollaboration": { "post": { "summary": "Set automation collaboration", "operationId": "soulfire_v1_AutomationService_SetAutomationCollaboration_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "SetAutomationCollaboration", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Toggles team orchestration by switching the instance between collaborative and independent presets." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } }, "required": ["enabled"] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.SetAutomationCollaborationResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:setMaxEndBots": { "post": { "summary": "Set automation max End bots", "operationId": "soulfire_v1_AutomationService_SetAutomationMaxEndBots_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "SetAutomationMaxEndBots", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Updates the maximum number of bots that may be active in the End at once." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "max_end_bots": { "type": "integer", "format": "int32" } }, "required": ["max_end_bots"] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.SetAutomationMaxEndBotsResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:setObjectiveOverride": { "post": { "summary": "Set automation objective override", "operationId": "soulfire_v1_AutomationService_SetAutomationObjectiveOverride_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "SetAutomationObjectiveOverride", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Forces or clears the team automation objective override for the instance." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "objective": { "type": "object", "additionalProperties": true } }, "required": ["objective"] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.SetAutomationObjectiveOverrideResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:setRoleOverride": { "post": { "summary": "Set automation role override", "operationId": "soulfire_v1_AutomationService_SetAutomationRoleOverride_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "SetAutomationRoleOverride", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-side-effects": [ "Forces or clears the automation role override for the selected configured bots." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "bot_ids": { "type": "array", "items": { "type": "string" }, "format": "uuid" }, "role": { "type": "object", "additionalProperties": true } }, "required": ["role"] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.SetAutomationRoleOverrideResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:setRolePolicy": { "post": { "summary": "Set automation role policy", "operationId": "soulfire_v1_AutomationService_SetAutomationRolePolicy_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "SetAutomationRolePolicy", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Changes how the automation coordinator assigns roles for the instance." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "role_policy": { "type": "object", "additionalProperties": true } }, "required": ["role_policy"] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.SetAutomationRolePolicyResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:setSharedClaims": { "post": { "summary": "Set automation shared claims", "operationId": "soulfire_v1_AutomationService_SetAutomationSharedClaims_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "SetAutomationSharedClaims", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Enables or disables cross-bot target reservation for shared automation work." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } }, "required": ["enabled"] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.SetAutomationSharedClaimsResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:setSharedEndEntry": { "post": { "summary": "Set automation shared End entry", "operationId": "soulfire_v1_AutomationService_SetAutomationSharedEndEntry_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "SetAutomationSharedEndEntry", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Enables or disables shared throttling for End entry across the team." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } }, "required": ["enabled"] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.SetAutomationSharedEndEntryResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:setSharedStructures": { "post": { "summary": "Set automation shared structures", "operationId": "soulfire_v1_AutomationService_SetAutomationSharedStructures_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "SetAutomationSharedStructures", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Enables or disables cross-bot sharing of structure hints and portal/eye intelligence." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } }, "required": ["enabled"] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.SetAutomationSharedStructuresResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:acquire": { "post": { "summary": "Start automation acquire", "operationId": "soulfire_v1_AutomationService_StartAutomationAcquire_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "StartAutomationAcquire", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["INSTANCE_COMMAND_EXECUTION"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Starts an acquire goal for the selected connected bots." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "bot_ids": { "type": "array", "items": { "type": "string" }, "format": "uuid" }, "target": { "type": "string" }, "count": { "type": "integer", "format": "int32" } }, "required": ["target", "count"] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.AutomationActionResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:beat": { "post": { "summary": "Start automation beat", "operationId": "soulfire_v1_AutomationService_StartAutomationBeat_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "StartAutomationBeat", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["INSTANCE_COMMAND_EXECUTION"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Starts beat-the-game automation for the selected connected bots." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "bot_ids": { "type": "array", "items": { "type": "string" }, "format": "uuid" } }, "required": [] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.AutomationActionResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/automation:stop": { "post": { "summary": "Stop automation", "operationId": "soulfire_v1_AutomationService_StopAutomation_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.AutomationService", "x-soulfire-grpc-method": "StopAutomation", "x-soulfire-unary-only": true, "tags": ["AutomationService"], "x-soulfire-permissions": ["INSTANCE_COMMAND_EXECUTION"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Stops automation and clears the current goal for the selected connected bots." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "bot_ids": { "type": "array", "items": { "type": "string" }, "format": "uuid" } }, "required": [] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.AutomationActionResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/bots/p1/container/buttons/p2:click": { "post": { "summary": "Click container button", "description": "Clicks a container-specific action button.\nUsed for: stonecutter recipes, enchanting, loom patterns, villager trades,\nbeacon effects, crafter slot toggles, lectern page navigation.\nThe action is queued and executed on the next game tick.", "operationId": "soulfire_v1_BotService_ClickContainerButton_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "ClickContainerButton", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-execution": "Queued for the next game tick", "x-soulfire-side-effects": [ "Activates the selected container-specific action button." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot clicking the button.", "schema": { "type": "string", "format": "uuid" } }, { "name": "button_id", "in": "path", "required": true, "description": "The button ID to click.\nValid values depend on container type:\n- Stonecutter: 0-99 (recipe index)\n- Enchanting table: 0-2 (enchantment slot)\n- Loom: 0-99 (pattern index)\n- Villager: 0 to (offer count - 1)\n- Beacon: mob effect registry ID, -1 for confirm\n- Crafter: 0-8 (slot toggle index)\n- Lectern: 1=prev page, 2=next page, 3=take book", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Response for container button click action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotContainerButtonClickResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/bots/p1/dialog/buttons/p2:click": { "post": { "summary": "Click dialog button", "description": "Clicks a button in the current dialog.\nButton index depends on dialog type (see BotClickDialogButtonRequest).\nThe dialog is typically closed after the button click.\nNote: Full dialog button packets are not yet implemented; this clears local state.", "operationId": "soulfire_v1_BotService_ClickDialogButton_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "ClickDialogButton", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-execution": "Immediate", "x-soulfire-side-effects": [ "Invokes a dialog action and usually clears the local dialog state." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot clicking the button.", "schema": { "type": "string", "format": "uuid" } }, { "name": "button_index", "in": "path", "required": true, "description": "Index of the button to click.\nFor NOTICE: 0 for the action button\nFor CONFIRMATION: 0 for yes, 1 for no\nFor MULTI_ACTION: index into the actions list\nSpecial value: -1 to close/escape the dialog", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Response for dialog button click.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotClickDialogButtonResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/bots/p1/inventory/slots/p2:click": { "post": { "summary": "Click inventory slot", "description": "Performs a click action on an inventory/container slot.\nSupports various click types (left, right, shift, drop, swap, middle).\nThe bot must be online with a valid player and gameMode.", "operationId": "soulfire_v1_BotService_ClickInventorySlot_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "ClickInventorySlot", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-preconditions": [ "Bot must be online.", "Player and game mode state must be available." ], "x-soulfire-execution": "Immediate", "x-soulfire-side-effects": [ "Clicks the open container or player inventory." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot performing the inventory action.", "schema": { "type": "string", "format": "uuid" } }, { "name": "slot", "in": "path", "required": true, "description": "The slot index to click.\nValid range depends on the currently open container.\nSpecial value: -999 for clicking outside the inventory (dropping items).", "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "click_type": { "type": "object", "additionalProperties": true, "description": "The type of click to perform.\nDifferent click types have different effects on items." }, "hotbar_slot": { "type": "integer", "format": "int32", "description": "For SWAP_HOTBAR click type: which hotbar slot to swap with.\nRange: 0-8 (corresponding to hotbar slots 1-9).\nIgnored for other click types." } }, "required": ["click_type"] } } } }, "responses": { "200": { "description": "Response for inventory click action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotInventoryClickResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/bots/p1/container:close": { "post": { "summary": "Close container", "description": "Closes the currently open container (chest, crafting table, etc.).\nReturns to the player inventory view.\nThe bot must be online with a valid player.", "operationId": "soulfire_v1_BotService_CloseContainer_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "CloseContainer", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-preconditions": [ "Bot must be online.", "Player state must be available." ], "x-soulfire-execution": "Immediate", "x-soulfire-side-effects": ["Closes the current container view."], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot to close container for.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response for container close action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotCloseContainerResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/bots/p1/dialog:close": { "post": { "summary": "Close dialog", "description": "Closes/dismisses the current dialog.\nClears the local dialog state.", "operationId": "soulfire_v1_BotService_CloseDialog_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "CloseDialog", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-execution": "Immediate", "x-soulfire-side-effects": [ "Closes the current dialog and clears the local dialog state." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot to close dialog for.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response for dialog close.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotCloseDialogResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/bots/:bot_id": { "get": { "summary": "Get bot", "description": "Returns detailed information about a specific bot.\nIncludes full live state with complete inventory data when the bot is online.", "operationId": "soulfire_v1_BotService_GetBotInfo_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "GetBotInfo", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["READ_BOT_INFO"], "x-soulfire-scope": "instance.bot", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.\nMust be a valid UUID string format (e.g., \"550e8400-e29b-41d4-a716-446655440000\").", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot (Minecraft account UUID).\nMust be a valid UUID string format.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response containing detailed information about a specific bot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotInfoResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/bots": { "get": { "summary": "List bots", "description": "Returns a list of all bots configured in the specified instance.\nIncludes both online and offline bots with their current status.\nFor online bots, includes live state (position, health, etc.) but NOT full inventory data.", "operationId": "soulfire_v1_BotService_GetBotList_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "GetBotList", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["READ_BOT_INFO"], "x-soulfire-scope": "instance", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance to list bots from.\nMust be a valid UUID string format.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response containing the list of all bots in an instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotListResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/bots/:bot_id/dialog": { "get": { "summary": "Get dialog", "description": "Returns the currently displayed server dialog (Minecraft 1.21.6+).\nDialogs are server-sent UI screens for custom interactions.\nReturns empty response if no dialog is being shown.\nDoes not require the bot to be online (but dialog will be absent).", "operationId": "soulfire_v1_BotService_GetDialog_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "GetDialog", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["READ_BOT_INFO"], "x-soulfire-scope": "instance.bot", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot to get dialog for.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response containing the current dialog state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotGetDialogResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/bots/:bot_id/inventory": { "get": { "summary": "Get inventory state", "description": "Returns the current state of the bot's open container/inventory.\nIncludes layout information, slot contents, and carried item.\nThe bot must be online with a valid player.", "operationId": "soulfire_v1_BotService_GetInventoryState_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "GetInventoryState", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["READ_BOT_INFO"], "x-soulfire-scope": "instance.bot", "x-soulfire-preconditions": [ "Bot should be online for live container data." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot to get inventory state for.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response containing the current inventory/container state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotInventoryStateResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/bots/p1/mouse:click": { "post": { "summary": "Mouse click", "description": "Simulates a mouse click in the game world.\nLeft click: attack entity or start breaking block.\nRight click: use item or interact with entity/block.\nThe bot must be online with valid player, level, and gameMode.", "operationId": "soulfire_v1_BotService_MouseClick_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "MouseClick", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-preconditions": [ "Bot must be online.", "Player, level, and game mode state must be available." ], "x-soulfire-execution": "Immediate", "x-soulfire-side-effects": [ "Triggers a world interaction using the selected mouse button." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot performing the click.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "button": { "type": "object", "additionalProperties": true, "description": "Which mouse button to simulate clicking." } }, "required": ["button"] } } } }, "responses": { "200": { "description": "Response for mouse click action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotMouseClickResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/bots/p1/inventory:open": { "post": { "summary": "Open inventory", "description": "Opens the player's inventory screen.\nSends a packet to the server to display the inventory UI.\nThe bot must be online with a valid player.", "operationId": "soulfire_v1_BotService_OpenInventory_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "OpenInventory", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-preconditions": [ "Bot must be online.", "Player state must be available." ], "x-soulfire-execution": "Immediate", "x-soulfire-side-effects": ["Opens the player inventory screen."], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot to open inventory for.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response for inventory open action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotOpenInventoryResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/bots/p1/pov:render": { "get": { "summary": "Render bot POV", "description": "Renders the bot's point-of-view as a PNG image using software rendering.\nThe bot must be online with a valid player and level.\nUses the bot's current render distance setting.", "operationId": "soulfire_v1_BotService_RenderBotPov_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "RenderBotPov", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["READ_BOT_INFO"], "x-soulfire-scope": "instance.bot", "x-soulfire-preconditions": [ "Bot must be online.", "Player and level state must be available." ], "x-soulfire-execution": "Immediate", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot to render POV for.", "schema": { "type": "string", "format": "uuid" } }, { "name": "width", "in": "query", "required": true, "description": "Desired image width in pixels.\nDefault: 854 (if 0 or not provided).\nMaximum: 1920 (values above this are clamped).\nMinimum: 1 (values below this are clamped).", "schema": { "type": "integer", "format": "int32" } }, { "name": "height", "in": "query", "required": true, "description": "Desired image height in pixels.\nDefault: 480 (if 0 or not provided).\nMaximum: 1080 (values above this are clamped).\nMinimum: 1 (values below this are clamped).", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Response containing the rendered POV image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotRenderPovResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/bots/p1/movement:reset": { "post": { "summary": "Reset movement", "description": "Resets all movement to stopped state.\nEquivalent to releasing all movement keys.\nThe action is queued and executed on the next game tick.", "operationId": "soulfire_v1_BotService_ResetMovement_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "ResetMovement", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-execution": "Queued for the next game tick", "x-soulfire-side-effects": ["Clears all movement inputs."], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot to stop movement for.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response for movement reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotResetMovementResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/bots/p1/container/text-inputs/p2:set": { "post": { "summary": "Set container text", "description": "Sets text in a container's text input field.\nCurrently only supports anvil item renaming (field_id: \"item_name\").\nThe action is queued and executed on the next game tick.", "operationId": "soulfire_v1_BotService_SetContainerText_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "SetContainerText", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-execution": "Queued for the next game tick", "x-soulfire-side-effects": [ "Updates the selected container text input." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot setting the text.", "schema": { "type": "string", "format": "uuid" } }, { "name": "field_id", "in": "path", "required": true, "description": "Which field to set the text for.\nCurrently supported: \"item_name\" (anvil rename)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": "string", "description": "The text value to set.\nFor anvil: max 50 characters for the item name." } }, "required": ["text"] } } } }, "responses": { "200": { "description": "Response for container text input action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotSetContainerTextResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/bots/p1/hotbar/p2:select": { "post": { "summary": "Select hotbar slot", "description": "Changes the selected hotbar slot.\nValid slot range: 0-8 (corresponding to slots 1-9 in the UI).\nThe action is queued and executed on the next game tick.", "operationId": "soulfire_v1_BotService_SetHotbarSlot_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "SetHotbarSlot", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-execution": "Queued for the next game tick", "x-soulfire-side-effects": ["Changes the selected hotbar slot."], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot to change hotbar selection for.", "schema": { "type": "string", "format": "uuid" } }, { "name": "slot", "in": "path", "required": true, "description": "Hotbar slot index to select.\nRange: 0-8 (corresponding to slots 1-9 in the UI).", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Response for hotbar slot selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotSetHotbarSlotResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/bots/p1/movement:set": { "post": { "summary": "Set movement state", "description": "Updates the bot's movement state (WASD, jump, sneak, sprint).\nOnly specified fields are changed; omitted fields retain their current value.\nMovement persists until explicitly changed or reset.\nThe action is queued and executed on the next game tick.", "operationId": "soulfire_v1_BotService_SetMovementState_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "SetMovementState", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-execution": "Queued for the next game tick", "x-soulfire-side-effects": [ "Updates the persisted movement control state." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot to control.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "forward": { "type": "boolean", "description": "W key state - move forward.\ntrue = pressing W, false = not pressing W" }, "backward": { "type": "boolean", "description": "S key state - move backward.\ntrue = pressing S, false = not pressing S" }, "left": { "type": "boolean", "description": "A key state - strafe left.\ntrue = pressing A, false = not pressing A" }, "right": { "type": "boolean", "description": "D key state - strafe right.\ntrue = pressing D, false = not pressing D" }, "jump": { "type": "boolean", "description": "Space key state - jump.\ntrue = pressing Space, false = not pressing Space\nWhen held, the bot will jump repeatedly." }, "sneak": { "type": "boolean", "description": "Shift key state - sneak/crouch.\ntrue = sneaking, false = not sneaking\nWhile sneaking: slower movement, won't fall off edges, crouching animation." }, "sprint": { "type": "boolean", "description": "Ctrl key state - sprint.\ntrue = sprinting, false = not sprinting\nRequires forward movement and sufficient hunger (food level >= 6)." } }, "required": [] } } } }, "responses": { "200": { "description": "Response for movement state update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotSetMovementStateResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/bots/p1/rotation:set": { "post": { "summary": "Set bot rotation", "description": "Sets the bot's view rotation (look direction).\nYaw is normalized to -180 to 180, pitch is clamped to -90 to 90.\nThe action is queued and executed on the next game tick.", "operationId": "soulfire_v1_BotService_SetRotation_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "SetRotation", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-execution": "Queued for the next game tick", "x-soulfire-side-effects": ["Updates the bot's look direction."], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot to rotate.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "yaw": { "type": "number", "format": "float", "description": "Horizontal rotation angle in degrees (yaw).\nRange: -180 to 180 (values outside this range are normalized).\nDirection mapping: 0 = South, 90 = West, -90 = East, +/-180 = North." }, "pitch": { "type": "number", "format": "float", "description": "Vertical rotation angle in degrees (pitch).\nRange: -90 to 90 (values outside this range are clamped).\nDirection mapping: -90 = looking up, 0 = horizon, 90 = looking down." } }, "required": ["yaw", "pitch"] } } } }, "responses": { "200": { "description": "Response for rotation update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotSetRotationResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/bots/p1/dialog:submit": { "post": { "summary": "Submit dialog", "description": "Submits a dialog with input values.\nUsed for dialogs containing text fields, checkboxes, dropdowns, or sliders.\nThe dialog is closed after submission.\nNote: Full dialog response packets are not yet implemented; this clears local state.", "operationId": "soulfire_v1_BotService_SubmitDialog_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "SubmitDialog", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-execution": "Immediate", "x-soulfire-side-effects": [ "Submits the current dialog and clears the local dialog state." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot submitting the dialog.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input_values": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Map of input key to value for each input field.\nKeys must match the `key` field of DialogInput elements." } }, "required": [] } } } }, "responses": { "200": { "description": "Response for dialog submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotSubmitDialogResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/bots/:bot_id/config/namespaces/:namespace/entries/:key": { "patch": { "summary": "Update bot config entry", "description": "Updates a single configuration entry for a specific bot.\nThe configuration is persisted to the database immediately.", "operationId": "soulfire_v1_BotService_UpdateBotConfigEntry_PATCH", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.BotService", "x-soulfire-grpc-method": "UpdateBotConfigEntry", "x-soulfire-unary-only": true, "tags": ["BotService"], "x-soulfire-permissions": ["UPDATE_BOT_CONFIG"], "x-soulfire-scope": "instance.bot", "x-soulfire-side-effects": [ "Persists the new setting value immediately." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance containing the bot.", "schema": { "type": "string", "format": "uuid" } }, { "name": "bot_id", "in": "path", "required": true, "description": "The profile UUID of the bot to update configuration for.", "schema": { "type": "string", "format": "uuid" } }, { "name": "namespace", "in": "path", "required": true, "description": "The settings namespace (e.g., plugin ID or \"bot\" for core bot settings).\nExamples: \"bot\", \"auto-reconnect\", \"chat-message-controller\"", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "The key within the namespace to update.\nMust be a valid setting key defined for that namespace.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "object", "additionalProperties": true, "description": "The new value to set for this configuration entry.\nMust be a valid protobuf Value (null, number, string, bool, list, or struct)." } }, "required": ["value"] } } } }, "responses": { "200": { "description": "Response for bot configuration entry update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.BotUpdateConfigEntryResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/client/tokens/api:generate": { "post": { "summary": "Generate API token", "description": "Generates a new JWT token for API authentication.\nThe generated token has the \"api\" audience and can be used for gRPC/HTTP API calls.", "operationId": "soulfire_v1_ClientService_GenerateAPIToken_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ClientService", "x-soulfire-grpc-method": "GenerateAPIToken", "x-soulfire-unary-only": true, "tags": ["ClientService"], "x-soulfire-permissions": ["GENERATE_SELF_API_TOKEN"], "x-soulfire-scope": "client.self", "x-soulfire-side-effects": ["Issues a new JWT with the api audience."], "responses": { "200": { "description": "Response containing a newly generated API authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GenerateAPITokenResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/client/tokens/webdav:generate": { "post": { "summary": "Generate WebDAV token", "description": "Generates a new JWT token specifically for WebDAV authentication.\nThe generated token has the \"webdav\" audience and can only be used for WebDAV access.", "operationId": "soulfire_v1_ClientService_GenerateWebDAVToken_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ClientService", "x-soulfire-grpc-method": "GenerateWebDAVToken", "x-soulfire-unary-only": true, "tags": ["ClientService"], "x-soulfire-permissions": ["GENERATE_SELF_WEBDAV_TOKEN"], "x-soulfire-scope": "client.self", "x-soulfire-side-effects": [ "Issues a new JWT with the webdav audience." ], "responses": { "200": { "description": "Response containing a newly generated WebDAV authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GenerateWebDAVTokenResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/client": { "get": { "summary": "Get client data", "description": "Retrieves comprehensive data about the authenticated client and the server.\nReturns user profile information, granted permissions, and server metadata.", "operationId": "soulfire_v1_ClientService_GetClientData_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ClientService", "x-soulfire-grpc-method": "GetClientData", "x-soulfire-unary-only": true, "tags": ["ClientService"], "x-soulfire-permissions": ["READ_CLIENT_DATA"], "x-soulfire-scope": "client.self", "responses": { "200": { "description": "Response containing comprehensive information about the authenticated client and server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.ClientDataResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/client/sessions:invalidate": { "post": { "summary": "Invalidate self sessions", "description": "Invalidates all existing sessions for the currently authenticated user.\nThis is done by setting the user's minIssuedAt timestamp to the current time,\nwhich causes all previously issued JWT tokens to become invalid.\nAfter calling this method, the user will need to re-authenticate on all devices.", "operationId": "soulfire_v1_ClientService_InvalidateSelfSessions_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ClientService", "x-soulfire-grpc-method": "InvalidateSelfSessions", "x-soulfire-unary-only": true, "tags": ["ClientService"], "x-soulfire-permissions": ["INVALIDATE_SELF_SESSIONS"], "x-soulfire-scope": "client.self", "x-soulfire-side-effects": [ "Revokes previously issued tokens for the current user." ], "responses": { "200": { "description": "Response message for session invalidation operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InvalidateSelfSessionsResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/client/email": { "patch": { "summary": "Update self email", "description": "Updates the email address of the currently authenticated user.\nThe change is persisted to the database immediately.", "operationId": "soulfire_v1_ClientService_UpdateSelfEmail_PATCH", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ClientService", "x-soulfire-grpc-method": "UpdateSelfEmail", "x-soulfire-unary-only": true, "tags": ["ClientService"], "x-soulfire-permissions": ["UPDATE_SELF_EMAIL"], "x-soulfire-scope": "client.self", "x-soulfire-side-effects": [ "Persists the new email address immediately." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "description": "The new email address to set for the current user.\nThis will replace the existing email in the database." } }, "required": ["email"] }, "example": { "email": "" } } } }, "responses": { "200": { "description": "Response message for email update operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.UpdateSelfEmailResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/client/username": { "patch": { "summary": "Update self username", "description": "Updates the username of the currently authenticated user.\nThe change is persisted to the database immediately.", "operationId": "soulfire_v1_ClientService_UpdateSelfUsername_PATCH", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ClientService", "x-soulfire-grpc-method": "UpdateSelfUsername", "x-soulfire-unary-only": true, "tags": ["ClientService"], "x-soulfire-permissions": ["UPDATE_SELF_USERNAME"], "x-soulfire-scope": "client.self", "x-soulfire-side-effects": ["Persists the new username immediately."], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "username": { "type": "string", "description": "The new username to set for the current user.\nThis will replace the existing username in the database." } }, "required": ["username"] }, "example": { "username": "" } } } }, "responses": { "200": { "description": "Response message for username update operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.UpdateSelfUsernameResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/commands:execute": { "post": { "summary": "Execute command", "description": "Executes a command string within the specified scope.\nThe command is parsed and executed using the Brigadier command dispatcher.\n\nPermission requirements depend on the scope:\n- Global scope: Requires GLOBAL_COMMAND_EXECUTION permission\n- Instance scope: Requires INSTANCE_COMMAND_EXECUTION for the instance\n- Bot scope: Requires INSTANCE_COMMAND_EXECUTION for the parent instance", "operationId": "soulfire_v1_CommandService_ExecuteCommand_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.CommandService", "x-soulfire-grpc-method": "ExecuteCommand", "x-soulfire-unary-only": true, "tags": ["CommandService"], "x-soulfire-scope": "command.scope", "x-soulfire-side-effects": [ "Executes a Brigadier command in the requested scope." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "scope.instance.instance_id": { "type": "string", "format": "uuid", "description": "The unique identifier (UUID) of the instance to scope commands to.\nMust be a valid UUID string." }, "scope.bot.instance_id": { "type": "string", "format": "uuid", "description": "The unique identifier (UUID) of the instance containing the bot.\nMust be a valid UUID string." }, "scope.bot.bot_id": { "type": "string", "format": "uuid", "description": "The unique identifier (UUID) of the bot (profile ID) to scope commands to.\nMust be a valid UUID string matching the bot's account profile ID." }, "command": { "type": "string", "description": "The command string to execute. This follows the Brigadier command format,\ne.g., \"help\", \"move 100 64 200\", \"say Hello world\".\nLeading/trailing whitespace will be stripped before execution." } }, "required": [ "scope.instance.instance_id", "scope.bot.instance_id", "scope.bot.bot_id", "command" ] }, "example": { "command": "" } } } }, "responses": { "200": { "description": "Response message containing the result of command execution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.CommandResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/commands:complete": { "post": { "summary": "Complete command", "description": "Retrieves tab-completion suggestions for a partial command.\nUses Brigadier's completion system to generate context-aware suggestions\nbased on the command structure and current cursor position.\n\nPermission requirements depend on the scope (same as ExecuteCommand).", "operationId": "soulfire_v1_CommandService_TabCompleteCommand_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.CommandService", "x-soulfire-grpc-method": "TabCompleteCommand", "x-soulfire-unary-only": true, "tags": ["CommandService"], "x-soulfire-scope": "command.scope", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "scope.instance.instance_id": { "type": "string", "format": "uuid", "description": "The unique identifier (UUID) of the instance to scope commands to.\nMust be a valid UUID string." }, "scope.bot.instance_id": { "type": "string", "format": "uuid", "description": "The unique identifier (UUID) of the instance containing the bot.\nMust be a valid UUID string." }, "scope.bot.bot_id": { "type": "string", "format": "uuid", "description": "The unique identifier (UUID) of the bot (profile ID) to scope commands to.\nMust be a valid UUID string matching the bot's account profile ID." }, "command": { "type": "string", "description": "The partial command string to complete. May be an incomplete command\nthat the user is typing, e.g., \"mov\" or \"move 100 \"." }, "cursor": { "type": "integer", "format": "int32", "description": "The cursor position within the command string (0-indexed).\nCompletions will be generated for the token at this position.\nTypically this is the length of the command string for end-of-line completion." } }, "required": [ "scope.instance.instance_id", "scope.bot.instance_id", "scope.bot.bot_id", "command", "cursor" ] }, "example": { "command": "", "cursor": 0 } } } }, "responses": { "200": { "description": "Response message containing tab-completion suggestions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.CommandCompletionResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/downloads:fetch": { "post": { "summary": "Download URL", "description": "Downloads content from the specified URI and returns the response.\n\nMakes an HTTP GET request to the URI specified in the request, optionally\nrouting through a proxy. Custom headers can be provided to customize the request.", "operationId": "soulfire_v1_DownloadService_Download_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.DownloadService", "x-soulfire-grpc-method": "Download", "x-soulfire-unary-only": true, "tags": ["DownloadService"], "x-soulfire-permissions": ["DOWNLOAD_URL"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Fetches remote content through the server's network stack." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance to associate this download with.\nUsed for permission checking - the caller must have DOWNLOAD_URL permission\nfor this instance. Must be a valid UUID string (e.g., \"550e8400-e29b-41d4-a716-446655440000\").", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "uri": { "type": "string", "format": "uri", "description": "The URI to download content from. Must be a valid, fully-formed URI\n(e.g., \"https://example.com/resource.json\"). The server will make an HTTP GET\nrequest to this URI." }, "headers.key": { "type": "string" }, "headers.value": { "type": "string" }, "proxy.type": { "type": "object", "additionalProperties": true, "description": "The proxy protocol type. Determines how the connection is established." }, "proxy.address": { "type": "string", "description": "The proxy server address in \"host:port\" format (e.g., \"proxy.example.com:8080\").\nThe address must be resolvable and the port must be valid (1-65535)." }, "proxy.username": { "type": "string", "description": "Optional username for proxy authentication.\nRequired if the proxy server requires authentication.\nIf password is set, username must also be set." }, "proxy.password": { "type": "string", "description": "Optional password for proxy authentication.\nUsed with username for SOCKS5 or HTTP proxy authentication.\nNot supported for SOCKS4 proxies (will cause an error if set)." } }, "required": ["uri"] } } } }, "responses": { "200": { "description": "Response message containing the downloaded content and metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.DownloadResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:id/accounts": { "post": { "summary": "Add instance account", "description": "Adds a Minecraft account to the instance.\nThe account's profile_id must be unique within the instance.", "operationId": "soulfire_v1_InstanceService_AddInstanceAccount_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "AddInstanceAccount", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance.account", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "account.type": { "type": "object", "additionalProperties": true, "description": "The authentication type used for this account.\nDetermines which account_data field is populated." }, "account.profile_id": { "type": "string", "description": "The unique profile identifier (UUID) for this account.\nFor online accounts: The official Minecraft profile UUID from Microsoft.\nFor offline accounts: A deterministic UUID derived from the username.\nFormat: Standard UUID string (e.g., \"550e8400-e29b-41d4-a716-446655440000\")." }, "account.last_known_name": { "type": "string", "description": "The last known username/gamertag for this account.\nUpdated during authentication and refresh operations.\nFor Java: The Minecraft username (up to 16 characters).\nFor Bedrock: The Xbox gamertag." }, "account.online_chain_java_data.auth_chain": { "type": "object", "additionalProperties": true, "description": "JSON structure containing the complete authentication chain from minecraftauth library.\nIncludes Microsoft OAuth tokens, Xbox Live tokens, and Minecraft access tokens.\nThis data can be refreshed to obtain new tokens without re-authentication." }, "account.bedrock_data.auth_chain": { "type": "object", "additionalProperties": true, "description": "JSON structure containing the complete Bedrock authentication chain.\nIncludes Xbox Live tokens and Bedrock-specific session data.\nCompatible with the ViaBedrock protocol implementation." }, "account.online_simple_java_data.access_token": { "type": "string", "description": "The raw Minecraft access token (JWT)." }, "account.online_simple_java_data.expire_time_ms": { "type": "integer", "format": "int64", "description": "Token expiry time in milliseconds since epoch." }, "account.config.namespace": { "type": "string" }, "account.config.entries.key": { "type": "string" }, "account.config.entries.value": { "type": "object", "additionalProperties": true }, "account.persistent_metadata.namespace": { "type": "string" }, "account.persistent_metadata.entries.key": { "type": "string" }, "account.persistent_metadata.entries.value": { "type": "object", "additionalProperties": true } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully adding an account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceAddAccountResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/accounts:batchAdd": { "post": { "summary": "Batch add instance accounts", "description": "Adds multiple Minecraft accounts to the instance in a single operation.\nMore efficient than multiple AddInstanceAccount calls.", "operationId": "soulfire_v1_InstanceService_AddInstanceAccountsBatch_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "AddInstanceAccountsBatch", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance.account", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "accounts.type": { "type": "object", "additionalProperties": true }, "accounts.profile_id": { "type": "string" }, "accounts.last_known_name": { "type": "string" }, "accounts.online_chain_java_data.auth_chain": { "type": "object", "additionalProperties": true }, "accounts.bedrock_data.auth_chain": { "type": "object", "additionalProperties": true }, "accounts.online_simple_java_data.access_token": { "type": "string" }, "accounts.online_simple_java_data.expire_time_ms": { "type": "integer", "format": "int64" }, "accounts.config.namespace": { "type": "string" }, "accounts.config.entries.key": { "type": "string" }, "accounts.config.entries.value": { "type": "object", "additionalProperties": true }, "accounts.persistent_metadata.namespace": { "type": "string" }, "accounts.persistent_metadata.entries.key": { "type": "string" }, "accounts.persistent_metadata.entries.value": { "type": "object", "additionalProperties": true } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully adding accounts in batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceAddAccountsBatchResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/proxies:batchAdd": { "post": { "summary": "Batch add instance proxies", "description": "Adds multiple proxies to the instance in a single operation.\nMore efficient than multiple AddInstanceProxy calls.", "operationId": "soulfire_v1_InstanceService_AddInstanceProxiesBatch_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "AddInstanceProxiesBatch", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance.proxy", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "proxies.type": { "type": "object", "additionalProperties": true }, "proxies.address": { "type": "string" }, "proxies.username": { "type": "string" }, "proxies.password": { "type": "string" } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully adding proxies in batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceAddProxiesBatchResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:id/proxies": { "post": { "summary": "Add instance proxy", "description": "Adds a proxy to the instance.", "operationId": "soulfire_v1_InstanceService_AddInstanceProxy_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "AddInstanceProxy", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance.proxy", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "proxy.type": { "type": "object", "additionalProperties": true, "description": "The proxy protocol type. Determines how the connection is established." }, "proxy.address": { "type": "string", "description": "The proxy server address in \"host:port\" format (e.g., \"proxy.example.com:8080\").\nThe address must be resolvable and the port must be valid (1-65535)." }, "proxy.username": { "type": "string", "description": "Optional username for proxy authentication.\nRequired if the proxy server requires authentication.\nIf password is set, username must also be set." }, "proxy.password": { "type": "string", "description": "Optional password for proxy authentication.\nUsed with username for SOCKS5 or HTTP proxy authentication.\nNot supported for SOCKS4 proxies (will cause an error if set)." } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully adding a proxy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceAddProxyResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0:changeState": { "post": { "summary": "Change instance state", "description": "Changes the lifecycle state of an instance.\nUsed to start, pause, resume, or stop bot sessions.\nThe operation blocks until the state transition is complete.", "operationId": "soulfire_v1_InstanceService_ChangeInstanceState_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "ChangeInstanceState", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["CHANGE_INSTANCE_STATE"], "x-soulfire-scope": "instance", "x-soulfire-execution": "Blocking until transition completes", "x-soulfire-side-effects": [ "Starts, pauses, resumes, or stops the instance." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "state": { "type": "object", "additionalProperties": true, "description": "The target state for the instance. Valid transitions:\n- STOPPED -> RUNNING: Starts the instance\n- RUNNING -> PAUSED: Pauses bot ticking\n- PAUSED -> RUNNING: Resumes bot ticking\n- RUNNING/PAUSED -> STOPPED: Stops the instance\nThe server will handle intermediate states (STARTING, STOPPING) automatically." } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully changing instance state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceStateChangeResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances": { "post": { "summary": "Create instance", "description": "Creates a new instance with the given friendly name.\nThe instance starts in STOPPED state with default configuration.", "operationId": "soulfire_v1_InstanceService_CreateInstance_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "CreateInstance", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["CREATE_INSTANCE"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Creates a new instance in the stopped state." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "friendlyName": { "type": "string", "description": "A human-readable name for the instance. This will be displayed in the UI\nand can be changed later via UpdateInstanceMeta." } }, "required": [] }, "example": { "friendlyName": "" } } } }, "responses": { "200": { "description": "Response after successfully creating an instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceCreateResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } }, "get": { "summary": "List instances", "description": "Lists all instances the current user has permission to view.\nOnly instances where the user has READ_INSTANCE permission are returned.\nReturns summary information for each instance.", "operationId": "soulfire_v1_InstanceService_ListInstances_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "ListInstances", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-scope": "instance", "responses": { "200": { "description": "Response containing a list of instances the current user has permission to view.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceListResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/accounts/:account_id/metadata/namespaces/:namespace/entries/:key": { "delete": { "summary": "Delete account metadata entry", "description": "Deletes a persistent metadata entry from a Minecraft account.", "operationId": "soulfire_v1_InstanceService_DeleteAccountMetadataEntry_DELETE", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "DeleteAccountMetadataEntry", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance.account.metadata", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance containing the account.", "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "description": "The profile_id (UUID) of the Minecraft account.", "schema": { "type": "string" } }, { "name": "namespace", "in": "path", "required": true, "description": "The namespace of the metadata entry to delete.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "The key of the metadata entry to delete.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response after successfully deleting a metadata entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.DeleteAccountMetadataEntryResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } }, "put": { "summary": "Set account metadata entry", "description": "Sets a single persistent metadata entry for a Minecraft account.\nCreates the namespace and key if they don't exist, or updates if they do.", "operationId": "soulfire_v1_InstanceService_SetAccountMetadataEntry_PUT", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "SetAccountMetadataEntry", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance.account.metadata", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance containing the account.", "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "description": "The profile_id (UUID) of the Minecraft account.", "schema": { "type": "string" } }, { "name": "namespace", "in": "path", "required": true, "description": "The namespace for the metadata entry.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "The key for the metadata entry within the namespace.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "object", "additionalProperties": true, "description": "The value to set. Supports JSON value types." } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully setting a metadata entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.SetAccountMetadataEntryResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:id": { "delete": { "summary": "Delete instance", "description": "Permanently deletes an instance and all its data.\nIf the instance is running, it will be stopped first.\nThis operation cannot be undone.", "operationId": "soulfire_v1_InstanceService_DeleteInstance_DELETE", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "DeleteInstance", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["DELETE_INSTANCE"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Deletes the target instance and its stored data." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance to delete.\nThe instance will be stopped if running before deletion.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response after successfully deleting an instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceDeleteResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } }, "get": { "summary": "Get instance", "description": "Gets detailed information about a specific instance.\nSupports conditional requests via if_modified_since to reduce bandwidth.", "operationId": "soulfire_v1_InstanceService_GetInstanceInfo_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "GetInstanceInfo", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["READ_INSTANCE"], "x-soulfire-scope": "instance", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } }, { "name": "if_modified_since", "in": "query", "required": false, "description": "Optional timestamp for conditional requests. If provided and the instance\nconfiguration has not been modified since this timestamp, the server returns\nInstanceNotModified instead of the full InstanceInfo. This helps reduce\nbandwidth for polling clients.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response for GetInstanceInfo containing either full info or a not-modified status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceInfoResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/metadata/namespaces/:namespace/entries/:key": { "delete": { "summary": "Delete instance metadata entry", "description": "Deletes a persistent metadata entry from the instance.", "operationId": "soulfire_v1_InstanceService_DeleteInstanceMetadataEntry_DELETE", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "DeleteInstanceMetadataEntry", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_META"], "x-soulfire-scope": "instance.metadata", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } }, { "name": "namespace", "in": "path", "required": true, "description": "The namespace of the metadata entry to delete.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "The key of the metadata entry to delete.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response after successfully deleting an instance metadata entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.DeleteInstanceMetadataEntryResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } }, "put": { "summary": "Set instance metadata entry", "description": "Sets a single persistent metadata entry for the instance.\nCreates the namespace and key if they don't exist, or updates if they do.", "operationId": "soulfire_v1_InstanceService_SetInstanceMetadataEntry_PUT", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "SetInstanceMetadataEntry", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_META"], "x-soulfire-scope": "instance.metadata", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } }, { "name": "namespace", "in": "path", "required": true, "description": "The namespace for the metadata entry.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "The key for the metadata entry within the namespace.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "object", "additionalProperties": true, "description": "The value to set. Supports JSON value types." } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully setting an instance metadata entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.SetInstanceMetadataEntryResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/accounts/:account_id/metadata": { "get": { "summary": "Get account metadata", "description": "Gets persistent metadata for a Minecraft account.\nPersistent metadata survives bot restarts and session changes.", "operationId": "soulfire_v1_InstanceService_GetAccountMetadata_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "GetAccountMetadata", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["READ_BOT_INFO"], "x-soulfire-scope": "instance.account.metadata", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance containing the account.", "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "description": "The profile_id (UUID) of the Minecraft account.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response containing the persistent metadata for an account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GetAccountMetadataResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:id/audit-log": { "get": { "summary": "Get audit log", "description": "Retrieves the audit log for an instance.\nReturns a list of recorded actions ordered by timestamp (newest first).", "operationId": "soulfire_v1_InstanceService_GetAuditLog_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "GetAuditLog", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["READ_INSTANCE_AUDIT_LOGS"], "x-soulfire-scope": "instance", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response containing the audit log entries for an instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceAuditLogResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/metadata": { "get": { "summary": "Get instance metadata", "description": "Gets persistent metadata for the instance itself.\nPersistent metadata survives restarts and session changes.", "operationId": "soulfire_v1_InstanceService_GetInstanceMetadata_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "GetInstanceMetadata", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["READ_INSTANCE"], "x-soulfire-scope": "instance.metadata", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response containing the persistent metadata for an instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GetInstanceMetadataResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:id/accounts/:profile_id": { "delete": { "summary": "Remove instance account", "description": "Removes a Minecraft account from the instance by profile_id.", "operationId": "soulfire_v1_InstanceService_RemoveInstanceAccount_DELETE", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "RemoveInstanceAccount", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance.account", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } }, { "name": "profile_id", "in": "path", "required": true, "description": "The profile_id (UUID) of the account to remove.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response after successfully removing an account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceRemoveAccountResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/accounts:batchRemove": { "post": { "summary": "Batch remove instance accounts", "description": "Removes multiple Minecraft accounts from the instance by their profile_ids.\nMore efficient than multiple RemoveInstanceAccount calls.", "operationId": "soulfire_v1_InstanceService_RemoveInstanceAccountsBatch_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "RemoveInstanceAccountsBatch", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance.account", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "profile_ids": { "type": "array", "items": { "type": "string" }, "description": "List of profile_ids (UUIDs) of accounts to remove." } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully removing accounts in batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceRemoveAccountsBatchResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/proxies:batchRemove": { "post": { "summary": "Batch remove instance proxies", "description": "Removes multiple proxies from the instance by their addresses.\nMore efficient than multiple RemoveInstanceProxy calls.", "operationId": "soulfire_v1_InstanceService_RemoveInstanceProxiesBatch_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "RemoveInstanceProxiesBatch", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance.proxy", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "addresses": { "type": "array", "items": { "type": "string" }, "description": "List of proxy addresses to remove (in serialized format, e.g., \"host:port\").\nProxies matching these addresses will be removed." } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully removing proxies in batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceRemoveProxiesBatchResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:id/proxies/:index": { "delete": { "summary": "Remove instance proxy", "description": "Removes a proxy from the instance by its index.", "operationId": "soulfire_v1_InstanceService_RemoveInstanceProxy_DELETE", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "RemoveInstanceProxy", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance.proxy", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } }, { "name": "index", "in": "path", "required": true, "description": "The zero-based index of the proxy to remove.\nReturns INVALID_ARGUMENT if index is out of bounds.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Response after successfully removing a proxy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceRemoveProxyResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } }, "put": { "summary": "Update instance proxy", "description": "Updates an existing proxy in the instance by its index.", "operationId": "soulfire_v1_InstanceService_UpdateInstanceProxy_PUT", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "UpdateInstanceProxy", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance.proxy", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } }, { "name": "index", "in": "path", "required": true, "description": "The zero-based index of the proxy to update.\nReturns INVALID_ARGUMENT if index is out of bounds.", "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "proxy.type": { "type": "object", "additionalProperties": true, "description": "The proxy protocol type. Determines how the connection is established." }, "proxy.address": { "type": "string", "description": "The proxy server address in \"host:port\" format (e.g., \"proxy.example.com:8080\").\nThe address must be resolvable and the port must be valid (1-65535)." }, "proxy.username": { "type": "string", "description": "Optional username for proxy authentication.\nRequired if the proxy server requires authentication.\nIf password is set, username must also be set." }, "proxy.password": { "type": "string", "description": "Optional password for proxy authentication.\nUsed with username for SOCKS5 or HTTP proxy authentication.\nNot supported for SOCKS4 proxies (will cause an error if set)." } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully updating a proxy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceUpdateProxyResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/accounts:update": { "post": { "summary": "Update instance account", "description": "Updates an existing Minecraft account in the instance.\nThe account is matched by profile_id and replaced.", "operationId": "soulfire_v1_InstanceService_UpdateInstanceAccount_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "UpdateInstanceAccount", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance.account", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "account.type": { "type": "object", "additionalProperties": true, "description": "The authentication type used for this account.\nDetermines which account_data field is populated." }, "account.profile_id": { "type": "string", "description": "The unique profile identifier (UUID) for this account.\nFor online accounts: The official Minecraft profile UUID from Microsoft.\nFor offline accounts: A deterministic UUID derived from the username.\nFormat: Standard UUID string (e.g., \"550e8400-e29b-41d4-a716-446655440000\")." }, "account.last_known_name": { "type": "string", "description": "The last known username/gamertag for this account.\nUpdated during authentication and refresh operations.\nFor Java: The Minecraft username (up to 16 characters).\nFor Bedrock: The Xbox gamertag." }, "account.online_chain_java_data.auth_chain": { "type": "object", "additionalProperties": true, "description": "JSON structure containing the complete authentication chain from minecraftauth library.\nIncludes Microsoft OAuth tokens, Xbox Live tokens, and Minecraft access tokens.\nThis data can be refreshed to obtain new tokens without re-authentication." }, "account.bedrock_data.auth_chain": { "type": "object", "additionalProperties": true, "description": "JSON structure containing the complete Bedrock authentication chain.\nIncludes Xbox Live tokens and Bedrock-specific session data.\nCompatible with the ViaBedrock protocol implementation." }, "account.online_simple_java_data.access_token": { "type": "string", "description": "The raw Minecraft access token (JWT)." }, "account.online_simple_java_data.expire_time_ms": { "type": "integer", "format": "int64", "description": "Token expiry time in milliseconds since epoch." }, "account.config.namespace": { "type": "string" }, "account.config.entries.key": { "type": "string" }, "account.config.entries.value": { "type": "object", "additionalProperties": true }, "account.persistent_metadata.namespace": { "type": "string" }, "account.persistent_metadata.entries.key": { "type": "string" }, "account.persistent_metadata.entries.value": { "type": "object", "additionalProperties": true } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully updating an account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceUpdateAccountResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:id/config": { "patch": { "summary": "Update instance config", "description": "Replaces the entire instance configuration.\nUsed primarily for profile import operations.\nFor individual setting changes, use UpdateInstanceConfigEntry instead.", "operationId": "soulfire_v1_InstanceService_UpdateInstanceConfig_PATCH", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "UpdateInstanceConfig", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Replaces the stored instance configuration." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance to update.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "config.settings.namespace": { "type": "string" }, "config.settings.entries.key": { "type": "string" }, "config.settings.entries.value": { "type": "object", "additionalProperties": true }, "config.accounts.type": { "type": "object", "additionalProperties": true }, "config.accounts.profile_id": { "type": "string" }, "config.accounts.last_known_name": { "type": "string" }, "config.accounts.online_chain_java_data.auth_chain": { "type": "object", "additionalProperties": true }, "config.accounts.bedrock_data.auth_chain": { "type": "object", "additionalProperties": true }, "config.accounts.online_simple_java_data.access_token": { "type": "string" }, "config.accounts.online_simple_java_data.expire_time_ms": { "type": "integer", "format": "int64" }, "config.accounts.config.namespace": { "type": "string" }, "config.accounts.config.entries.key": { "type": "string" }, "config.accounts.config.entries.value": { "type": "object", "additionalProperties": true }, "config.accounts.persistent_metadata.namespace": { "type": "string" }, "config.accounts.persistent_metadata.entries.key": { "type": "string" }, "config.accounts.persistent_metadata.entries.value": { "type": "object", "additionalProperties": true }, "config.proxies.type": { "type": "object", "additionalProperties": true }, "config.proxies.address": { "type": "string" }, "config.proxies.username": { "type": "string" }, "config.proxies.password": { "type": "string" }, "config.persistent_metadata.namespace": { "type": "string" }, "config.persistent_metadata.entries.key": { "type": "string" }, "config.persistent_metadata.entries.value": { "type": "object", "additionalProperties": true } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully updating instance configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceUpdateConfigResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:id/config/namespaces/:namespace/entries/:key": { "put": { "summary": "Update instance config entry", "description": "Updates a single configuration entry by namespace and key.\nMore efficient than UpdateInstanceConfig for individual changes.", "operationId": "soulfire_v1_InstanceService_UpdateInstanceConfigEntry_PUT", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "UpdateInstanceConfigEntry", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_CONFIG"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Persists a single instance setting entry." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance to update.", "schema": { "type": "string" } }, { "name": "namespace", "in": "path", "required": true, "description": "The namespace of the setting (e.g., \"bot\", \"account\", plugin ID).", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "The key of the setting within the namespace.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "object", "additionalProperties": true, "description": "The new value for the setting. Supports JSON value types\n(string, number, boolean, null, array, object)." } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully updating a configuration entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceUpdateConfigEntryResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:id/meta": { "patch": { "summary": "Update instance metadata", "description": "Updates instance metadata (friendly name or icon).\nOnly one field can be updated per request.", "operationId": "soulfire_v1_InstanceService_UpdateInstanceMeta_PATCH", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.InstanceService", "x-soulfire-grpc-method": "UpdateInstanceMeta", "x-soulfire-unary-only": true, "tags": ["InstanceService"], "x-soulfire-permissions": ["UPDATE_INSTANCE_META"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Updates the instance's friendly name or icon." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the instance to update.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "friendly_name": { "type": "string", "description": "New human-readable name for the instance." }, "icon": { "type": "string", "description": "New icon identifier for the instance." } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully updating instance metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InstanceUpdateMetaResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/login/email-code": { "post": { "summary": "Verify email code", "description": "Verifies an email verification code to complete authentication.\n\nThe auth_flow_token must match a pending login flow, and the code must match\nthe one that was sent to the user's email. On success, returns a JWT token.\nOn failure, returns a Failure response with INVALID_CODE reason.\n\nAfter successful verification, the auth_flow_token is invalidated and cannot be reused.", "operationId": "soulfire_v1_LoginService_EmailCode_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.LoginService", "x-soulfire-grpc-method": "EmailCode", "x-soulfire-unary-only": true, "tags": ["LoginService"], "x-soulfire-scope": "public.login", "x-soulfire-side-effects": [ "Completes the login flow and may issue an API JWT." ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "auth_flow_token": { "type": "string", "description": "The authentication flow token received from the Login RPC response.\nThis token links the code verification to the original login request.\nMust be a valid UUID string." }, "code": { "type": "string", "description": "The six-digit verification code that was sent to the user's email address.\nMust exactly match the code that was emailed to the user." } }, "required": ["code"] }, "example": { "authFlowToken": "", "code": "" } } } }, "responses": { "200": { "description": "Response message representing the next step in the authentication flow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.NextAuthFlowResponse" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "429": { "description": "Login flow or credential validation was rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/login": { "post": { "summary": "Start login flow", "description": "Initiates a login flow for the specified email address.\n\nIf the email is registered, a six-digit verification code is sent to that address.\nThe response always indicates that an email code step is next, regardless of whether\nthe email exists, to prevent email enumeration attacks.", "operationId": "soulfire_v1_LoginService_Login_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.LoginService", "x-soulfire-grpc-method": "Login", "x-soulfire-unary-only": true, "tags": ["LoginService"], "x-soulfire-scope": "public.login", "x-soulfire-side-effects": [ "Starts an email login flow and may send a verification code." ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "description": "The email address of the user attempting to log in.\nIf a user with this email exists, a six-digit verification code will be sent to this address.\nFor security reasons, the response is the same whether or not the email is registered,\npreventing enumeration attacks." } }, "required": ["email"] }, "example": { "email": "" } } } }, "responses": { "200": { "description": "Response message representing the next step in the authentication flow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.NextAuthFlowResponse" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "429": { "description": "Login flow or credential validation was rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/logs:history": { "post": { "summary": "Get log history", "description": "Retrieves historical log entries from the server's in-memory log buffer.\nThe server maintains a rolling buffer of the last 300 log entries.\nOnly returns non-personal logs that match the specified scope.", "operationId": "soulfire_v1_LogsService_GetPrevious_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.LogsService", "x-soulfire-grpc-method": "GetPrevious", "x-soulfire-unary-only": true, "tags": ["LogsService"], "x-soulfire-scope": "log.scope", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "scope.instance.instance_id": { "type": "string", "description": "The UUID of the instance to filter logs for. Must be a valid UUID string." }, "scope.bot.instance_id": { "type": "string", "description": "The UUID of the instance the bot belongs to. Must be a valid UUID string." }, "scope.bot.bot_id": { "type": "string", "description": "The UUID of the bot account to filter logs for. Must be a valid UUID string." }, "scope.instance_script.instance_id": { "type": "string", "description": "The UUID of the instance the script is running in. Must be a valid UUID string." }, "scope.instance_script.script_id": { "type": "string", "description": "The UUID of the script to filter logs for. Must be a valid UUID string." }, "count": { "type": "integer", "format": "int32", "description": "The maximum number of recent log entries to retrieve.\nMust not exceed 300 (the server's maximum log buffer size).\nReturns the newest entries that match the scope, up to this count." } }, "required": ["count"] }, "example": { "count": 0 } } } }, "responses": { "200": { "description": "Response containing historical log entries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.PreviousLogResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/mc-auth:refresh": { "post": { "summary": "Refresh Minecraft account", "description": "Refreshes the authentication tokens for an existing Minecraft account.\nUsed to renew expired access tokens using stored refresh tokens.\n\nFor Microsoft accounts, this refreshes the Minecraft token, profile,\nand player certificates. For offline accounts, returns the account\nunchanged (offline accounts never expire).", "operationId": "soulfire_v1_MCAuthService_Refresh_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.MCAuthService", "x-soulfire-grpc-method": "Refresh", "x-soulfire-unary-only": true, "tags": ["MCAuthService"], "x-soulfire-permissions": ["AUTHENTICATE_MC_ACCOUNT"], "x-soulfire-scope": "instance", "x-soulfire-side-effects": [ "Refreshes the account's authentication tokens." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance context for the refresh operation.\nMust be a valid UUID string. The instance must exist and the caller\nmust have AUTHENTICATE_MC_ACCOUNT permission for this instance.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "account.type": { "type": "object", "additionalProperties": true, "description": "The authentication type used for this account.\nDetermines which account_data field is populated." }, "account.profile_id": { "type": "string", "description": "The unique profile identifier (UUID) for this account.\nFor online accounts: The official Minecraft profile UUID from Microsoft.\nFor offline accounts: A deterministic UUID derived from the username.\nFormat: Standard UUID string (e.g., \"550e8400-e29b-41d4-a716-446655440000\")." }, "account.last_known_name": { "type": "string", "description": "The last known username/gamertag for this account.\nUpdated during authentication and refresh operations.\nFor Java: The Minecraft username (up to 16 characters).\nFor Bedrock: The Xbox gamertag." }, "account.online_chain_java_data.auth_chain": { "type": "object", "additionalProperties": true, "description": "JSON structure containing the complete authentication chain from minecraftauth library.\nIncludes Microsoft OAuth tokens, Xbox Live tokens, and Minecraft access tokens.\nThis data can be refreshed to obtain new tokens without re-authentication." }, "account.bedrock_data.auth_chain": { "type": "object", "additionalProperties": true, "description": "JSON structure containing the complete Bedrock authentication chain.\nIncludes Xbox Live tokens and Bedrock-specific session data.\nCompatible with the ViaBedrock protocol implementation." }, "account.online_simple_java_data.access_token": { "type": "string", "description": "The raw Minecraft access token (JWT)." }, "account.online_simple_java_data.expire_time_ms": { "type": "integer", "format": "int64", "description": "Token expiry time in milliseconds since epoch." }, "account.config.namespace": { "type": "string" }, "account.config.entries.key": { "type": "string" }, "account.config.entries.value": { "type": "object", "additionalProperties": true }, "account.persistent_metadata.namespace": { "type": "string" }, "account.persistent_metadata.entries.key": { "type": "string" }, "account.persistent_metadata.entries.value": { "type": "object", "additionalProperties": true } }, "required": [] } } } }, "responses": { "200": { "description": "Response message containing the refreshed Minecraft account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.RefreshResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/metrics": { "get": { "summary": "Get instance metrics", "description": "Returns time-series metrics and current distributions for an instance.\nSupports incremental fetching via the \"since\" parameter.", "operationId": "soulfire_v1_MetricsService_GetInstanceMetrics_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.MetricsService", "x-soulfire-grpc-method": "GetInstanceMetrics", "x-soulfire-unary-only": true, "tags": ["MetricsService"], "x-soulfire-permissions": ["READ_BOT_INFO"], "x-soulfire-scope": "instance", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The UUID of the SoulFire instance to get metrics for.", "schema": { "type": "string", "format": "uuid" } }, { "name": "since", "in": "query", "required": false, "description": "If set, only return snapshots taken after this timestamp.\nUsed for incremental fetching to reduce payload size.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response containing time-series metrics and current distributions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GetInstanceMetricsResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/server/metrics": { "get": { "summary": "Get server metrics", "description": "Returns server-level system metrics (CPU, memory, threads, GC, aggregate bots).\nSupports incremental fetching via the \"since\" parameter.", "operationId": "soulfire_v1_MetricsService_GetServerMetrics_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.MetricsService", "x-soulfire-grpc-method": "GetServerMetrics", "x-soulfire-unary-only": true, "tags": ["MetricsService"], "x-soulfire-permissions": ["READ_SERVER_CONFIG"], "x-soulfire-scope": "server", "parameters": [ { "name": "since", "in": "query", "required": false, "description": "If set, only return snapshots taken after this timestamp.\nUsed for incremental fetching to reduce payload size.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response containing server-level system metrics time-series.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GetServerMetricsResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/scripts": { "post": { "summary": "Create script", "description": "Creates a new script in the specified instance.\nThe script can be created with initial nodes and edges, or as a blank script\nto be edited later.", "operationId": "soulfire_v1_ScriptService_CreateScript_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ScriptService", "x-soulfire-grpc-method": "CreateScript", "x-soulfire-unary-only": true, "tags": ["ScriptService"], "x-soulfire-permissions": ["UPDATE_SCRIPT"], "x-soulfire-scope": "instance.script", "x-soulfire-side-effects": ["Creates and stores a new script graph."], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The instance to create the script in.\nFormat: UUID string.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The human-readable name for the script." }, "description": { "type": "string", "description": "Optional description of what the script does." }, "nodes.id": { "type": "string" }, "nodes.type": { "type": "string" }, "nodes.position.x": { "type": "number", "format": "double" }, "nodes.position.y": { "type": "number", "format": "double" }, "nodes.data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "nodes.muted": { "type": "boolean" }, "nodes.collapsed": { "type": "boolean" }, "nodes.width": { "type": "number", "format": "double" }, "nodes.height": { "type": "number", "format": "double" }, "nodes.contained_nodes": { "type": "array", "items": { "type": "string" } }, "nodes.label": { "type": "string" }, "nodes.resolved_type": { "type": "object", "additionalProperties": true }, "nodes.parent_frame_id": { "type": "string" }, "edges.id": { "type": "string" }, "edges.source": { "type": "string" }, "edges.source_handle": { "type": "string" }, "edges.target": { "type": "string" }, "edges.target_handle": { "type": "string" }, "edges.edge_type": { "type": "object", "additionalProperties": true }, "paused": { "type": "boolean", "description": "Whether the script should be created in paused state.\nIf false (default), the script starts running immediately after creation." }, "quotas.max_execution_count": { "type": "integer", "format": "int64", "description": "Maximum number of node executions per trigger invocation." }, "quotas.max_execution_time_ms": { "type": "integer", "format": "int64", "description": "Maximum wall-clock time for a single trigger execution in milliseconds." }, "quotas.max_concurrent_triggers": { "type": "integer", "format": "int32", "description": "Maximum number of concurrent trigger invocations." }, "quotas.max_state_store_entries": { "type": "integer", "format": "int64", "description": "Maximum number of entries in the script's state store." }, "quotas.disable_timeouts": { "type": "boolean", "description": "When true, disables per-node and data edge timeouts entirely." } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully creating a script.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.CreateScriptResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } }, "get": { "summary": "List scripts", "description": "Lists all scripts in the specified instance.\nReturns summary information (ScriptInfo) without full node/edge data\nto reduce response size.", "operationId": "soulfire_v1_ScriptService_ListScripts_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ScriptService", "x-soulfire-grpc-method": "ListScripts", "x-soulfire-unary-only": true, "tags": ["ScriptService"], "x-soulfire-permissions": ["READ_SCRIPT"], "x-soulfire-scope": "instance.script", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The instance to list scripts from.\nFormat: UUID string.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response containing the list of scripts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.ListScriptsResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/scripts/p1:deactivate": { "post": { "summary": "Deactivate script", "description": "Deactivates an active script.\nUnregisters all event listeners and cancels any pending async operations.", "operationId": "soulfire_v1_ScriptService_DeactivateScript_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ScriptService", "x-soulfire-grpc-method": "DeactivateScript", "x-soulfire-unary-only": true, "tags": ["ScriptService"], "x-soulfire-permissions": ["EXECUTE_SCRIPT"], "x-soulfire-scope": "instance.script", "x-soulfire-side-effects": [ "Stops the active script and unregisters listeners." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The instance containing the script.\nFormat: UUID string.", "schema": { "type": "string" } }, { "name": "script_id", "in": "path", "required": true, "description": "The ID of the script to deactivate.\nFormat: UUID string.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response after successfully deactivating a script.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.DeactivateScriptResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/scripts/:script_id": { "delete": { "summary": "Delete script", "description": "Permanently deletes a script.\nIf the script is currently active, it will be deactivated first.\nThis operation cannot be undone.", "operationId": "soulfire_v1_ScriptService_DeleteScript_DELETE", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ScriptService", "x-soulfire-grpc-method": "DeleteScript", "x-soulfire-unary-only": true, "tags": ["ScriptService"], "x-soulfire-permissions": ["UPDATE_SCRIPT"], "x-soulfire-scope": "instance.script", "x-soulfire-side-effects": ["Deletes the target script."], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The instance containing the script.\nFormat: UUID string.", "schema": { "type": "string" } }, { "name": "script_id", "in": "path", "required": true, "description": "The ID of the script to delete.\nFormat: UUID string.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response after successfully deleting a script.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.DeleteScriptResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } }, "get": { "summary": "Get script", "description": "Retrieves a specific script by its ID.\nReturns the complete script data including all nodes and edges.", "operationId": "soulfire_v1_ScriptService_GetScript_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ScriptService", "x-soulfire-grpc-method": "GetScript", "x-soulfire-unary-only": true, "tags": ["ScriptService"], "x-soulfire-permissions": ["READ_SCRIPT"], "x-soulfire-scope": "instance.script", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The instance containing the script.\nFormat: UUID string.", "schema": { "type": "string" } }, { "name": "script_id", "in": "path", "required": true, "description": "The ID of the script to retrieve.\nFormat: UUID string.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response containing the requested script.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GetScriptResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } }, "patch": { "summary": "Update script", "description": "Updates an existing script's metadata and/or node graph.\nOnly specified fields are updated; others remain unchanged.\nUse update_nodes/update_edges flags to explicitly set empty lists.", "operationId": "soulfire_v1_ScriptService_UpdateScript_PATCH", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ScriptService", "x-soulfire-grpc-method": "UpdateScript", "x-soulfire-unary-only": true, "tags": ["ScriptService"], "x-soulfire-permissions": ["UPDATE_SCRIPT"], "x-soulfire-scope": "instance.script", "x-soulfire-side-effects": [ "Persists script metadata and graph updates." ], "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The instance containing the script.\nFormat: UUID string.", "schema": { "type": "string" } }, { "name": "script_id", "in": "path", "required": true, "description": "The ID of the script to update.\nFormat: UUID string.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Updated name for the script.\nIf not set, the name remains unchanged." }, "description": { "type": "string", "description": "Updated description for the script.\nIf not set, the description remains unchanged." }, "nodes.id": { "type": "string" }, "nodes.type": { "type": "string" }, "nodes.position.x": { "type": "number", "format": "double" }, "nodes.position.y": { "type": "number", "format": "double" }, "nodes.data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "nodes.muted": { "type": "boolean" }, "nodes.collapsed": { "type": "boolean" }, "nodes.width": { "type": "number", "format": "double" }, "nodes.height": { "type": "number", "format": "double" }, "nodes.contained_nodes": { "type": "array", "items": { "type": "string" } }, "nodes.label": { "type": "string" }, "nodes.resolved_type": { "type": "object", "additionalProperties": true }, "nodes.parent_frame_id": { "type": "string" }, "edges.id": { "type": "string" }, "edges.source": { "type": "string" }, "edges.source_handle": { "type": "string" }, "edges.target": { "type": "string" }, "edges.target_handle": { "type": "string" }, "edges.edge_type": { "type": "object", "additionalProperties": true }, "update_nodes": { "type": "boolean", "description": "Whether the nodes field should be updated (allows setting to empty list)." }, "update_edges": { "type": "boolean", "description": "Whether the edges field should be updated (allows setting to empty list)." }, "paused": { "type": "boolean", "description": "Updated paused setting.\nIf not set, the paused setting remains unchanged.\nIf set to false and script was paused, the script will be restarted." }, "quotas.max_execution_count": { "type": "integer", "format": "int64", "description": "Maximum number of node executions per trigger invocation." }, "quotas.max_execution_time_ms": { "type": "integer", "format": "int64", "description": "Maximum wall-clock time for a single trigger execution in milliseconds." }, "quotas.max_concurrent_triggers": { "type": "integer", "format": "int32", "description": "Maximum number of concurrent trigger invocations." }, "quotas.max_state_store_entries": { "type": "integer", "format": "int64", "description": "Maximum number of entries in the script's state store." }, "quotas.disable_timeouts": { "type": "boolean", "description": "When true, disables per-node and data edge timeouts entirely." }, "update_quotas": { "type": "boolean", "description": "Whether the quotas field should be updated (allows clearing quotas)." } }, "required": [] } } } }, "responses": { "200": { "description": "Response after successfully updating a script.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.UpdateScriptResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/scripts/node-types": { "get": { "summary": "Get node types", "description": "Gets all available node types with their metadata.\nThis enables clients to render the node editor without hardcoded knowledge\nof specific node types. The response includes port definitions, categories,\ndisplay names, and all other information needed to render and validate nodes.\nThis endpoint is cacheable - node types only change between server versions.", "operationId": "soulfire_v1_ScriptService_GetNodeTypes_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ScriptService", "x-soulfire-grpc-method": "GetNodeTypes", "x-soulfire-unary-only": true, "tags": ["ScriptService"], "x-soulfire-permissions": ["READ_SCRIPT"], "x-soulfire-scope": "script.catalog", "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Optional filter by category ID (references CategoryDefinition.id).\nExamples: \"triggers\", \"actions\", \"math\".\nIf empty, returns all node types.", "schema": { "type": "string" } }, { "name": "include_deprecated", "in": "query", "required": false, "description": "Whether to include deprecated node types.\nDefault is false.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Response containing all available node types.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GetNodeTypesResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/scripts/registry": { "get": { "summary": "Get script registry data", "description": "Gets Minecraft registry data for autocomplete and validation.\nReturns blocks, entities, items, and biomes that can be used in scripts.\nThis endpoint is cacheable - registry data only changes between server versions.", "operationId": "soulfire_v1_ScriptService_GetRegistryData_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ScriptService", "x-soulfire-grpc-method": "GetRegistryData", "x-soulfire-unary-only": true, "tags": ["ScriptService"], "x-soulfire-permissions": ["READ_SCRIPT"], "x-soulfire-scope": "script.catalog", "parameters": [ { "name": "registry", "in": "query", "required": false, "description": "Optional: specific registry to fetch. If empty, returns all registries.\nValid values: \"blocks\", \"entities\", \"items\", \"biomes\"", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response containing Minecraft registry data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GetRegistryDataResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/:instance_id/scripts/:script_id/status": { "get": { "summary": "Get script status", "description": "Gets the current status of a script.\nReturns whether the script is active, which node is executing, and activation count.", "operationId": "soulfire_v1_ScriptService_GetScriptStatus_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ScriptService", "x-soulfire-grpc-method": "GetScriptStatus", "x-soulfire-unary-only": true, "tags": ["ScriptService"], "x-soulfire-permissions": ["READ_SCRIPT"], "x-soulfire-scope": "instance.script", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The instance containing the script.\nFormat: UUID string.", "schema": { "type": "string" } }, { "name": "script_id", "in": "path", "required": true, "description": "The ID of the script to check.\nFormat: UUID string.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response containing the script's execution status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GetScriptStatusResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/instances/p0/scripts:validate": { "post": { "summary": "Validate script", "description": "Validates a script graph without saving it.\nReturns all diagnostics (errors and warnings) for the given nodes and edges.\nUseful for live validation in the editor without requiring a save.", "operationId": "soulfire_v1_ScriptService_ValidateScript_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ScriptService", "x-soulfire-grpc-method": "ValidateScript", "x-soulfire-unary-only": true, "tags": ["ScriptService"], "x-soulfire-permissions": ["UPDATE_SCRIPT"], "x-soulfire-scope": "instance.script", "parameters": [ { "name": "instance_id", "in": "path", "required": true, "description": "The instance context for validation.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "nodes.id": { "type": "string" }, "nodes.type": { "type": "string" }, "nodes.position.x": { "type": "number", "format": "double" }, "nodes.position.y": { "type": "number", "format": "double" }, "nodes.data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "nodes.muted": { "type": "boolean" }, "nodes.collapsed": { "type": "boolean" }, "nodes.width": { "type": "number", "format": "double" }, "nodes.height": { "type": "number", "format": "double" }, "nodes.contained_nodes": { "type": "array", "items": { "type": "string" } }, "nodes.label": { "type": "string" }, "nodes.resolved_type": { "type": "object", "additionalProperties": true }, "nodes.parent_frame_id": { "type": "string" }, "edges.id": { "type": "string" }, "edges.source": { "type": "string" }, "edges.source_handle": { "type": "string" }, "edges.target": { "type": "string" }, "edges.target_handle": { "type": "string" }, "edges.edge_type": { "type": "object", "additionalProperties": true } }, "required": [] } } } }, "responses": { "200": { "description": "Response containing validation diagnostics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.ValidateScriptResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/server": { "get": { "summary": "Get server info", "description": "Retrieves comprehensive server information including current configuration,\nall available settings definitions, settings page layouts, and registered plugins.\n\nThis method is typically called when initializing a settings UI to obtain:\n1. Current configuration values to populate form fields\n2. Settings definitions describing each setting's type, constraints, and metadata\n3. Page definitions for organizing settings into logical groups\n4. Plugin information for displaying registered plugins", "operationId": "soulfire_v1_ServerService_GetServerInfo_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ServerService", "x-soulfire-grpc-method": "GetServerInfo", "x-soulfire-unary-only": true, "tags": ["ServerService"], "x-soulfire-permissions": ["READ_SERVER_CONFIG"], "x-soulfire-scope": "server", "responses": { "200": { "description": "Response message for GetServerInfo RPC containing comprehensive server information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.ServerInfoResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/server/config": { "patch": { "summary": "Update server config", "description": "Replaces the entire server configuration with the provided values.\nThis is a bulk update operation primarily used for profile import functionality.\n\nUse this method when you need to apply a complete configuration snapshot,\nsuch as when importing settings from a saved profile or restoring a backup.\nFor individual setting changes during normal operation, prefer UpdateServerConfigEntry.\n\nThe new configuration is persisted to the database, and runtime hooks are\ntriggered to apply changes immediately (e.g., log level adjustments).", "operationId": "soulfire_v1_ServerService_UpdateServerConfig_PATCH", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ServerService", "x-soulfire-grpc-method": "UpdateServerConfig", "x-soulfire-unary-only": true, "tags": ["ServerService"], "x-soulfire-permissions": ["UPDATE_SERVER_CONFIG"], "x-soulfire-scope": "server", "x-soulfire-side-effects": [ "Replaces the persisted server configuration." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "config.settings.namespace": { "type": "string" }, "config.settings.entries.key": { "type": "string" }, "config.settings.entries.value": { "type": "object", "additionalProperties": true } }, "required": [] } } } }, "responses": { "200": { "description": "Response message for UpdateServerConfig RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.ServerUpdateConfigResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/server/config/namespaces/:namespace/entries/:key": { "put": { "summary": "Update server config entry", "description": "Updates a single configuration entry identified by namespace and key.\nThis is a granular update operation for modifying individual settings.\n\nThis is the preferred method for real-time UI interactions where users\nmodify settings one at a time. It avoids overwriting unrelated settings\nand is more efficient than replacing the entire configuration.\n\nIf the namespace doesn't exist, it will be created. If the key doesn't\nexist within the namespace, it will be added. Existing values are overwritten.\n\nThe change is persisted to the database, and runtime hooks are triggered\nto apply the new value immediately where applicable.", "operationId": "soulfire_v1_ServerService_UpdateServerConfigEntry_PUT", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.ServerService", "x-soulfire-grpc-method": "UpdateServerConfigEntry", "x-soulfire-unary-only": true, "tags": ["ServerService"], "x-soulfire-permissions": ["UPDATE_SERVER_CONFIG"], "x-soulfire-scope": "server", "x-soulfire-side-effects": ["Persists a single server setting entry."], "parameters": [ { "name": "namespace", "in": "path", "required": true, "description": "The namespace of the setting to update.\nNamespaces group related settings together (e.g., \"dev\" for developer settings).\nMust match an existing namespace or a new namespace will be created.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "The key identifying the specific setting within the namespace.\nCombined with namespace, this uniquely identifies the setting.\nExample: namespace=\"dev\", key=\"soulfire-debug\" for the SoulFire debug setting.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "object", "additionalProperties": true, "description": "The new value for the setting.\nUses google.protobuf.Value to support various JSON types:\n- string_value for text settings\n- number_value for int/double settings\n- bool_value for boolean settings\n- list_value for string list settings\n- struct_value for complex settings like min/max ranges" } }, "required": ["value"] } } } }, "responses": { "200": { "description": "Response message for UpdateServerConfigEntry RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.ServerUpdateConfigEntryResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/users": { "post": { "summary": "Create user", "description": "Creates a new user account in the system.", "operationId": "soulfire_v1_UserService_CreateUser_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.UserService", "x-soulfire-grpc-method": "CreateUser", "x-soulfire-unary-only": true, "tags": ["UserService"], "x-soulfire-permissions": ["CREATE_USER"], "x-soulfire-scope": "server.user", "x-soulfire-side-effects": ["Creates a new user account."], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "username": { "type": "string", "description": "The username for the new user.\nMust be lowercase, between 3 and 32 characters.\nMust begin with an alphanumeric character, followed by alphanumeric characters or dashes,\nand end with an alphanumeric character.\nMust be unique across all users." }, "role": { "type": "object", "additionalProperties": true, "description": "The role to assign to the user. Determines what permissions the user has.\nADMIN users have all permissions, while USER role has limited permissions\ncontrolled by server settings." }, "email": { "type": "string", "format": "email", "description": "The email address for the user.\nMust be a valid email format and unique across all users.\nMaximum length is 255 characters." } }, "required": ["username", "role", "email"] }, "example": { "username": "", "role": "ADMIN", "email": "" } } } }, "responses": { "200": { "description": "Response message returned after successfully creating a new user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.UserCreateResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } }, "get": { "summary": "List users", "description": "Lists all users in the system.", "operationId": "soulfire_v1_UserService_ListUsers_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.UserService", "x-soulfire-grpc-method": "ListUsers", "x-soulfire-unary-only": true, "tags": ["UserService"], "x-soulfire-permissions": ["READ_USER"], "x-soulfire-scope": "server.user", "responses": { "200": { "description": "Response message containing a list of all users in the system.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.UserListResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/users/:id": { "delete": { "summary": "Delete user", "description": "Deletes an existing user from the system.", "operationId": "soulfire_v1_UserService_DeleteUser_DELETE", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.UserService", "x-soulfire-grpc-method": "DeleteUser", "x-soulfire-unary-only": true, "tags": ["UserService"], "x-soulfire-permissions": ["DELETE_USER"], "x-soulfire-scope": "server.user", "x-soulfire-side-effects": ["Deletes the user and related owned data."], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the user to delete.\nCannot be the ID of the requesting user (cannot delete self).\nCannot be the root user ID (00000000-0000-0000-0000-000000000000).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response message returned after successfully deleting a user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.UserDeleteResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } }, "get": { "summary": "Get user", "description": "Retrieves detailed information about a specific user.", "operationId": "soulfire_v1_UserService_GetUserInfo_GET", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.UserService", "x-soulfire-grpc-method": "GetUserInfo", "x-soulfire-unary-only": true, "tags": ["UserService"], "x-soulfire-permissions": ["READ_USER"], "x-soulfire-scope": "server.user", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the user to retrieve information for.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response message containing detailed information about a specific user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.UserInfoResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } }, "patch": { "summary": "Update user", "description": "Updates an existing user's profile information.", "operationId": "soulfire_v1_UserService_UpdateUser_PATCH", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.UserService", "x-soulfire-grpc-method": "UpdateUser", "x-soulfire-unary-only": true, "tags": ["UserService"], "x-soulfire-permissions": ["UPDATE_USER"], "x-soulfire-scope": "server.user", "x-soulfire-side-effects": [ "Persists the updated username, role, and email." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the user to update.\nCannot be the ID of the requesting user (cannot update self via this method).\nCannot be the root user ID (00000000-0000-0000-0000-000000000000).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "username": { "type": "string", "description": "The new username for the user.\nMust be lowercase, between 3 and 32 characters.\nMust begin with an alphanumeric character, followed by alphanumeric characters or dashes,\nand end with an alphanumeric character.\nMust be unique across all users." }, "role": { "type": "object", "additionalProperties": true, "description": "The new role to assign to the user.\nADMIN users have all permissions, while USER role has limited permissions." }, "email": { "type": "string", "format": "email", "description": "The new email address for the user.\nMust be a valid email format and unique across all users.\nMaximum length is 255 characters." } }, "required": ["username", "role", "email"] } } } }, "responses": { "200": { "description": "Response message returned after successfully updating a user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.UpdateUserResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/users/p0/tokens/api:generate": { "post": { "summary": "Generate user API token", "description": "Generates a new API token (JWT) for a specific user.", "operationId": "soulfire_v1_UserService_GenerateUserAPIToken_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.UserService", "x-soulfire-grpc-method": "GenerateUserAPIToken", "x-soulfire-unary-only": true, "tags": ["UserService"], "x-soulfire-permissions": ["GENERATE_API_TOKEN"], "x-soulfire-scope": "server.user", "x-soulfire-side-effects": [ "Issues a new API JWT for the target user." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the user to generate a token for.\nCannot be the ID of the requesting user (cannot generate token for self via this method).\nCannot be the root user ID (00000000-0000-0000-0000-000000000000).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response message containing the newly generated API token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.GenerateUserAPITokenResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } }, "/v1/users/p0/sessions:invalidate": { "post": { "summary": "Invalidate user sessions", "description": "Invalidates all active sessions for a user by updating their min_issued_at timestamp.", "operationId": "soulfire_v1_UserService_InvalidateSessions_POST", "x-soulfire-transport": "http-json-transcoding", "x-soulfire-grpc-service": "soulfire.v1.UserService", "x-soulfire-grpc-method": "InvalidateSessions", "x-soulfire-unary-only": true, "tags": ["UserService"], "x-soulfire-permissions": ["INVALIDATE_SESSIONS"], "x-soulfire-scope": "server.user", "x-soulfire-side-effects": [ "Revokes previously issued tokens for the target user." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier (UUID) of the user whose sessions should be invalidated.\nCannot be the ID of the requesting user (cannot invalidate own sessions via this method).\nCannot be the root user ID (00000000-0000-0000-0000-000000000000).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response message returned after successfully invalidating all sessions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/soulfire.v1.InvalidateSessionsResponse" } } } }, "401": { "description": "Missing or invalid API authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "403": { "description": "The authenticated user does not have the required permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } }, "500": { "description": "Unexpected server-side failure while handling the RPC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoulFireGrpcError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Preferred API authentication. Use a JWT with the `api` audience." }, "basicTokenAuth": { "type": "http", "scheme": "basic", "description": "Compatibility authentication. Encode `username:api-jwt` as the HTTP Basic credentials. SoulFire ignores the username and validates the token in the password slot." } }, "schemas": { "SoulFireGrpcError": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "integer", "format": "int32", "description": "Numeric gRPC status code." }, "grpc-code": { "type": "string", "description": "Named gRPC status code." }, "message": { "type": "string", "description": "Human-readable error message." }, "stack-trace": { "type": "string", "description": "Stack trace included only when verbose responses are enabled." }, "details": { "type": "array", "description": "Optional Google RPC error detail payloads.", "items": { "type": "object", "additionalProperties": true } } }, "required": ["code", "grpc-code"] }, "soulfire.v1.ApplyAutomationPresetResponse": { "type": "object", "additionalProperties": false, "properties": { "settings": { "$ref": "#/components/schemas/soulfire.v1.AutomationInstanceSettings" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationBotActionResult" } } }, "required": [] }, "soulfire.v1.AutomationActionResponse": { "type": "object", "additionalProperties": false, "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationBotActionResult" } } }, "required": [] }, "soulfire.v1.BotClickDialogButtonResponse": { "type": "object", "additionalProperties": false, "description": "Response for dialog button click.", "properties": { "success": { "type": "boolean", "description": "Whether the button click was processed successfully." }, "error": { "type": "string", "description": "Error message if success is false.\nPossible errors: \"No dialog is currently displayed\"" } }, "required": [] }, "soulfire.v1.BotCloseContainerResponse": { "type": "object", "additionalProperties": false, "description": "Response for container close action.", "properties": { "success": { "type": "boolean", "description": "Whether the close action was successful." } }, "required": [] }, "soulfire.v1.BotCloseDialogResponse": { "type": "object", "additionalProperties": false, "description": "Response for dialog close.", "properties": { "success": { "type": "boolean", "description": "Whether the dialog was successfully closed." }, "error": { "type": "string", "description": "Error message if success is false." } }, "required": [] }, "soulfire.v1.BotContainerButtonClickResponse": { "type": "object", "additionalProperties": false, "description": "Response for container button click action.", "properties": { "success": { "type": "boolean", "description": "Whether the button click was successfully queued." }, "error": { "type": "string", "description": "Error message if success is false.\nPossible errors: \"Invalid button ID for this container type\"" } }, "required": [] }, "soulfire.v1.BotGetDialogResponse": { "type": "object", "additionalProperties": false, "description": "Response containing the current dialog state.", "properties": { "dialog": { "description": "The currently displayed dialog.\nAbsent if no dialog is being shown.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.ServerDialog" } ] } }, "required": [] }, "soulfire.v1.BotInfoResponse": { "type": "object", "additionalProperties": false, "description": "Response containing detailed information about a specific bot.", "properties": { "live_state": { "description": "Live state of the bot including full inventory data.\nWill be absent if the bot is offline or player data is not available.\nWhen present, includes complete inventory slot information.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.BotLiveState" } ] } }, "required": [] }, "soulfire.v1.BotInventoryClickResponse": { "type": "object", "additionalProperties": false, "description": "Response for inventory click action.", "properties": { "success": { "type": "boolean", "description": "Whether the click action was successfully sent to the server.\nNote: This indicates the action was sent, not that the server accepted it." }, "error": { "type": "string", "description": "Error message if success is false.\nPossible errors: \"Invalid click type\"" } }, "required": [] }, "soulfire.v1.BotInventoryStateResponse": { "type": "object", "additionalProperties": false, "description": "Response containing the current inventory/container state.", "properties": { "layout": { "description": "Layout information describing the container structure.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.ContainerLayout" } ] }, "slots": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.InventorySlot" }, "description": "All slots containing items (empty slots are omitted)." }, "carried_item": { "description": "Item currently held on the cursor (being moved).\nAbsent if cursor is empty.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.InventorySlot" } ] }, "selected_hotbar_slot": { "type": "integer", "format": "int32", "description": "Currently selected hotbar slot index (0-8)." } }, "required": [] }, "soulfire.v1.BotListResponse": { "type": "object", "additionalProperties": false, "description": "Response containing the list of all bots in an instance.", "properties": { "bots": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.BotListEntry" }, "description": "All bots configured in the instance, both online and offline.\nThe order is determined by the account configuration order." } }, "required": [] }, "soulfire.v1.BotMouseClickResponse": { "type": "object", "additionalProperties": false, "description": "Response for mouse click action.", "properties": { "success": { "type": "boolean", "description": "Whether the click action was successfully performed." }, "error": { "type": "string", "description": "Error message if success is false.\nPossible errors: \"Invalid mouse button\"" } }, "required": [] }, "soulfire.v1.BotOpenInventoryResponse": { "type": "object", "additionalProperties": false, "description": "Response for inventory open action.", "properties": { "success": { "type": "boolean", "description": "Whether the open inventory action was successful." } }, "required": [] }, "soulfire.v1.BotRenderPovResponse": { "type": "object", "additionalProperties": false, "description": "Response containing the rendered POV image.", "properties": { "image_base64": { "type": "string", "description": "Base64-encoded PNG image data.\nDecode with standard Base64 decoder to get raw PNG bytes.\nThe image uses the bot's current render distance setting." } }, "required": [] }, "soulfire.v1.BotResetMovementResponse": { "type": "object", "additionalProperties": false, "description": "Response for movement reset.", "properties": { "success": { "type": "boolean", "description": "Whether the movement was successfully reset." }, "error": { "type": "string", "description": "Error message if success is false." } }, "required": [] }, "soulfire.v1.BotSetContainerTextResponse": { "type": "object", "additionalProperties": false, "description": "Response for container text input action.", "properties": { "success": { "type": "boolean", "description": "Whether the text was successfully set." }, "error": { "type": "string", "description": "Error message if success is false.\nPossible errors: \"Unsupported container or field ID: /\"" } }, "required": [] }, "soulfire.v1.BotSetHotbarSlotResponse": { "type": "object", "additionalProperties": false, "description": "Response for hotbar slot selection.", "properties": { "success": { "type": "boolean", "description": "Whether the hotbar slot was successfully changed." }, "error": { "type": "string", "description": "Error message if success is false.\nPossible errors: \"Hotbar slot must be between 0 and 8, got: \",\n\"Player is not available\"" } }, "required": [] }, "soulfire.v1.BotSetMovementStateResponse": { "type": "object", "additionalProperties": false, "description": "Response for movement state update.", "properties": { "success": { "type": "boolean", "description": "Whether the movement state was successfully updated." }, "error": { "type": "string", "description": "Error message if success is false." } }, "required": [] }, "soulfire.v1.BotSetRotationResponse": { "type": "object", "additionalProperties": false, "description": "Response for rotation update.", "properties": { "success": { "type": "boolean", "description": "Whether the rotation was successfully set." }, "error": { "type": "string", "description": "Error message if success is false.\nPossible errors: \"Player is not available\"" } }, "required": [] }, "soulfire.v1.BotSubmitDialogResponse": { "type": "object", "additionalProperties": false, "description": "Response for dialog submission.", "properties": { "success": { "type": "boolean", "description": "Whether the submission was processed successfully." }, "error": { "type": "string", "description": "Error message if success is false.\nPossible errors: \"No dialog is currently displayed\"" } }, "required": [] }, "soulfire.v1.BotUpdateConfigEntryResponse": { "type": "object", "additionalProperties": false, "description": "Response for bot configuration entry update.\nEmpty on success; errors are returned via gRPC status.", "properties": {}, "required": [] }, "soulfire.v1.ClientDataResponse": { "type": "object", "additionalProperties": false, "description": "Response containing comprehensive information about the authenticated client and server.\nThis is typically called after authentication to populate the client UI with user details.", "properties": { "id": { "type": "string", "description": "The unique identifier (UUID) of the authenticated user." }, "username": { "type": "string", "description": "The display username of the authenticated user." }, "role": { "description": "The role assigned to the user (ADMIN or USER), which determines base permission levels.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.UserRole" } ] }, "email": { "type": "string", "description": "The email address associated with the user account." }, "server_permissions": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.GlobalPermissionState" }, "description": "A complete list of all global permissions and whether they are granted to this user.\nThis allows the client to determine which features/actions are available." }, "server_info": { "description": "Metadata about the server instance the client is connected to.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.ServerInfo" } ] } }, "required": [] }, "soulfire.v1.CommandCompletionResponse": { "type": "object", "additionalProperties": false, "description": "Response message containing tab-completion suggestions.", "properties": { "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.CommandCompletion" }, "description": "List of completion suggestions for the partial command.\nMay be empty if no completions are available.\nSuggestions are generated based on the command's Brigadier definition\nand the current execution scope's visibility." } }, "required": [] }, "soulfire.v1.CommandResponse": { "type": "object", "additionalProperties": false, "description": "Response message containing the result of command execution.", "properties": { "code": { "type": "integer", "format": "int32", "description": "The exit code returned by the command.\n- 0: Command failed or had no effect (e.g., syntax error, no targets found)\n- 1 (Command.SINGLE_SUCCESS): Command executed successfully\n- >1: Command succeeded and affected multiple targets (count of affected items)\nNote: Syntax errors return 0 and error details are sent via the logging system." } }, "required": [] }, "soulfire.v1.CreateScriptResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully creating a script.", "properties": { "script": { "description": "The complete script data including the generated ID.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.ScriptData" } ] }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.ValidationDiagnostic" }, "description": "Validation diagnostics (warnings) from building the script graph." } }, "required": [] }, "soulfire.v1.DeactivateScriptResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully deactivating a script.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.DeleteAccountMetadataEntryResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully deleting a metadata entry.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.DeleteInstanceMetadataEntryResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully deleting an instance metadata entry.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.DeleteScriptResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully deleting a script.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.DownloadResponse": { "type": "object", "additionalProperties": false, "description": "Response message containing the downloaded content and metadata.\nReturned after successfully fetching content from the requested URI.", "properties": { "data": { "type": "string", "format": "byte", "description": "The raw bytes of the downloaded content.\nThis contains the complete response body from the target server.\nMay be empty if the server returned no content (e.g., 204 No Content)." }, "headers": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.HeaderPair" }, "description": "All HTTP headers returned by the target server in its response.\nIncludes standard headers like Content-Type, Content-Length, Cache-Control,\nas well as any custom headers set by the server." }, "status_code": { "type": "integer", "format": "int32", "description": "The HTTP status code returned by the target server (e.g., 200, 404, 500).\nCommon values:\n- 200: OK - Request succeeded\n- 301/302: Redirect (note: redirects may be followed automatically)\n- 400: Bad Request\n- 401: Unauthorized\n- 403: Forbidden\n- 404: Not Found\n- 500: Internal Server Error" } }, "required": [] }, "soulfire.v1.GenerateAPITokenResponse": { "type": "object", "additionalProperties": false, "description": "Response containing a newly generated API authentication token.", "properties": { "token": { "type": "string", "description": "A JWT token with \"api\" audience that can be used to authenticate gRPC/HTTP API requests.\nThis token should be included in the Authorization header for subsequent API calls." } }, "required": [] }, "soulfire.v1.GenerateUserAPITokenResponse": { "type": "object", "additionalProperties": false, "description": "Response message containing the newly generated API token.", "properties": { "token": { "type": "string", "description": "The generated JWT token for API authentication.\nThis token is signed with the server's secret key and has the \"api\" audience.\nThe token does not expire but can be invalidated by updating the user's min_issued_at.\nShould be stored securely as it grants full access as the specified user." } }, "required": [] }, "soulfire.v1.GenerateWebDAVTokenResponse": { "type": "object", "additionalProperties": false, "description": "Response containing a newly generated WebDAV authentication token.", "properties": { "token": { "type": "string", "description": "A JWT token with \"webdav\" audience that can be used to authenticate WebDAV requests.\nThis token should be included in the Authorization header when accessing the WebDAV endpoint." } }, "required": [] }, "soulfire.v1.GetAccountMetadataResponse": { "type": "object", "additionalProperties": false, "description": "Response containing the persistent metadata for an account.", "properties": { "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.SettingsNamespace" }, "description": "Metadata organized by namespace. Each namespace contains\nkey-value pairs of metadata." } }, "required": [] }, "soulfire.v1.GetAutomationBotStateResponse": { "type": "object", "additionalProperties": false, "properties": { "state": { "$ref": "#/components/schemas/soulfire.v1.AutomationBotState" } }, "required": [] }, "soulfire.v1.GetAutomationCoordinationStateResponse": { "type": "object", "additionalProperties": false, "properties": { "state": { "$ref": "#/components/schemas/soulfire.v1.AutomationCoordinationState" } }, "required": [] }, "soulfire.v1.GetAutomationMemoryStateResponse": { "type": "object", "additionalProperties": false, "properties": { "state": { "$ref": "#/components/schemas/soulfire.v1.AutomationMemoryState" } }, "required": [] }, "soulfire.v1.GetAutomationTeamStateResponse": { "type": "object", "additionalProperties": false, "properties": { "state": { "$ref": "#/components/schemas/soulfire.v1.AutomationTeamState" } }, "required": [] }, "soulfire.v1.GetInstanceMetadataResponse": { "type": "object", "additionalProperties": false, "description": "Response containing the persistent metadata for an instance.", "properties": { "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.SettingsNamespace" }, "description": "Metadata organized by namespace. Each namespace contains\nkey-value pairs of metadata." } }, "required": [] }, "soulfire.v1.GetInstanceMetricsResponse": { "type": "object", "additionalProperties": false, "description": "Response containing time-series metrics and current distributions.", "properties": { "snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.MetricsSnapshot" }, "description": "Time-series snapshots ordered oldest to newest.\nContains up to 600 snapshots (30 minutes at 3-second intervals).\nIf the request included a \"since\" timestamp, only newer snapshots are returned." }, "distributions": { "description": "Current-state distributions computed from the latest bot data.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.MetricsDistributions" } ] } }, "required": [] }, "soulfire.v1.GetNodeTypesResponse": { "type": "object", "additionalProperties": false, "description": "Response containing all available node types.", "properties": { "node_types": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.NodeTypeDefinition" }, "description": "List of all node type definitions.\nClients can use this to render any node and validate connections." }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.CategoryDefinition" }, "description": "List of all categories with their metadata.\nUseful for building category filters and palette sections in the UI." }, "port_type_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.PortTypeMetadata" }, "description": "Metadata for each port type including colors and compatibility.\nClients should use this instead of hardcoded port type info." } }, "required": [] }, "soulfire.v1.GetRegistryDataResponse": { "type": "object", "additionalProperties": false, "description": "Response containing Minecraft registry data.", "properties": { "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.RegistryEntry" }, "description": "Block types (e.g., \"minecraft:stone\", \"minecraft:diamond_ore\")." }, "entities": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.RegistryEntry" }, "description": "Entity types (e.g., \"minecraft:zombie\", \"minecraft:player\")." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.RegistryEntry" }, "description": "Item types (e.g., \"minecraft:diamond\", \"minecraft:stick\")." }, "biomes": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.RegistryEntry" }, "description": "Biome types (e.g., \"minecraft:plains\", \"minecraft:forest\")." } }, "required": [] }, "soulfire.v1.GetScriptResponse": { "type": "object", "additionalProperties": false, "description": "Response containing the requested script.", "properties": { "script": { "description": "The complete script data including all nodes and edges.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.ScriptData" } ] } }, "required": [] }, "soulfire.v1.GetScriptStatusResponse": { "type": "object", "additionalProperties": false, "description": "Response containing the script's execution status.", "properties": { "status": { "description": "The current status of the script.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.ScriptStatus" } ] } }, "required": [] }, "soulfire.v1.GetServerMetricsResponse": { "type": "object", "additionalProperties": false, "description": "Response containing server-level system metrics time-series.", "properties": { "snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.ServerMetricsSnapshot" }, "description": "Time-series snapshots ordered oldest to newest.\nContains up to 600 snapshots (30 minutes at 3-second intervals)." } }, "required": [] }, "soulfire.v1.InstanceAddAccountResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully adding an account.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.InstanceAddAccountsBatchResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully adding accounts in batch.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.InstanceAddProxiesBatchResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully adding proxies in batch.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.InstanceAddProxyResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully adding a proxy.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.InstanceAuditLogResponse": { "type": "object", "additionalProperties": false, "description": "Response containing the audit log entries for an instance.", "properties": { "entry": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.InstanceAuditLogResponse.AuditLogEntry" }, "description": "List of audit log entries, ordered by timestamp descending (newest first)." } }, "required": [] }, "soulfire.v1.InstanceCreateResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully creating an instance.", "properties": { "id": { "type": "string", "description": "The unique identifier (UUID) of the newly created instance.\nUse this ID for all subsequent operations on the instance." } }, "required": [] }, "soulfire.v1.InstanceDeleteResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully deleting an instance.\nEmpty response indicates successful deletion.", "properties": {}, "required": [] }, "soulfire.v1.InstanceInfoResponse": { "type": "object", "additionalProperties": false, "description": "Response for GetInstanceInfo containing either full info or a not-modified status.", "properties": { "info": { "description": "Full instance information when the config has been modified\nor no if_modified_since was provided.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.InstanceInfo" } ] }, "not_modified": { "description": "Returned when the config has not changed since if_modified_since.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.InstanceNotModified" } ] } }, "required": [] }, "soulfire.v1.InstanceListResponse": { "type": "object", "additionalProperties": false, "description": "Response containing a list of instances the current user has permission to view.", "properties": { "instances": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.InstanceListResponse.Instance" }, "description": "List of instances the user has READ_INSTANCE permission for." } }, "required": [] }, "soulfire.v1.InstanceRemoveAccountResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully removing an account.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.InstanceRemoveAccountsBatchResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully removing accounts in batch.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.InstanceRemoveProxiesBatchResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully removing proxies in batch.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.InstanceRemoveProxyResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully removing a proxy.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.InstanceStateChangeResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully changing instance state.\nThe operation completes when the state transition is finished.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.InstanceUpdateAccountResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully updating an account.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.InstanceUpdateConfigEntryResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully updating a configuration entry.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.InstanceUpdateConfigResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully updating instance configuration.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.InstanceUpdateMetaResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully updating instance metadata.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.InstanceUpdateProxyResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully updating a proxy.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.InvalidateSelfSessionsResponse": { "type": "object", "additionalProperties": false, "description": "Response message for session invalidation operation.\nAn empty response indicates the operation completed successfully.", "properties": {}, "required": [] }, "soulfire.v1.InvalidateSessionsResponse": { "type": "object", "additionalProperties": false, "description": "Response message returned after successfully invalidating all sessions.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.ListScriptsResponse": { "type": "object", "additionalProperties": false, "description": "Response containing the list of scripts.", "properties": { "scripts": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.ScriptInfo" }, "description": "Summary information for each script in the instance.\nDoes not include full node/edge data to reduce payload size." } }, "required": [] }, "soulfire.v1.NextAuthFlowResponse": { "type": "object", "additionalProperties": false, "description": "Response message representing the next step in the authentication flow.\nThis is a polymorphic response that indicates what action should be taken next.", "properties": { "auth_flow_token": { "type": "string", "format": "uuid", "description": "A unique token identifying this authentication flow session.\nThis token must be included in subsequent requests (e.g., EmailCodeRequest) to continue the flow.\nThe token is a UUID string and expires after 15 minutes of inactivity." }, "email_code": { "description": "Set when the client should prompt the user to enter the email verification code.\nThis is the response after a successful Login RPC call.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.NextAuthFlowResponse.EmailCode" } ] }, "success": { "description": "Set when authentication is complete and successful.\nContains the JWT token for authenticated API access.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.NextAuthFlowResponse.Success" } ] }, "failure": { "description": "Set when authentication has failed.\nContains the reason for the failure.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.NextAuthFlowResponse.Failure" } ] } }, "required": ["auth_flow_token"] }, "soulfire.v1.PreviousLogResponse": { "type": "object", "additionalProperties": false, "description": "Response containing historical log entries.", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.LogString" }, "description": "The list of log entries matching the requested scope, ordered from oldest to newest.\nMay contain fewer entries than requested if not enough matching logs exist in the buffer." } }, "required": [] }, "soulfire.v1.RefreshResponse": { "type": "object", "additionalProperties": false, "description": "Response message containing the refreshed Minecraft account.", "properties": { "account": { "description": "The refreshed Minecraft account with updated tokens.\nContains new access tokens and updated expiration times.\nFor offline accounts, returns the same account unchanged.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.MinecraftAccountProto" } ] } }, "required": [] }, "soulfire.v1.ReleaseAutomationBotClaimsResponse": { "type": "object", "additionalProperties": false, "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationBotActionResult" } }, "state": { "$ref": "#/components/schemas/soulfire.v1.AutomationCoordinationState" } }, "required": [] }, "soulfire.v1.ReleaseAutomationClaimResponse": { "type": "object", "additionalProperties": false, "properties": { "released": { "type": "boolean" }, "state": { "$ref": "#/components/schemas/soulfire.v1.AutomationCoordinationState" } }, "required": [] }, "soulfire.v1.ResetAutomationCoordinationStateResponse": { "type": "object", "additionalProperties": false, "properties": { "state": { "$ref": "#/components/schemas/soulfire.v1.AutomationCoordinationState" } }, "required": [] }, "soulfire.v1.ResetAutomationMemoryResponse": { "type": "object", "additionalProperties": false, "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationBotActionResult" } } }, "required": [] }, "soulfire.v1.ServerInfoResponse": { "type": "object", "additionalProperties": false, "description": "Response message for GetServerInfo RPC containing comprehensive server information.\nThis response provides everything needed to render a settings UI, including:\n- Current configuration values\n- All available setting definitions with their types and constraints\n- Page layouts for organizing settings in the UI\n- Information about registered plugins", "properties": { "config": { "description": "The current server configuration containing all persisted settings values.\nIf no configuration has been saved yet, this will contain default/empty values.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.ServerConfig" } ] }, "settings_definitions": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.SettingsDefinition" }, "description": "All available settings definitions that can be rendered by identifier.\nEach definition includes the setting's type (string, int, bool, etc.),\nUI metadata (display name, description), constraints (min/max, patterns),\nand scope (SERVER, INSTANCE, or BOT level).\nThese definitions are referenced by their identifier (namespace + key)." }, "server_settings": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.SettingsPage" }, "description": "Pages that group settings together for UI organization.\nEach page has an ID, display name, icon, and references settings by their identifiers.\nPages may be associated with plugins and can have an \"enabled\" toggle setting." }, "plugins": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.ServerPlugin" }, "description": "List of registered plugins on the server.\nEach plugin includes metadata such as ID, version, description, author,\nlicense, and website URL. Plugins may own settings pages." } }, "required": ["config"] }, "soulfire.v1.ServerUpdateConfigEntryResponse": { "type": "object", "additionalProperties": false, "description": "Response message for UpdateServerConfigEntry RPC.\nAn empty response indicates the setting was successfully updated.\nThe change is persisted to the database and runtime hooks are triggered\nto apply the new value immediately where applicable.", "properties": {}, "required": [] }, "soulfire.v1.ServerUpdateConfigResponse": { "type": "object", "additionalProperties": false, "description": "Response message for UpdateServerConfig RPC.\nAn empty response indicates successful configuration update.\nThe new configuration is persisted to the database and runtime hooks are triggered\n(e.g., log level adjustments take effect immediately).", "properties": {}, "required": [] }, "soulfire.v1.SetAccountMetadataEntryResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully setting a metadata entry.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.SetAutomationCollaborationResponse": { "type": "object", "additionalProperties": false, "properties": { "settings": { "$ref": "#/components/schemas/soulfire.v1.AutomationInstanceSettings" } }, "required": [] }, "soulfire.v1.SetAutomationMaxEndBotsResponse": { "type": "object", "additionalProperties": false, "properties": { "settings": { "$ref": "#/components/schemas/soulfire.v1.AutomationInstanceSettings" } }, "required": [] }, "soulfire.v1.SetAutomationObjectiveOverrideResponse": { "type": "object", "additionalProperties": false, "properties": { "settings": { "$ref": "#/components/schemas/soulfire.v1.AutomationInstanceSettings" } }, "required": [] }, "soulfire.v1.SetAutomationRoleOverrideResponse": { "type": "object", "additionalProperties": false, "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationBotActionResult" } } }, "required": [] }, "soulfire.v1.SetAutomationRolePolicyResponse": { "type": "object", "additionalProperties": false, "properties": { "settings": { "$ref": "#/components/schemas/soulfire.v1.AutomationInstanceSettings" } }, "required": [] }, "soulfire.v1.SetAutomationSharedClaimsResponse": { "type": "object", "additionalProperties": false, "properties": { "settings": { "$ref": "#/components/schemas/soulfire.v1.AutomationInstanceSettings" } }, "required": [] }, "soulfire.v1.SetAutomationSharedEndEntryResponse": { "type": "object", "additionalProperties": false, "properties": { "settings": { "$ref": "#/components/schemas/soulfire.v1.AutomationInstanceSettings" } }, "required": [] }, "soulfire.v1.SetAutomationSharedStructuresResponse": { "type": "object", "additionalProperties": false, "properties": { "settings": { "$ref": "#/components/schemas/soulfire.v1.AutomationInstanceSettings" } }, "required": [] }, "soulfire.v1.SetInstanceMetadataEntryResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully setting an instance metadata entry.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.UpdateScriptResponse": { "type": "object", "additionalProperties": false, "description": "Response after successfully updating a script.", "properties": { "script": { "description": "The updated script data.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.ScriptData" } ] }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.ValidationDiagnostic" }, "description": "Validation diagnostics (warnings) from building the script graph." } }, "required": [] }, "soulfire.v1.UpdateSelfEmailResponse": { "type": "object", "additionalProperties": false, "description": "Response message for email update operation.\nAn empty response indicates the operation completed successfully.", "properties": {}, "required": [] }, "soulfire.v1.UpdateSelfUsernameResponse": { "type": "object", "additionalProperties": false, "description": "Response message for username update operation.\nAn empty response indicates the operation completed successfully.", "properties": {}, "required": [] }, "soulfire.v1.UpdateUserResponse": { "type": "object", "additionalProperties": false, "description": "Response message returned after successfully updating a user.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.UserCreateResponse": { "type": "object", "additionalProperties": false, "description": "Response message returned after successfully creating a new user.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier (UUID) assigned to the newly created user.\nThis ID should be used for all subsequent operations on this user." } }, "required": ["id"] }, "soulfire.v1.UserDeleteResponse": { "type": "object", "additionalProperties": false, "description": "Response message returned after successfully deleting a user.\nEmpty response indicates success.", "properties": {}, "required": [] }, "soulfire.v1.UserInfoResponse": { "type": "object", "additionalProperties": false, "description": "Response message containing detailed information about a specific user.", "properties": { "username": { "type": "string", "description": "The username of the user (3-32 lowercase alphanumeric characters with dashes allowed)." }, "role": { "description": "The role of the user (ADMIN or USER).", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.UserRole" } ] }, "email": { "type": "string", "description": "The email address of the user." }, "created_at": { "description": "Timestamp when the user account was created.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] }, "updated_at": { "description": "Timestamp when the user account was last updated.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] }, "last_login_at": { "description": "Timestamp of the user's last successful authentication.\nOptional; may be absent if the user has never logged in.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] }, "min_issued_at": { "description": "Minimum issued-at timestamp for valid JWT tokens.\nTokens issued before this timestamp are considered invalid.\nUsed to invalidate all sessions by updating this value.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] } }, "required": [] }, "soulfire.v1.UserListResponse": { "type": "object", "additionalProperties": false, "description": "Response message containing a list of all users in the system.", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.UserListResponse.User" }, "description": "List of all users in the system." } }, "required": [] }, "soulfire.v1.ValidateScriptResponse": { "type": "object", "additionalProperties": false, "description": "Response containing validation diagnostics.", "properties": { "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.ValidationDiagnostic" }, "description": "All diagnostics (errors and warnings) for the script graph." } }, "required": [] }, "soulfire.v1.AutomationInstanceSettings": { "type": "object", "additionalProperties": false, "properties": { "preset": { "$ref": "#/components/schemas/soulfire.v1.AutomationPreset" }, "team_collaboration": { "type": "boolean" }, "role_policy": { "$ref": "#/components/schemas/soulfire.v1.AutomationRolePolicy" }, "shared_end_entry": { "type": "boolean" }, "max_end_bots": { "type": "integer", "format": "int32" }, "shared_structure_intel": { "type": "boolean" }, "shared_target_claims": { "type": "boolean" }, "objective_override": { "$ref": "#/components/schemas/soulfire.v1.AutomationTeamObjective" } }, "required": [] }, "soulfire.v1.AutomationBotActionResult": { "type": "object", "additionalProperties": false, "properties": { "bot_id": { "type": "string" }, "account_name": { "type": "string" }, "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [] }, "soulfire.v1.ServerDialog": { "type": "object", "additionalProperties": false, "description": "Complete server dialog definition.\nContains all information needed to render and interact with a dialog.", "properties": { "id": { "type": "string", "description": "Dialog identifier from the server.\nFormat: namespaced identifier (e.g., \"myserver:welcome_dialog\")." }, "type": { "description": "The type of dialog, determining overall structure.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogType" } ] }, "title": { "type": "string", "description": "Dialog title (may be a JSON text component)." }, "external_title": { "type": "string", "description": "Button label when shown as an external/minimized button." }, "body": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.DialogBodyElement" }, "description": "Body elements (text and items) displayed in the dialog." }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.DialogInput" }, "description": "Input controls for gathering user data." }, "can_close_with_escape": { "type": "boolean", "description": "Whether ESC key can close the dialog.\nDefault: true." }, "pause": { "type": "boolean", "description": "Whether to pause the game in singleplayer.\nDefault: true. No effect in multiplayer." }, "after_action": { "description": "Behavior after an action button is clicked.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogAfterAction" } ] }, "action": { "description": "For NOTICE type: the single action button.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogButton" } ] }, "yes": { "description": "For CONFIRMATION type: the \"yes\" button.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogButton" } ] }, "no": { "description": "For CONFIRMATION type: the \"no\" button.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogButton" } ] }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.DialogButton" }, "description": "For MULTI_ACTION type: list of action buttons." }, "columns": { "type": "integer", "format": "int32", "description": "For MULTI_ACTION and DIALOG_LIST: number of button columns.\nDefault: 2." }, "exit_action": { "description": "For MULTI_ACTION, SERVER_LINKS, DIALOG_LIST: exit/close button.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogButton" } ] }, "button_width": { "type": "integer", "format": "int32", "description": "For SERVER_LINKS and DIALOG_LIST: button width.\nDefault: 150." } }, "required": [] }, "soulfire.v1.BotLiveState": { "type": "object", "additionalProperties": false, "description": "Real-time state of a connected bot.\nContains position, health, inventory, and other live game data.", "properties": { "x": { "type": "number", "format": "double", "description": "X coordinate in the Minecraft world (east/west axis).\nEast is positive, West is negative." }, "y": { "type": "number", "format": "double", "description": "Y coordinate in the Minecraft world (vertical axis).\nIncreases upward. Sea level is typically around 63." }, "z": { "type": "number", "format": "double", "description": "Z coordinate in the Minecraft world (north/south axis).\nSouth is positive, North is negative." }, "xRot": { "type": "number", "format": "float", "description": "Vertical rotation (pitch) in degrees.\nRange: -90 (looking straight up) to 90 (looking straight down).\n0 is looking at the horizon." }, "yRot": { "type": "number", "format": "float", "description": "Horizontal rotation (yaw) in degrees.\nRange: -180 to 180. 0 = South, 90 = West, -90 = East, +/-180 = North." }, "health": { "type": "number", "format": "float", "description": "Current health points.\nRange: 0 (dead) to max_health. 1 point = half a heart in the UI." }, "max_health": { "type": "number", "format": "float", "description": "Maximum health points the player can have.\nDefault is 20 (10 hearts). Can be modified by effects or attributes." }, "food_level": { "type": "integer", "format": "int32", "description": "Current hunger/food level.\nRange: 0 (starving) to 20 (full). 1 point = half a drumstick in the UI.\nBelow 6, the player cannot sprint. At 0, health starts draining." }, "saturation_level": { "type": "number", "format": "float", "description": "Current saturation level.\nRange: 0 to food_level. Acts as a buffer before hunger depletes.\nWhen saturation is above 0, hunger bar doesn't decrease while performing actions." }, "inventory": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.InventorySlot" }, "description": "Inventory slots containing items (only non-empty slots are included).\nFor list views (GetBotList), this will be empty for performance.\nFor detail views (GetBotInfo), contains all non-empty slots from the player inventory." }, "selected_hotbar_slot": { "type": "integer", "format": "int32", "description": "Currently selected hotbar slot index.\nRange: 0 to 8, corresponding to hotbar slots 1-9 in the UI." }, "dimension": { "type": "string", "description": "The dimension the player is currently in.\nFormat: namespaced identifier (e.g., \"minecraft:overworld\", \"minecraft:the_nether\", \"minecraft:the_end\").\nCustom dimensions will use their server-defined namespace." }, "experience_level": { "type": "integer", "format": "int32", "description": "Player's current experience level (the number shown on the XP bar).\nRange: 0 to theoretically unlimited (typically 0-30+ for enchanting)." }, "experience_progress": { "type": "number", "format": "float", "description": "Progress towards the next experience level.\nRange: 0.0 (just reached current level) to 1.0 (about to level up)." }, "skin_texture_hash": { "type": "string", "description": "Skin texture hash for avatar rendering.\nThis is the hash extracted from the texture URL in the player's game profile.\nCan be used with services like mc-heads.net: https://mc-heads.net/body/\nWill be absent if the player has no custom skin or skin data is unavailable." }, "game_mode": { "description": "Current game mode of the player.\nDetermines available actions (breaking blocks, flying, taking damage, etc.).", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.GameMode" } ] } }, "required": [] }, "soulfire.v1.ContainerLayout": { "type": "object", "additionalProperties": false, "description": "Complete layout description for an open container menu.\nProvides all information needed to render the container UI.", "properties": { "title": { "type": "string", "description": "Container title/name displayed at the top.\nExamples: \"Chest\", \"Crafting Table\", \"Inventory\", custom container names." }, "regions": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.SlotRegion" }, "description": "Ordered list of slot regions defining the container layout.\nRegions are listed in rendering order (typically container slots first, then player inventory)." }, "total_slots": { "type": "integer", "format": "int32", "description": "Total number of slots in the container.\nSum of all region slot_counts." }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.ContainerButton" }, "description": "Available action buttons for this container.\nPresent for: stonecutter (recipes), enchanting table (3 enchant options),\nloom (patterns), villager trading (trade offers), beacon (effects), etc." }, "container_type": { "type": "string", "description": "Container type identifier for client-specific rendering.\nValues: \"inventory\", \"chest\", \"dispenser\", \"hopper\", \"furnace\", \"crafting\",\n\"anvil\", \"enchanting\", \"brewing\", \"beacon\", \"shulker\", \"grindstone\",\n\"stonecutter\", \"loom\", \"cartography\", \"smithing\", \"merchant\",\n\"crafter\", \"lectern\", \"generic\"" }, "text_inputs": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.ContainerTextInput" }, "description": "Text input fields available in this container.\nCurrently only populated for anvil menus." }, "book_pages": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.BookPage" }, "description": "Book pages for lectern containers.\nContains all pages of the book on the lectern." }, "current_book_page": { "type": "integer", "format": "int32", "description": "Current page being displayed (for lectern).\nZero-indexed into book_pages." } }, "required": [] }, "soulfire.v1.InventorySlot": { "type": "object", "additionalProperties": false, "description": "Represents an item in an inventory slot.\nUsed for both container slots and carried (cursor) items.", "properties": { "slot": { "type": "integer", "format": "int32", "description": "The slot index within the container.\n- For container menus: 0 to (total_slots - 1)\n- For player inventory: 0-4 crafting, 5-8 armor, 9-35 main inventory, 36-44 hotbar, 45 offhand\n- For carried items (cursor): -1 is used as a special indicator" }, "item_id": { "type": "string", "description": "The Minecraft item identifier in namespaced format.\nExamples: \"minecraft:diamond_sword\", \"minecraft:stone\", \"minecraft:enchanted_book\"" }, "count": { "type": "integer", "format": "int32", "description": "The number of items in this stack.\nRange: 1 to the item's maximum stack size (typically 1, 16, or 64)." }, "display_name": { "type": "string", "description": "The custom display name of the item, if it has been renamed.\nOnly present when the item has a custom name component (e.g., renamed in an anvil).\nContains the plain text string, not JSON text components." } }, "required": [] }, "soulfire.v1.BotListEntry": { "type": "object", "additionalProperties": false, "description": "Entry representing a single bot in the bot list.\nContains summary information suitable for display in a list view.", "properties": { "profile_id": { "type": "string", "description": "The Minecraft profile UUID of the bot.\nThis uniquely identifies the bot within the instance." }, "is_online": { "type": "boolean", "description": "Whether the bot is currently connected to a Minecraft server.\nWhen false, the bot exists in configuration but is not active." }, "live_state": { "description": "Live state of the bot if online and player data is available.\nWill be absent if the bot is offline or the player hasn't fully spawned.\nNote: For list views, inventory data is NOT included (too expensive).", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.BotLiveState" } ] } }, "required": [] }, "soulfire.v1.UserRole": { "type": "string", "description": "The role assigned to a user account, determining their base permission level.\nRoles provide a coarse-grained permission model that is supplemented by\nspecific permission grants at the global and instance levels.", "enum": ["ADMIN", "USER"] }, "soulfire.v1.GlobalPermissionState": { "type": "object", "additionalProperties": false, "description": "Represents the grant status of a single global permission for the current user.\nUsed to communicate which server-wide permissions the authenticated user has been granted.", "properties": { "global_permission": { "description": "The global permission being described.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.GlobalPermission" } ] }, "granted": { "type": "boolean", "description": "Whether this permission has been granted to the current user.\nTrue if the user has this permission, false otherwise." } }, "required": [] }, "soulfire.v1.ServerInfo": { "type": "object", "additionalProperties": false, "description": "Contains metadata about the SoulFire server instance.\nThis information is useful for client compatibility checks and connecting to related services.", "properties": { "version": { "type": "string", "description": "The semantic version of the SoulFire server (e.g., \"1.0.0\")." }, "commit_hash": { "type": "string", "description": "The git commit hash of the server build, useful for debugging and version tracking." }, "branch_name": { "type": "string", "description": "The git branch name from which the server was built (e.g., \"main\", \"develop\")." }, "public_api_address": { "type": "string", "description": "The public URL for the gRPC/HTTP API endpoint.\nThis is the base address clients should use to connect to the server." }, "public_webdav_address": { "type": "string", "description": "The public URL for the WebDAV file access endpoint.\nDerived from public_api_address with \"/webdav\" appended." }, "public_docs_address": { "type": "string", "description": "The public URL for the API documentation endpoint.\nDerived from public_api_address with \"/docs\" appended." }, "public_mcp_address": { "type": "string", "description": "The public URL for the MCP (Model Context Protocol) endpoint.\nDerived from public_api_address with \"/mcp\" appended.\nClients can use this to connect AI assistants to the SoulFire server." }, "minecraft_version": { "type": "string", "description": "The native Minecraft protocol version supported by this server (e.g., \"1.21.4\")." } }, "required": [] }, "soulfire.v1.CommandCompletion": { "type": "object", "additionalProperties": false, "description": "A single tab-completion suggestion.", "properties": { "suggestion": { "type": "string", "description": "The suggested text to insert at the cursor position.\nThis is the actual completion value, not the full command." }, "tooltip": { "type": "string", "description": "Optional tooltip providing additional context about this suggestion.\nMay contain formatted text explaining what the suggestion does.\nIf not present, no tooltip should be displayed." } }, "required": [] }, "soulfire.v1.ScriptData": { "type": "object", "additionalProperties": false, "description": "Complete data structure representing a visual script.\nContains all nodes, edges, and metadata needed to render and execute the script.", "properties": { "id": { "type": "string", "description": "Unique identifier for this script.\nFormat: UUID string." }, "name": { "type": "string", "description": "Human-readable name for the script.\nDisplayed in the UI and used for identification." }, "description": { "type": "string", "description": "Optional description explaining what the script does.\nDisplayed in script listings and detail views." }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.ScriptNode" }, "description": "The list of nodes that make up this script's graph.\nNodes are executed based on execution edge connections." }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.ScriptEdge" }, "description": "The list of edges connecting nodes in this script.\nDefines both execution flow and data transfer between nodes." }, "instance_id": { "type": "string", "description": "The instance this script belongs to.\nScripts are always associated with a specific instance.\nFormat: UUID string." }, "paused": { "type": "boolean", "description": "Whether this script is paused (not running).\nScripts run by default. When paused, they won't be started on server startup\nor when created/updated." }, "quotas": { "description": "Optional resource quotas for this script.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.ScriptQuotas" } ] } }, "required": [] }, "soulfire.v1.ValidationDiagnostic": { "type": "object", "additionalProperties": false, "description": "A structured validation diagnostic with node/edge context and severity.", "properties": { "node_id": { "type": "string", "description": "The node related to this diagnostic, or empty for graph-level issues." }, "edge_id": { "type": "string", "description": "A composite edge key related to this diagnostic, or empty." }, "message": { "type": "string", "description": "Human-readable description of the issue." }, "severity": { "description": "Severity level of this diagnostic.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DiagnosticSeverity" } ] } }, "required": [] }, "soulfire.v1.HeaderPair": { "type": "object", "additionalProperties": false, "description": "Represents a single HTTP header as a key-value pair.\nUsed for both request headers (sent to the target server) and\nresponse headers (received from the target server).", "properties": { "key": { "type": "string", "description": "The header name (e.g., \"Content-Type\", \"Authorization\", \"Accept\").\nHeader names are case-insensitive per HTTP specification." }, "value": { "type": "string", "description": "The header value (e.g., \"application/json\", \"Bearer token123\")." } }, "required": [] }, "soulfire.v1.SettingsNamespace": { "type": "object", "additionalProperties": false, "description": "A collection of settings entries grouped under a common namespace.\nUsed to organize configuration values hierarchically, where each namespace\nrepresents a logical grouping (e.g., plugin name, feature area).\nPart of the instance configuration, server configuration, and account settings.", "properties": { "namespace": { "type": "string", "description": "The namespace identifier that groups related settings together.\nTypically matches a plugin ID or internal system component name.\nExamples: \"bot\", \"account\", \"auto-reconnect\", \"anti-afk\"." }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.SettingsNamespace.SettingsEntry" }, "description": "The list of setting entries within this namespace.\nEach entry has a unique key within the namespace." } }, "required": [] }, "soulfire.v1.AutomationBotState": { "type": "object", "additionalProperties": false, "properties": { "instance_id": { "type": "string" }, "bot_id": { "type": "string" }, "account_name": { "type": "string" }, "status_summary": { "type": "string" }, "goal_mode": { "$ref": "#/components/schemas/soulfire.v1.AutomationGoalMode" }, "paused": { "type": "boolean" }, "beat_phase": { "$ref": "#/components/schemas/soulfire.v1.AutomationBeatPhase" }, "current_action": { "type": "string" }, "target": { "$ref": "#/components/schemas/soulfire.v1.AutomationRequirementTarget" }, "team_role": { "$ref": "#/components/schemas/soulfire.v1.AutomationTeamRole" }, "team_objective": { "$ref": "#/components/schemas/soulfire.v1.AutomationTeamObjective" }, "dimension": { "type": "string" }, "position": { "$ref": "#/components/schemas/soulfire.v1.AutomationPosition" }, "death_count": { "type": "integer", "format": "int32" }, "timeout_count": { "type": "integer", "format": "int32" }, "recovery_count": { "type": "integer", "format": "int32" }, "last_recovery_reason": { "type": "string" }, "last_progress_at": { "$ref": "#/components/schemas/google.protobuf.Timestamp" }, "settings": { "$ref": "#/components/schemas/soulfire.v1.AutomationBotSettings" }, "queued_targets": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationRequirementTarget" } } }, "required": [] }, "soulfire.v1.AutomationCoordinationState": { "type": "object", "additionalProperties": false, "properties": { "instance_id": { "type": "string" }, "friendly_name": { "type": "string" }, "settings": { "$ref": "#/components/schemas/soulfire.v1.AutomationInstanceSettings" }, "objective": { "$ref": "#/components/schemas/soulfire.v1.AutomationTeamObjective" }, "active_bots": { "type": "integer", "format": "int32" }, "shared_block_count": { "type": "integer", "format": "int32" }, "claim_count": { "type": "integer", "format": "int32" }, "eye_sample_count": { "type": "integer", "format": "int32" }, "shared_counts": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationSharedRequirementCount" } }, "shared_blocks": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationCoordinationSharedBlock" } }, "claims": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationCoordinationClaim" } }, "eye_samples": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationCoordinationEyeSample" } } }, "required": [] }, "soulfire.v1.AutomationMemoryState": { "type": "object", "additionalProperties": false, "properties": { "instance_id": { "type": "string" }, "bot_id": { "type": "string" }, "account_name": { "type": "string" }, "tick": { "type": "integer", "format": "int64" }, "remembered_block_count": { "type": "integer", "format": "int32" }, "remembered_container_count": { "type": "integer", "format": "int32" }, "remembered_entity_count": { "type": "integer", "format": "int32" }, "remembered_dropped_item_count": { "type": "integer", "format": "int32" }, "unreachable_position_count": { "type": "integer", "format": "int32" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationMemoryBlock" } }, "containers": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationMemoryContainer" } }, "entities": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationMemoryEntity" } }, "dropped_items": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationMemoryDroppedItem" } }, "unreachable_positions": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationMemoryUnreachablePosition" } } }, "required": [] }, "soulfire.v1.AutomationTeamState": { "type": "object", "additionalProperties": false, "properties": { "instance_id": { "type": "string" }, "friendly_name": { "type": "string" }, "settings": { "$ref": "#/components/schemas/soulfire.v1.AutomationInstanceSettings" }, "objective": { "$ref": "#/components/schemas/soulfire.v1.AutomationTeamObjective" }, "active_bots": { "type": "integer", "format": "int32" }, "quotas": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationResourceQuota" } }, "bots": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.AutomationBotState" } } }, "required": [] }, "soulfire.v1.MetricsSnapshot": { "type": "object", "additionalProperties": false, "description": "A single time-series data point sampled at a fixed interval.", "properties": { "timestamp": { "description": "When this snapshot was taken.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] }, "bots_online": { "type": "integer", "format": "int32", "description": "Number of bots currently connected to the Minecraft server." }, "bots_total": { "type": "integer", "format": "int32", "description": "Total number of bots configured in the instance (online + offline)." }, "packets_sent_total": { "type": "integer", "format": "int64", "description": "Cumulative packets sent across all bots since session start." }, "packets_received_total": { "type": "integer", "format": "int64", "description": "Cumulative packets received across all bots since session start." }, "bytes_sent_total": { "type": "integer", "format": "int64", "description": "Cumulative bytes sent across all bots since session start." }, "bytes_received_total": { "type": "integer", "format": "int64", "description": "Cumulative bytes received across all bots since session start." }, "packets_sent_per_second": { "type": "number", "format": "double", "description": "Current rate of packets sent per second (computed from counter deltas)." }, "packets_received_per_second": { "type": "number", "format": "double", "description": "Current rate of packets received per second (computed from counter deltas)." }, "bytes_sent_per_second": { "type": "number", "format": "double", "description": "Current rate of bytes sent per second (computed from counter deltas)." }, "bytes_received_per_second": { "type": "number", "format": "double", "description": "Current rate of bytes received per second (computed from counter deltas)." }, "avg_tick_duration_ms": { "type": "number", "format": "double", "description": "Average tick duration across all bots in milliseconds." }, "max_tick_duration_ms": { "type": "number", "format": "double", "description": "Maximum tick duration observed across all bots in milliseconds.\nReset each sampling interval." }, "avg_health": { "type": "number", "format": "double", "description": "Average health across all online bots with player data.\nRange: 0 to 20 (Minecraft health points)." }, "avg_food_level": { "type": "number", "format": "double", "description": "Average food level across all online bots with player data.\nRange: 0 to 20 (Minecraft food points)." }, "total_loaded_chunks": { "type": "integer", "format": "int32", "description": "Total number of loaded chunks across all online bots." }, "total_tracked_entities": { "type": "integer", "format": "int32", "description": "Total number of tracked entities across all online bots." }, "connections": { "type": "integer", "format": "int32", "description": "Connection events since the previous snapshot." }, "disconnections": { "type": "integer", "format": "int32", "description": "Disconnection events since the previous snapshot." } }, "required": [] }, "soulfire.v1.MetricsDistributions": { "type": "object", "additionalProperties": false, "description": "Current-state distributions computed from the latest bot data.\nThese are not time-series; they reflect the current instant.", "properties": { "health_histogram": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Health histogram with 10 buckets of width 2: [0,2), [2,4), ..., [18,20].\nEach entry is the count of bots whose health falls in that bucket." }, "food_histogram": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Food level histogram with 10 buckets of width 2: [0,2), [2,4), ..., [18,20]." }, "dimension_counts": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" }, "description": "Number of bots in each dimension (e.g., \"minecraft:overworld\" -> 5)." }, "game_mode_counts": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" }, "description": "Number of bots in each game mode (e.g., \"SURVIVAL\" -> 10)." }, "bot_positions": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.BotPosition" }, "description": "XZ positions of online bots for scatter plot rendering." } }, "required": [] }, "soulfire.v1.NodeTypeDefinition": { "type": "object", "additionalProperties": false, "description": "Complete definition of a node type.\nContains all metadata needed to render the node in an editor\nand validate its connections without hardcoded client knowledge.", "properties": { "type": { "type": "string", "description": "The unique type identifier for this node.\nExamples: \"trigger.on_tick\", \"action.pathfind\", \"math.add\"." }, "display_name": { "type": "string", "description": "Human-readable name displayed in the UI.\nExamples: \"On Tick\", \"Pathfind To\", \"Add\"." }, "description": { "type": "string", "description": "Description of what this node does.\nDisplayed in tooltips and node palettes." }, "category": { "type": "string", "description": "Category ID for organizing nodes in the palette.\nReferences CategoryDefinition.id from GetNodeTypesResponse.\nExamples: \"triggers\", \"actions\", \"math\", \"logic\", \"flow\"." }, "is_trigger": { "type": "boolean", "description": "Whether this is a trigger node (entry point for execution).\nTrigger nodes have no execution input and start script flows." }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.PortDefinition" }, "description": "The input ports for this node type.\nIncludes both data inputs and execution inputs." }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.PortDefinition" }, "description": "The output ports for this node type.\nIncludes both data outputs and execution outputs." }, "icon": { "type": "string", "description": "Optional icon identifier for rendering.\nCan be an icon name or emoji." }, "color": { "type": "string", "description": "Optional color hint for the node (hex color code).\nUsed for visual distinction between node categories." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords for searching/filtering nodes in the palette." }, "deprecated": { "type": "boolean", "description": "Whether this node is deprecated and should be avoided." }, "deprecation_message": { "type": "string", "description": "If deprecated, message explaining what to use instead." }, "is_layout_node": { "type": "boolean", "description": "Whether this is a layout node (reroute, frame, etc.).\nLayout nodes have special minimal rendering and don't execute logic." }, "supports_muting": { "type": "boolean", "description": "Whether this node can be muted (bypassed during execution).\nWhen muted, inputs pass through to outputs unchanged." }, "supports_preview": { "type": "boolean", "description": "Whether this node supports inline preview of its output." }, "is_expensive": { "type": "boolean", "description": "Whether this node is expensive (slow, may block).\nUsed for visual warnings in tick-path analysis." } }, "required": [] }, "soulfire.v1.CategoryDefinition": { "type": "object", "additionalProperties": false, "description": "Definition of a node category for organizing the node palette.", "properties": { "id": { "type": "string", "description": "The unique identifier for this category.\nExamples: \"triggers\", \"actions\", \"math\", \"logic\"." }, "display_name": { "type": "string", "description": "Human-readable name displayed in the UI.\nExamples: \"Triggers\", \"Actions\", \"Math\", \"Logic\"." }, "icon": { "type": "string", "description": "Icon identifier for the category.\nExamples: \"zap\", \"play\", \"calculator\", \"git-branch\"." }, "description": { "type": "string", "description": "Optional description of this category." }, "sort_order": { "type": "integer", "format": "int32", "description": "Sort order for displaying categories (lower = earlier)." } }, "required": [] }, "soulfire.v1.PortTypeMetadata": { "type": "object", "additionalProperties": false, "description": "Metadata for a port type, enabling data-driven port rendering.", "properties": { "port_type": { "description": "The port type this metadata applies to.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.PortType" } ] }, "color": { "type": "string", "description": "Display color for this port type (hex color code, e.g., \"#22c55e\")." }, "display_name": { "type": "string", "description": "Human-readable name for this port type." }, "compatible_from": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.PortType" }, "description": "List of port types that can be implicitly converted to this type.\nUsed for connection validation. Empty means only exact matches allowed." }, "handle_shape": { "description": "Shape of the handle for this port type in the visual editor.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.HandleShape" } ] }, "edge_style": { "description": "Visual style for edges of this port type.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.EdgeStyle" } ] } }, "required": [] }, "soulfire.v1.RegistryEntry": { "type": "object", "additionalProperties": false, "description": "A single registry entry (block, entity, item, or biome).", "properties": { "id": { "type": "string", "description": "The namespaced identifier (e.g., \"minecraft:diamond_ore\")." }, "display_name": { "type": "string", "description": "Human-readable display name." }, "icon": { "type": "string", "description": "Optional icon or texture identifier." }, "category": { "type": "string", "description": "Optional category/group for organizing in UI." } }, "required": [] }, "soulfire.v1.ScriptStatus": { "type": "object", "additionalProperties": false, "description": "Runtime status information for a script.\nProvides information about current activation state and statistics.", "properties": { "script_id": { "type": "string", "description": "The script this status applies to.\nFormat: UUID string." }, "is_active": { "type": "boolean", "description": "Whether the script is currently active (listening for triggers)." }, "active_node_id": { "type": "string", "description": "The ID of the currently executing node, if any.\nOnly present when a node is actively executing." }, "activation_count": { "type": "integer", "format": "int64", "description": "The total number of times this script has been activated.\nIncremented each time ActivateScript is called." } }, "required": [] }, "soulfire.v1.ServerMetricsSnapshot": { "type": "object", "additionalProperties": false, "description": "A single server-level system metrics data point sampled at a fixed interval.", "properties": { "timestamp": { "description": "When this snapshot was taken.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] }, "process_cpu_load": { "type": "number", "format": "double", "description": "JVM process CPU load (0.0 to 1.0, or -1.0 if unavailable)." }, "system_cpu_load": { "type": "number", "format": "double", "description": "System-wide CPU load (0.0 to 1.0, or -1.0 if unavailable)." }, "heap_used_bytes": { "type": "integer", "format": "int64", "description": "Heap memory currently used in bytes." }, "heap_committed_bytes": { "type": "integer", "format": "int64", "description": "Heap memory committed (reserved by JVM) in bytes." }, "heap_max_bytes": { "type": "integer", "format": "int64", "description": "Maximum heap memory in bytes (-1 if undefined)." }, "non_heap_used_bytes": { "type": "integer", "format": "int64", "description": "Non-heap memory currently used in bytes." }, "thread_count": { "type": "integer", "format": "int32", "description": "Current live thread count." }, "daemon_thread_count": { "type": "integer", "format": "int32", "description": "Current daemon thread count." }, "gc_collection_count": { "type": "integer", "format": "int64", "description": "Cumulative GC collection count across all collectors." }, "gc_collection_time_ms": { "type": "integer", "format": "int64", "description": "Cumulative GC collection time in milliseconds across all collectors." }, "uptime_ms": { "type": "integer", "format": "int64", "description": "JVM uptime in milliseconds." }, "available_processors": { "type": "integer", "format": "int32", "description": "Number of available processors." }, "total_bots_online": { "type": "integer", "format": "int32", "description": "Total bots online across all instances." }, "total_bots_total": { "type": "integer", "format": "int32", "description": "Total bots configured across all instances." }, "active_instances": { "type": "integer", "format": "int32", "description": "Number of active (non-stopped) instances." } }, "required": [] }, "soulfire.v1.InstanceAuditLogResponse.AuditLogEntry": { "type": "object", "additionalProperties": false, "description": "A single entry in the audit log.", "properties": { "id": { "type": "string", "description": "Unique identifier for this audit log entry." }, "user": { "description": "The user who performed the action.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.InstanceUser" } ] }, "type": { "description": "The type of action that was performed.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.InstanceAuditLogResponse.AuditLogEntryType" } ] }, "timestamp": { "description": "When the action was performed.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] }, "data": { "type": "string", "description": "Additional data about the action (e.g., command text for EXECUTE_COMMAND).\nMay be empty for some action types." } }, "required": [] }, "soulfire.v1.InstanceInfo": { "type": "object", "additionalProperties": false, "description": "Contains comprehensive information about an instance including its\nconfiguration, state, permissions, and available settings.", "properties": { "friendly_name": { "type": "string", "description": "The human-readable name of the instance." }, "icon": { "type": "string", "description": "The icon identifier for the instance (used for UI display)." }, "config": { "description": "The complete configuration of the instance including settings,\naccounts, and proxies.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.InstanceConfig" } ] }, "state": { "description": "The current lifecycle state of the instance.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.InstanceState" } ] }, "instance_permissions": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.InstancePermissionState" }, "description": "The permissions the current user has on this instance." }, "settings_definitions": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.SettingsDefinition" }, "description": "All available settings definitions that can be rendered by identifier.\nThese define the schema and UI configuration for each setting." }, "instance_settings": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.SettingsPage" }, "description": "Pages that group settings together for UI rendering.\nReferences settings by their identifiers from settings_definitions." }, "plugins": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.ServerPlugin" }, "description": "List of plugins registered with this instance." }, "last_modified": { "description": "Timestamp of when the configuration was last modified.\nUsed for conditional requests via if_modified_since.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] } }, "required": [] }, "soulfire.v1.InstanceNotModified": { "type": "object", "additionalProperties": false, "description": "Returned when the instance configuration has not changed since\nthe if_modified_since timestamp provided in the request.", "properties": { "last_modified": { "description": "The current last_modified timestamp of the instance.\nClients should use this for subsequent conditional requests.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] } }, "required": [] }, "soulfire.v1.InstanceListResponse.Instance": { "type": "object", "additionalProperties": false, "description": "Summary information about a single instance.", "properties": { "id": { "type": "string", "description": "The unique identifier (UUID) of the instance." }, "friendly_name": { "type": "string", "description": "The human-readable name of the instance." }, "icon": { "type": "string", "description": "The icon identifier for the instance (used for UI display)." }, "state": { "description": "The current lifecycle state of the instance.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.InstanceState" } ] }, "instance_permissions": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.InstancePermissionState" }, "description": "The permissions the current user has on this instance.\nEach permission indicates whether a specific action is allowed." } }, "required": [] }, "soulfire.v1.ScriptInfo": { "type": "object", "additionalProperties": false, "description": "Summary information about a script for listing purposes.\nContains metadata without the full node graph to reduce payload size.", "properties": { "id": { "type": "string", "description": "Unique identifier for this script.\nFormat: UUID string." }, "name": { "type": "string", "description": "Human-readable name for the script." }, "description": { "type": "string", "description": "Optional description of what the script does." }, "instance_id": { "type": "string", "description": "The instance this script belongs to.\nFormat: UUID string." }, "created_at": { "description": "Timestamp when the script was first created.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] }, "updated_at": { "description": "Timestamp when the script was last modified.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] }, "paused": { "type": "boolean", "description": "Whether this script is paused (not running)." } }, "required": [] }, "soulfire.v1.NextAuthFlowResponse.EmailCode": { "type": "object", "additionalProperties": false, "description": "Indicates that an email verification code has been sent (if the email was registered).\nThe client should prompt the user to enter the six-digit code from their email.\nThis is an empty message as the presence itself is the signal; no additional data is needed.", "properties": {}, "required": [] }, "soulfire.v1.NextAuthFlowResponse.Success": { "type": "object", "additionalProperties": false, "description": "Indicates successful authentication.\nThe client should store the JWT token and use it for subsequent authenticated requests.", "properties": { "token": { "type": "string", "description": "A JWT (JSON Web Token) for authenticating subsequent API requests.\nThis token should be included in the Authorization header for authenticated endpoints.\nThe token is issued with the \"api\" audience claim." } }, "required": [] }, "soulfire.v1.NextAuthFlowResponse.Failure": { "type": "object", "additionalProperties": false, "description": "Indicates that the authentication flow has failed.", "properties": { "reason": { "description": "The specific reason for the authentication failure.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.NextAuthFlowResponse.Failure.Reason" } ] } }, "required": [] }, "soulfire.v1.LogString": { "type": "object", "additionalProperties": false, "description": "Represents a single log entry from the SoulFire logging system.\nLog entries can be associated with specific instances, bots, or scripts,\nor they can be personal messages directed to a specific user.", "properties": { "id": { "type": "string", "description": "Unique identifier for this log entry. Format is \"{timestamp_millis}-{counter}\"\nwhere counter is an incrementing integer to ensure uniqueness within the same millisecond." }, "message": { "type": "string", "description": "The formatted log message content. This is the fully formatted output including\nany Minecraft formatting codes and exception stack traces if present." }, "instance_id": { "type": "string", "description": "The UUID of the instance this log is associated with, if any.\nPresent when the log was generated in the context of a specific attack instance." }, "bot_account_id": { "type": "string", "description": "The UUID of the bot account this log is associated with, if any.\nPresent when the log was generated by or about a specific bot." }, "script_id": { "type": "string", "description": "The UUID of the script this log is associated with, if any.\nPresent when the log was generated during script execution." }, "personal": { "type": "boolean", "description": "Indicates whether this is a personal message directed to a specific user.\nPersonal messages are only visible to the target user and are not stored in the log history." }, "instance_name": { "type": "string", "description": "Human-readable name of the instance, if available.\nProvided as a convenience to avoid requiring additional lookups." }, "bot_account_name": { "type": "string", "description": "Human-readable name of the bot account, if available.\nProvided as a convenience to avoid requiring additional lookups." }, "timestamp": { "description": "The timestamp when this log entry was created.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] }, "logger_name": { "type": "string", "description": "The name of the logger that produced this log entry (e.g., \"com.soulfiremc.server.SomeClass\").\nUseful for filtering and debugging purposes." }, "level": { "type": "string", "description": "The log level (e.g., \"INFO\", \"WARN\", \"ERROR\", \"DEBUG\", \"TRACE\", \"FATAL\").\nCorresponds to Log4j2 log levels." } }, "required": [] }, "soulfire.v1.MinecraftAccountProto": { "type": "object", "additionalProperties": false, "description": "Represents an authenticated Minecraft account that can be used by bots.\nThis can be a premium Microsoft account (Java or Bedrock) or an offline account.\nThe account contains authentication data, profile information, and per-account settings.\nUsed throughout the system for instance configuration and bot management.", "properties": { "type": { "description": "The authentication type used for this account.\nDetermines which account_data field is populated.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.MinecraftAccountProto.AccountTypeProto" } ] }, "profile_id": { "type": "string", "description": "The unique profile identifier (UUID) for this account.\nFor online accounts: The official Minecraft profile UUID from Microsoft.\nFor offline accounts: A deterministic UUID derived from the username.\nFormat: Standard UUID string (e.g., \"550e8400-e29b-41d4-a716-446655440000\")." }, "last_known_name": { "type": "string", "description": "The last known username/gamertag for this account.\nUpdated during authentication and refresh operations.\nFor Java: The Minecraft username (up to 16 characters).\nFor Bedrock: The Xbox gamertag." }, "online_chain_java_data": { "description": "Authentication chain for online Java accounts (Microsoft-authenticated).", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.MinecraftAccountProto.OnlineChainJavaData" } ] }, "offline_java_data": { "description": "Data for offline Java accounts (no authentication required).", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.MinecraftAccountProto.OfflineJavaData" } ] }, "bedrock_data": { "description": "Authentication chain for Bedrock accounts (Microsoft-authenticated).", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.MinecraftAccountProto.BedrockData" } ] }, "online_simple_java_data": { "description": "Data for Java accounts authenticated with a raw access token.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.MinecraftAccountProto.OnlineSimpleJavaData" } ] }, "config": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.SettingsNamespace" }, "description": "Per-bot configuration settings stored with the account.\nOrganized as namespace -> key -> value mappings.\nThese settings override instance-level settings when the bot is running.\nTypically includes bot-specific behavior settings." }, "persistent_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.SettingsNamespace" }, "description": "Persistent metadata stored with the account across sessions.\nOrganized as namespace -> key -> value mappings.\nUsed by plugins and the system to store account-specific state\nthat should persist across bot restarts (e.g., last position, inventory cache)." } }, "required": [] }, "soulfire.v1.ServerConfig": { "type": "object", "additionalProperties": false, "description": "ServerConfig represents the complete server-level configuration.\nIt contains all settings organized by namespace, where each namespace groups\nrelated settings together (e.g., \"dev\" namespace for developer settings).\nThis configuration is stored persistently and affects server-wide behavior.", "properties": { "settings": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.SettingsNamespace" }, "description": "Collection of settings organized by namespace.\nEach namespace contains key-value pairs representing individual settings.\nThe structure allows for hierarchical organization of configuration values." } }, "required": [] }, "soulfire.v1.SettingsDefinition": { "type": "object", "additionalProperties": false, "description": "A complete setting definition that describes a single configurable value.\nContains all information needed for a client to render the setting UI,\nvalidate input, and store/retrieve values by identifier.\nDefinitions are exported from the server and referenced by SettingsPage.", "properties": { "id": { "description": "Unique identifier for this setting (namespace + key).\nUsed to reference this setting from pages and to store/retrieve values.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.SettingsEntryIdentifier" } ] }, "scope": { "description": "The configuration scope where this setting applies (SERVER, INSTANCE, BOT).\nDetermines where values are stored and how they cascade.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.SettingsPageEntryScopeType" } ] }, "string": { "description": "String/text setting with optional validation.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.StringSetting" } ] }, "int": { "description": "Integer number setting with range constraints.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.IntSetting" } ] }, "double": { "description": "Floating-point number setting with precision control.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DoubleSetting" } ] }, "bool": { "description": "Boolean toggle setting.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.BoolSetting" } ] }, "combo": { "description": "Dropdown/select setting with predefined options.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.ComboSetting" } ] }, "string_list": { "description": "List of strings setting for multi-value input.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.StringListSetting" } ] }, "min_max": { "description": "Min/max range setting with two paired integer values.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.MinMaxSetting" } ] } }, "required": [] }, "soulfire.v1.SettingsPage": { "type": "object", "additionalProperties": false, "description": "A settings page that groups related settings together for UI navigation.\nPages provide a logical organization of settings with visual elements like\nicons and names. Each page references settings by their identifiers rather\nthan embedding the definitions, allowing settings to be shared across pages.", "properties": { "id": { "type": "string", "description": "Unique page identifier, URL-safe for navigation.\nExamples: \"bot\", \"account\", \"auto-reconnect\", \"anti-afk\".\nShould be lowercase with hyphens for word separation." }, "owning_plugin_id": { "type": "string", "description": "The ID of the plugin that owns this page (optional).\nNull/empty for internal SoulFire pages.\nUsed to group pages by plugin in the UI navigation." }, "page_name": { "type": "string", "description": "The human-readable display name shown in the UI navigation.\nExamples: \"Bot Settings\", \"Account\", \"Auto Reconnect\"." }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.SettingsEntryIdentifier" }, "description": "Ordered list of setting identifiers to display on this page.\nSettings are rendered in the order they appear in this list.\nEach identifier must correspond to a valid SettingsDefinition." }, "icon_id": { "type": "string", "description": "Icon identifier for visual representation of this page.\nUses lucide.dev icon IDs (e.g., \"bot\", \"user\", \"refresh-cw\").\nRendered next to the page name in navigation menus." }, "enabled_identifier": { "description": "Optional identifier for a boolean setting that controls whether\nthis page/feature is enabled. Used primarily for plugin pages.\nWhen set, the page may show an enable/disable toggle.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.SettingsEntryIdentifier" } ] } }, "required": [] }, "soulfire.v1.ServerPlugin": { "type": "object", "additionalProperties": false, "description": "Metadata about a registered server plugin.\nPlugins extend SoulFire functionality by adding new settings, commands,\nand bot behaviors. This information is displayed in the client UI.\nReturned as part of InstanceInfo and ServerInfoResponse.", "properties": { "id": { "type": "string", "description": "The unique plugin identifier.\nShould be a lowercase, hyphenated string (e.g., \"auto-reconnect\", \"chat-control\").\nUsed to reference the plugin in owning_plugin_id fields." }, "version": { "type": "string", "description": "The semantic version of the plugin (e.g., \"1.0.0\", \"2.1.3-beta\").\nFollows semver conventions for compatibility tracking." }, "description": { "type": "string", "description": "A brief description of what the plugin does.\nShown in plugin lists and information panels." }, "author": { "type": "string", "description": "The author or organization that created the plugin.\nTypically a name or organization identifier." }, "license": { "type": "string", "description": "The software license under which the plugin is distributed.\nExamples: \"MIT\", \"Apache-2.0\", \"GPL-3.0\"." }, "website": { "type": "string", "description": "URL to the plugin's website, documentation, or repository.\nAllows users to find more information or report issues." } }, "required": [] }, "google.protobuf.Timestamp": { "type": "object", "additionalProperties": false, "description": "A Timestamp represents a point in time independent of any time zone or local\ncalendar, encoded as a count of seconds and fractions of seconds at\nnanosecond resolution. The count is relative to an epoch at UTC midnight on\nJanuary 1, 1970, in the proleptic Gregorian calendar which extends the\nGregorian calendar backwards to year one.\n\nAll minutes are 60 seconds long. Leap seconds are \"smeared\" so that no leap\nsecond table is needed for interpretation, using a [24-hour linear\nsmear](https://developers.google.com/time/smear).\n\nThe range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By\nrestricting to that range, we ensure that we can convert to and from [RFC\n3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.\n\n# Examples\n\nExample 1: Compute Timestamp from POSIX `time()`.\n\nTimestamp timestamp;\ntimestamp.set_seconds(time(NULL));\ntimestamp.set_nanos(0);\n\nExample 2: Compute Timestamp from POSIX `gettimeofday()`.\n\nstruct timeval tv;\ngettimeofday(&tv, NULL);\n\nTimestamp timestamp;\ntimestamp.set_seconds(tv.tv_sec);\ntimestamp.set_nanos(tv.tv_usec * 1000);\n\nExample 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.\n\nFILETIME ft;\nGetSystemTimeAsFileTime(&ft);\nUINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;\n\n// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z\n// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.\nTimestamp timestamp;\ntimestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));\ntimestamp.set_nanos((INT32) ((ticks % 10000000) * 100));\n\nExample 4: Compute Timestamp from Java `System.currentTimeMillis()`.\n\nlong millis = System.currentTimeMillis();\n\nTimestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)\n.setNanos((int) ((millis % 1000) * 1000000)).build();\n\nExample 5: Compute Timestamp from Java `Instant.now()`.\n\nInstant now = Instant.now();\n\nTimestamp timestamp =\nTimestamp.newBuilder().setSeconds(now.getEpochSecond())\n.setNanos(now.getNano()).build();\n\nExample 6: Compute Timestamp from current time in Python.\n\ntimestamp = Timestamp()\ntimestamp.GetCurrentTime()\n\n# JSON Mapping\n\nIn JSON format, the Timestamp type is encoded as a string in the\n[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the\nformat is \"{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z\"\nwhere {year} is always expressed using four digits while {month}, {day},\n{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional\nseconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),\nare optional. The \"Z\" suffix indicates the timezone (\"UTC\"); the timezone\nis required. A ProtoJSON serializer should always use UTC (as indicated by\n\"Z\") when printing the Timestamp type and a ProtoJSON parser should be\nable to accept both UTC and other timezones (as indicated by an offset).\n\nFor example, \"2017-01-15T01:30:15.01Z\" encodes 15.01 seconds past\n01:30 UTC on January 15, 2017.\n\nIn JavaScript, one can convert a Date object to this format using the\nstandard\n[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)\nmethod. In Python, a standard `datetime.datetime` object can be converted\nto this format using\n[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with\nthe time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use\nthe Joda Time's [`ISODateTimeFormat.dateTime()`](\nhttp://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()\n) to obtain a formatter capable of generating timestamps in this format.", "properties": { "seconds": { "type": "integer", "format": "int64", "description": "Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must\nbe between -62135596800 and 253402300799 inclusive (which corresponds to\n0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z)." }, "nanos": { "type": "integer", "format": "int32", "description": "Non-negative fractions of a second at nanosecond resolution. This field is\nthe nanosecond portion of the duration, not an alternative to seconds.\nNegative second values with fractions must still have non-negative nanos\nvalues that count forward in time. Must be between 0 and 999,999,999\ninclusive." } }, "required": [] }, "soulfire.v1.UserListResponse.User": { "type": "object", "additionalProperties": false, "description": "Represents a user in the list with all their profile information.", "properties": { "id": { "type": "string", "description": "The unique identifier (UUID) of the user." }, "username": { "type": "string", "description": "The username of the user (3-32 lowercase alphanumeric characters with dashes allowed)." }, "role": { "description": "The role of the user (ADMIN or USER).", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.UserRole" } ] }, "email": { "type": "string", "description": "The email address of the user." }, "created_at": { "description": "Timestamp when the user account was created.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] }, "updated_at": { "description": "Timestamp when the user account was last updated.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] }, "last_login_at": { "description": "Timestamp of the user's last successful authentication.\nOptional; may be absent if the user has never logged in.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] }, "min_issued_at": { "description": "Minimum issued-at timestamp for valid JWT tokens.\nTokens issued before this timestamp are considered invalid.\nUsed to invalidate all sessions by updating this value.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Timestamp" } ] } }, "required": [] }, "soulfire.v1.AutomationPreset": { "type": "string", "enum": [ "AUTOMATION_PRESET_UNSPECIFIED", "AUTOMATION_PRESET_BALANCED_TEAM", "AUTOMATION_PRESET_INDEPENDENT_RUNNERS", "AUTOMATION_PRESET_CAUTIOUS_TEAM" ] }, "soulfire.v1.AutomationRolePolicy": { "type": "string", "enum": [ "AUTOMATION_ROLE_POLICY_UNSPECIFIED", "AUTOMATION_ROLE_POLICY_STATIC_TEAM", "AUTOMATION_ROLE_POLICY_INDEPENDENT" ] }, "soulfire.v1.AutomationTeamObjective": { "type": "string", "enum": [ "AUTOMATION_TEAM_OBJECTIVE_UNSPECIFIED", "AUTOMATION_TEAM_OBJECTIVE_BOOTSTRAP", "AUTOMATION_TEAM_OBJECTIVE_NETHER_PROGRESS", "AUTOMATION_TEAM_OBJECTIVE_STRONGHOLD_HUNT", "AUTOMATION_TEAM_OBJECTIVE_END_ASSAULT", "AUTOMATION_TEAM_OBJECTIVE_COMPLETE" ] }, "soulfire.v1.DialogType": { "type": "string", "description": "Dialog types matching Minecraft's dialog registry.\nDetermines the overall structure and behavior of the dialog.", "enum": [ "DIALOG_TYPE_UNSPECIFIED", "DIALOG_TYPE_NOTICE", "DIALOG_TYPE_CONFIRMATION", "DIALOG_TYPE_MULTI_ACTION", "DIALOG_TYPE_SERVER_LINKS", "DIALOG_TYPE_DIALOG_LIST" ] }, "soulfire.v1.DialogBodyElement": { "type": "object", "additionalProperties": false, "description": "Body element that can appear in a dialog.\nDialogs can contain a mix of text and item displays.", "properties": { "plain_message": { "description": "Plain text message element.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogPlainMessage" } ] }, "item": { "description": "Item display element (shows a Minecraft item).", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogItem" } ] } }, "required": [] }, "soulfire.v1.DialogInput": { "type": "object", "additionalProperties": false, "description": "Input control that can appear in a dialog.\nAllows dialogs to gather user input before submission.", "properties": { "text": { "description": "Text input field (single or multi-line).", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogTextInput" } ] }, "boolean": { "description": "Boolean checkbox input.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogBooleanInput" } ] }, "single_option": { "description": "Dropdown/combo box for selecting one option.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogSingleOptionInput" } ] }, "number_range": { "description": "Slider for selecting a number in a range.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogNumberRangeInput" } ] } }, "required": [] }, "soulfire.v1.DialogAfterAction": { "type": "string", "description": "Behavior after a dialog action is triggered.", "enum": [ "DIALOG_AFTER_ACTION_UNSPECIFIED", "DIALOG_AFTER_ACTION_CLOSE", "DIALOG_AFTER_ACTION_NONE", "DIALOG_AFTER_ACTION_WAIT_FOR_RESPONSE" ] }, "soulfire.v1.DialogButton": { "type": "object", "additionalProperties": false, "description": "Button that can appear in a dialog.", "properties": { "label": { "type": "string", "description": "Button text (may be a JSON text component)." }, "tooltip": { "type": "string", "description": "Optional tooltip shown on hover." }, "width": { "type": "integer", "format": "int32", "description": "Button width in pixels.\nRange: 1-1024, default: 150." }, "action": { "description": "Action to perform when clicked.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogAction" } ] } }, "required": [] }, "soulfire.v1.GameMode": { "type": "string", "description": "Minecraft game modes that determine player capabilities.", "enum": [ "GAME_MODE_UNSPECIFIED", "GAME_MODE_SURVIVAL", "GAME_MODE_CREATIVE", "GAME_MODE_ADVENTURE", "GAME_MODE_SPECTATOR" ] }, "soulfire.v1.SlotRegion": { "type": "object", "additionalProperties": false, "description": "A group of slots that should be rendered together in the UI.\nDefines the layout grid for a section of the inventory.", "properties": { "id": { "type": "string", "description": "Unique identifier for this region within the container.\nExamples: \"container\", \"player_inventory\", \"player_hotbar\", \"crafting_output\"" }, "label": { "type": "string", "description": "Display label for this region.\nExamples: \"Chest\", \"Inventory\", \"Hotbar\", \"Crafting Grid\"" }, "start_index": { "type": "integer", "format": "int32", "description": "First slot index belonging to this region.\nSlots are numbered sequentially from 0 across all regions." }, "slot_count": { "type": "integer", "format": "int32", "description": "Total number of slots in this region." }, "columns": { "type": "integer", "format": "int32", "description": "Number of columns for grid layout.\nCommon values: 9 (standard inventory width), 3 (dispenser), 1 (armor column)" }, "type": { "description": "The type of region, affecting rendering behavior.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.SlotRegionType" } ] } }, "required": [] }, "soulfire.v1.ContainerButton": { "type": "object", "additionalProperties": false, "description": "A clickable button in a container menu.\nUsed for special interactions like enchantment selection, stonecutter recipes, trade offers, etc.", "properties": { "button_id": { "type": "integer", "format": "int32", "description": "Button ID to send to the server when clicking.\nThe meaning depends on the container type." }, "label": { "type": "string", "description": "Display label for the button.\nExamples: \"Enchant Slot 1\", \"Recipe 5\", \"8x Emerald -> 1x Diamond Pickaxe\"" }, "icon_item_id": { "type": "string", "description": "Optional item ID for displaying an icon.\nExample: \"minecraft:enchanted_book\", \"minecraft:stone_bricks\"" }, "description": { "type": "string", "description": "Optional tooltip/description text with additional details.\nExamples: \"Requires 3 lapis, 30 levels\", \"Out of stock\"" }, "disabled": { "type": "boolean", "description": "Whether the button is currently disabled (cannot be clicked).\nReasons vary by container: missing materials, out of stock, insufficient levels, etc." }, "selected": { "type": "boolean", "description": "Whether this button is currently selected/active.\nUsed for toggle-style buttons or to show current selection." } }, "required": [] }, "soulfire.v1.ContainerTextInput": { "type": "object", "additionalProperties": false, "description": "Text input field in a container menu.\nCurrently only used by the anvil for item renaming.", "properties": { "id": { "type": "string", "description": "Field identifier for the SetContainerText RPC.\nCurrently supported: \"item_name\" (anvil rename)" }, "label": { "type": "string", "description": "Display label for the input field." }, "current_value": { "type": "string", "description": "Current text value in the field.\nFor anvil: the item's current custom name, or empty if none." }, "max_length": { "type": "integer", "format": "int32", "description": "Maximum allowed character length.\nFor anvil: 50 characters.\nValue of 0 means no limit." }, "placeholder": { "type": "string", "description": "Placeholder text shown when field is empty." } }, "required": [] }, "soulfire.v1.BookPage": { "type": "object", "additionalProperties": false, "description": "A page from a book, used for lectern display.", "properties": { "page_number": { "type": "integer", "format": "int32", "description": "Zero-indexed page number." }, "content": { "type": "string", "description": "Page content text.\nMay contain Minecraft formatting codes (section symbols)." } }, "required": [] }, "soulfire.v1.GlobalPermission": { "type": "string", "description": "Server-wide permissions that apply globally across all instances.\nThese permissions control access to server administration, user management,\nand self-service operations. Checked via the PermissionContext.global() method.\nADMIN role users have all global permissions by default.", "enum": [ "CREATE_INSTANCE", "GLOBAL_SUBSCRIBE_LOGS", "READ_CLIENT_DATA", "READ_SERVER_CONFIG", "UPDATE_SERVER_CONFIG", "CREATE_USER", "READ_USER", "UPDATE_USER", "DELETE_USER", "GLOBAL_COMMAND_EXECUTION", "INVALIDATE_SESSIONS", "GENERATE_SELF_WEBDAV_TOKEN", "GENERATE_SELF_API_TOKEN", "UPDATE_SELF_USERNAME", "UPDATE_SELF_EMAIL", "GENERATE_API_TOKEN", "INVALIDATE_SELF_SESSIONS" ] }, "soulfire.v1.ScriptNode": { "type": "object", "additionalProperties": false, "description": "Represents a single node in the visual script graph.\nNodes are the building blocks of scripts, each performing a specific action\nor computation when executed.", "properties": { "id": { "type": "string", "description": "Unique identifier for this node within the script.\nUsed to reference this node in edges and during execution tracking.\nFormat: UUID string." }, "type": { "type": "string", "description": "The type identifier for this node, determining its behavior and available ports.\nExamples: \"trigger.on_chat\", \"action.send_message\", \"control.delay\", \"logic.condition\"." }, "position": { "description": "The visual position of this node on the editor canvas.\nPersisted to maintain the user's layout when reopening the script.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.Position" } ] }, "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/google.protobuf.Value" }, "description": "Configuration data for this node instance.\nContains node-specific settings and parameter values.\nThe structure depends on the node type." }, "muted": { "type": "boolean", "description": "Whether this node is muted (bypassed during execution).\nWhen muted, the node passes inputs directly to outputs without processing.\nVisually shown as grayed out with pass-through indicator." }, "collapsed": { "type": "boolean", "description": "Whether this node is collapsed (showing only header).\nCollapsed nodes still function normally but take less visual space." }, "width": { "type": "number", "format": "double", "description": "For frame nodes: the width of the frame." }, "height": { "type": "number", "format": "double", "description": "For frame nodes: the height of the frame." }, "contained_nodes": { "type": "array", "items": { "type": "string" }, "description": "For frame nodes: IDs of nodes contained within this frame.\nUpdated automatically based on node positions." }, "label": { "type": "string", "description": "Optional label override for this node instance.\nIf set, displayed instead of the node type's default label." }, "resolved_type": { "description": "For reroute nodes: the resolved port type based on connections.\nDynamically updated when connections change.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.PortType" } ] }, "parent_frame_id": { "type": "string", "description": "Parent frame node ID, if this node is inside a frame." } }, "required": [] }, "soulfire.v1.ScriptEdge": { "type": "object", "additionalProperties": false, "description": "Represents a connection between two nodes in the visual script graph.\nEdges define how execution flows and how data passes between nodes.", "properties": { "id": { "type": "string", "description": "Unique identifier for this edge within the script.\nFormat: UUID string." }, "source": { "type": "string", "description": "The ID of the source node where this edge originates.\nMust reference a valid node ID in the script's nodes list." }, "source_handle": { "type": "string", "description": "The handle/port identifier on the source node.\nIdentifies which output port of the source node this edge connects from.\nExamples: \"exec_out\", \"value\", \"true\", \"false\"." }, "target": { "type": "string", "description": "The ID of the target node where this edge terminates.\nMust reference a valid node ID in the script's nodes list." }, "target_handle": { "type": "string", "description": "The handle/port identifier on the target node.\nIdentifies which input port of the target node this edge connects to.\nExamples: \"exec_in\", \"message\", \"condition\"." }, "edge_type": { "description": "The type of this edge, determining whether it carries execution flow or data.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.EdgeType" } ] } }, "required": [] }, "soulfire.v1.ScriptQuotas": { "type": "object", "additionalProperties": false, "description": "Resource quotas for limiting script execution.\nAll fields are optional; unset fields use server defaults.", "properties": { "max_execution_count": { "type": "integer", "format": "int64", "description": "Maximum number of node executions per trigger invocation." }, "max_execution_time_ms": { "type": "integer", "format": "int64", "description": "Maximum wall-clock time for a single trigger execution in milliseconds." }, "max_concurrent_triggers": { "type": "integer", "format": "int32", "description": "Maximum number of concurrent trigger invocations." }, "max_state_store_entries": { "type": "integer", "format": "int64", "description": "Maximum number of entries in the script's state store." }, "disable_timeouts": { "type": "boolean", "description": "When true, disables per-node and data edge timeouts entirely." } }, "required": [] }, "soulfire.v1.DiagnosticSeverity": { "type": "string", "description": "Severity level for validation diagnostics.", "enum": ["DIAGNOSTIC_ERROR", "DIAGNOSTIC_WARNING"] }, "soulfire.v1.SettingsNamespace.SettingsEntry": { "type": "object", "additionalProperties": false, "description": "A single key-value setting entry within a namespace.", "properties": { "key": { "type": "string", "description": "The unique key identifying this setting within its namespace.\nShould be a valid identifier (alphanumeric with underscores/dashes)." }, "value": { "description": "The value of this setting as a protobuf Value.\nCan be a string, number, boolean, list, or nested object.\nThe expected type depends on the setting definition (see SettingsDefinition).", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Value" } ] } }, "required": [] }, "soulfire.v1.AutomationGoalMode": { "type": "string", "enum": [ "AUTOMATION_GOAL_MODE_UNSPECIFIED", "AUTOMATION_GOAL_MODE_IDLE", "AUTOMATION_GOAL_MODE_ACQUIRE", "AUTOMATION_GOAL_MODE_BEAT" ] }, "soulfire.v1.AutomationBeatPhase": { "type": "string", "enum": [ "AUTOMATION_BEAT_PHASE_UNSPECIFIED", "AUTOMATION_BEAT_PHASE_PREPARE_OVERWORLD", "AUTOMATION_BEAT_PHASE_ENTER_NETHER", "AUTOMATION_BEAT_PHASE_NETHER_COLLECTION", "AUTOMATION_BEAT_PHASE_RETURN_TO_OVERWORLD", "AUTOMATION_BEAT_PHASE_STRONGHOLD_SEARCH", "AUTOMATION_BEAT_PHASE_ACTIVATE_PORTAL", "AUTOMATION_BEAT_PHASE_END_FIGHT", "AUTOMATION_BEAT_PHASE_COMPLETE" ] }, "soulfire.v1.AutomationRequirementTarget": { "type": "object", "additionalProperties": false, "properties": { "requirement_key": { "type": "string" }, "display_name": { "type": "string" }, "count": { "type": "integer", "format": "int32" } }, "required": [] }, "soulfire.v1.AutomationTeamRole": { "type": "string", "enum": [ "AUTOMATION_TEAM_ROLE_UNSPECIFIED", "AUTOMATION_TEAM_ROLE_LEAD", "AUTOMATION_TEAM_ROLE_PORTAL_ENGINEER", "AUTOMATION_TEAM_ROLE_NETHER_RUNNER", "AUTOMATION_TEAM_ROLE_STRONGHOLD_SCOUT", "AUTOMATION_TEAM_ROLE_END_SUPPORT" ] }, "soulfire.v1.AutomationPosition": { "type": "object", "additionalProperties": false, "properties": { "x": { "type": "number", "format": "double" }, "y": { "type": "number", "format": "double" }, "z": { "type": "number", "format": "double" } }, "required": [] }, "soulfire.v1.AutomationBotSettings": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "allow_death_recovery": { "type": "boolean" }, "memory_scan_radius": { "type": "integer", "format": "int32" }, "memory_scan_interval_ticks": { "type": "integer", "format": "int32" }, "retreat_health_threshold": { "type": "integer", "format": "int32" }, "retreat_food_threshold": { "type": "integer", "format": "int32" }, "role_override": { "$ref": "#/components/schemas/soulfire.v1.AutomationTeamRole" } }, "required": [] }, "soulfire.v1.AutomationSharedRequirementCount": { "type": "object", "additionalProperties": false, "properties": { "requirement_key": { "type": "string" }, "display_name": { "type": "string" }, "current_count": { "type": "integer", "format": "int32" }, "target_count": { "type": "integer", "format": "int32" } }, "required": [] }, "soulfire.v1.AutomationCoordinationSharedBlock": { "type": "object", "additionalProperties": false, "properties": { "observer_bot_id": { "type": "string" }, "observer_account_name": { "type": "string" }, "dimension": { "type": "string" }, "x": { "type": "integer", "format": "int32" }, "y": { "type": "integer", "format": "int32" }, "z": { "type": "integer", "format": "int32" }, "block_id": { "type": "string" }, "last_seen_at": { "$ref": "#/components/schemas/google.protobuf.Timestamp" } }, "required": [] }, "soulfire.v1.AutomationCoordinationClaim": { "type": "object", "additionalProperties": false, "properties": { "key": { "type": "string" }, "owner_bot_id": { "type": "string" }, "owner_account_name": { "type": "string" }, "target": { "$ref": "#/components/schemas/soulfire.v1.AutomationPosition" }, "expires_at": { "$ref": "#/components/schemas/google.protobuf.Timestamp" } }, "required": [] }, "soulfire.v1.AutomationCoordinationEyeSample": { "type": "object", "additionalProperties": false, "properties": { "bot_id": { "type": "string" }, "account_name": { "type": "string" }, "origin": { "$ref": "#/components/schemas/soulfire.v1.AutomationPosition" }, "direction": { "$ref": "#/components/schemas/soulfire.v1.AutomationPosition" }, "recorded_at": { "$ref": "#/components/schemas/google.protobuf.Timestamp" } }, "required": [] }, "soulfire.v1.AutomationMemoryBlock": { "type": "object", "additionalProperties": false, "properties": { "x": { "type": "integer", "format": "int32" }, "y": { "type": "integer", "format": "int32" }, "z": { "type": "integer", "format": "int32" }, "block_id": { "type": "string" }, "last_seen_tick": { "type": "integer", "format": "int64" } }, "required": [] }, "soulfire.v1.AutomationMemoryContainer": { "type": "object", "additionalProperties": false, "properties": { "x": { "type": "integer", "format": "int32" }, "y": { "type": "integer", "format": "int32" }, "z": { "type": "integer", "format": "int32" }, "block_id": { "type": "string" }, "inspected": { "type": "boolean" }, "distinct_item_kinds": { "type": "integer", "format": "int32" }, "total_item_count": { "type": "integer", "format": "int32" }, "last_seen_tick": { "type": "integer", "format": "int64" } }, "required": [] }, "soulfire.v1.AutomationMemoryEntity": { "type": "object", "additionalProperties": false, "properties": { "entity_id": { "type": "string" }, "entity_type": { "type": "string" }, "position": { "$ref": "#/components/schemas/soulfire.v1.AutomationPosition" }, "last_seen_tick": { "type": "integer", "format": "int64" } }, "required": [] }, "soulfire.v1.AutomationMemoryDroppedItem": { "type": "object", "additionalProperties": false, "properties": { "entity_id": { "type": "string" }, "item_id": { "type": "string" }, "count": { "type": "integer", "format": "int32" }, "position": { "$ref": "#/components/schemas/soulfire.v1.AutomationPosition" }, "last_seen_tick": { "type": "integer", "format": "int64" } }, "required": [] }, "soulfire.v1.AutomationMemoryUnreachablePosition": { "type": "object", "additionalProperties": false, "properties": { "x": { "type": "integer", "format": "int32" }, "y": { "type": "integer", "format": "int32" }, "z": { "type": "integer", "format": "int32" }, "until_tick": { "type": "integer", "format": "int64" } }, "required": [] }, "soulfire.v1.AutomationResourceQuota": { "type": "object", "additionalProperties": false, "properties": { "requirement_key": { "type": "string" }, "display_name": { "type": "string" }, "current_count": { "type": "integer", "format": "int32" }, "target_count": { "type": "integer", "format": "int32" } }, "required": [] }, "soulfire.v1.BotPosition": { "type": "object", "additionalProperties": false, "description": "Position of a single bot on the XZ plane.", "properties": { "x": { "type": "number", "format": "double", "description": "X coordinate in the Minecraft world." }, "z": { "type": "number", "format": "double", "description": "Z coordinate in the Minecraft world." }, "dimension": { "type": "string", "description": "Dimension the bot is in (e.g., \"minecraft:overworld\")." } }, "required": [] }, "soulfire.v1.PortDefinition": { "type": "object", "additionalProperties": false, "description": "Definition of a port (input or output) on a node type.\nDescribes the port's type, constraints, and display properties.", "properties": { "id": { "type": "string", "description": "The identifier for this port.\nUsed in edge connections (source_handle/target_handle).\nExamples: \"value\", \"target\", \"bot\", \"exec_in\", \"exec_out\"." }, "display_name": { "type": "string", "description": "Human-readable name displayed in the UI.\nExamples: \"Target Position\", \"Bot\", \"Message\"." }, "port_type": { "description": "The data type this port accepts or produces.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.PortType" } ] }, "required": { "type": "boolean", "description": "Whether this input is required for the node to execute.\nOnly applicable for input ports." }, "default_value": { "type": "string", "description": "Default value for this port when not connected (JSON-encoded).\nOnly applicable for input ports." }, "description": { "type": "string", "description": "Optional description explaining what this port is for." }, "element_type": { "description": "For list ports, the type of elements in the list.\nOnly applicable when port_type is PORT_TYPE_LIST.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.PortType" } ] }, "multi_input": { "type": "boolean", "description": "Whether this input accepts multiple connections (Blender-style multi-input).\nWhen true, all connected values are collected into a list.\nVisually rendered as a pill/ellipsis shaped socket." }, "accepted_types": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.PortType" }, "description": "For polymorphic ports, the list of accepted types.\nIf non-empty, this port can accept any of these types and will\nadapt its behavior based on the connected type." }, "infer_type_from": { "type": "string", "description": "For dynamic output ports, the ID of the input port to inherit type from.\nUsed for polymorphic nodes where output type depends on input type." }, "type_descriptor": { "description": "Optional generic type descriptor for parameterized types.\nWhen present, provides richer type information than the flat port_type field.\nFor example, List or a type variable T that resolves from connections.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.TypeDescriptor" } ] } }, "required": [] }, "soulfire.v1.PortType": { "type": "string", "description": "The data type of a node port.\nUsed for validation and UI rendering of connections.", "enum": [ "PORT_TYPE_ANY", "PORT_TYPE_NUMBER", "PORT_TYPE_STRING", "PORT_TYPE_BOOLEAN", "PORT_TYPE_VECTOR3", "PORT_TYPE_BOT", "PORT_TYPE_LIST", "PORT_TYPE_EXEC", "PORT_TYPE_BLOCK", "PORT_TYPE_ENTITY", "PORT_TYPE_ITEM", "PORT_TYPE_MAP" ] }, "soulfire.v1.HandleShape": { "type": "string", "description": "Shape of the port handle in the visual editor.", "enum": [ "HANDLE_SHAPE_CIRCLE", "HANDLE_SHAPE_SQUARE", "HANDLE_SHAPE_DIAMOND" ] }, "soulfire.v1.EdgeStyle": { "type": "string", "description": "Visual style for edges connected to this port type.", "enum": [ "EDGE_STYLE_DEFAULT", "EDGE_STYLE_ANIMATED", "EDGE_STYLE_DASHED" ] }, "soulfire.v1.InstanceUser": { "type": "object", "additionalProperties": false, "description": "Represents a user associated with an instance, typically used in audit logs\nto track who performed an action.", "properties": { "id": { "type": "string", "description": "Unique identifier for the user (UUID format)." }, "username": { "type": "string", "description": "The username of the user." }, "email": { "type": "string", "description": "The email address of the user." } }, "required": [] }, "soulfire.v1.InstanceAuditLogResponse.AuditLogEntryType": { "type": "string", "description": "Types of actions that are recorded in the audit log.", "enum": [ "EXECUTE_COMMAND", "START_SESSION", "PAUSE_SESSION", "RESUME_SESSION", "STOP_SESSION", "AUTOMATION_START", "AUTOMATION_PAUSE", "AUTOMATION_RESUME", "AUTOMATION_STOP", "AUTOMATION_UPDATE_SETTINGS", "AUTOMATION_APPLY_PRESET", "AUTOMATION_RESET_MEMORY", "AUTOMATION_RESET_COORDINATION", "AUTOMATION_RELEASE_CLAIMS" ] }, "soulfire.v1.InstanceConfig": { "type": "object", "additionalProperties": false, "description": "Contains the complete configuration for an instance, including settings,\nMinecraft accounts, and proxies.", "properties": { "settings": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.SettingsNamespace" }, "description": "Instance settings organized by namespace. Each namespace contains\nkey-value pairs for configuration options." }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.MinecraftAccountProto" }, "description": "List of Minecraft accounts available to this instance for bot connections." }, "proxies": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.ProxyProto" }, "description": "List of proxies available to this instance for routing bot connections." }, "persistent_metadata": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.SettingsNamespace" }, "description": "Persistent metadata stored with the instance across sessions.\nOrganized as namespace -> key -> value mappings.\nUsed by plugins and the system to store instance-specific state\nthat should persist across restarts." } }, "required": [] }, "soulfire.v1.InstanceState": { "type": "string", "description": "Represents the lifecycle state of an instance session.\nState transitions follow a specific flow:\nSTOPPED -> STARTING -> RUNNING <-> PAUSED -> STOPPING -> STOPPED", "enum": ["STARTING", "RUNNING", "PAUSED", "STOPPING", "STOPPED"] }, "soulfire.v1.InstancePermissionState": { "type": "object", "additionalProperties": false, "description": "Represents the grant status of a specific instance permission for the current user.", "properties": { "instance_permission": { "description": "The permission being described.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.InstancePermission" } ] }, "granted": { "type": "boolean", "description": "Whether the current user has been granted this permission." } }, "required": [] }, "soulfire.v1.NextAuthFlowResponse.Failure.Reason": { "type": "string", "description": "Enumeration of possible failure reasons.", "enum": ["INVALID_CODE"] }, "soulfire.v1.MinecraftAccountProto.AccountTypeProto": { "type": "string", "description": "The type of authentication that was used to create this account.\nDetermines which account_data oneof field is populated and how the account\ncan be refreshed or re-authenticated.", "enum": [ "MICROSOFT_JAVA_CREDENTIALS", "MICROSOFT_BEDROCK_CREDENTIALS", "OFFLINE", "MICROSOFT_JAVA_DEVICE_CODE", "MICROSOFT_BEDROCK_DEVICE_CODE", "MICROSOFT_JAVA_REFRESH_TOKEN", "MICROSOFT_JAVA_COOKIES", "MICROSOFT_JAVA_ACCESS_TOKEN" ] }, "soulfire.v1.MinecraftAccountProto.OnlineChainJavaData": { "type": "object", "additionalProperties": false, "description": "Authentication chain data for online Java Edition accounts.\nContains OAuth tokens, Minecraft profile data, and Xbox Live authentication details.\nUsed for Microsoft-authenticated Java accounts to maintain session state.", "properties": { "auth_chain": { "description": "JSON structure containing the complete authentication chain from minecraftauth library.\nIncludes Microsoft OAuth tokens, Xbox Live tokens, and Minecraft access tokens.\nThis data can be refreshed to obtain new tokens without re-authentication.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Struct" } ] } }, "required": [] }, "soulfire.v1.MinecraftAccountProto.OfflineJavaData": { "type": "object", "additionalProperties": false, "description": "Account data for offline mode Java accounts.\nContains no authentication data since offline accounts don't require Microsoft auth.\nThe profile UUID is derived deterministically from the username.", "properties": {}, "required": [] }, "soulfire.v1.MinecraftAccountProto.BedrockData": { "type": "object", "additionalProperties": false, "description": "Authentication chain data for Bedrock Edition accounts.\nContains Xbox Live and Bedrock-specific authentication details.\nUsed for Microsoft-authenticated Bedrock accounts.", "properties": { "auth_chain": { "description": "JSON structure containing the complete Bedrock authentication chain.\nIncludes Xbox Live tokens and Bedrock-specific session data.\nCompatible with the ViaBedrock protocol implementation.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Struct" } ] } }, "required": [] }, "soulfire.v1.MinecraftAccountProto.OnlineSimpleJavaData": { "type": "object", "additionalProperties": false, "description": "Account data for Java Edition accounts authenticated with a raw access token.\nContains only the token and its expiry, without a full authentication chain.\nCannot be refreshed; used until the token expires.", "properties": { "access_token": { "type": "string", "description": "The raw Minecraft access token (JWT)." }, "expire_time_ms": { "type": "integer", "format": "int64", "description": "Token expiry time in milliseconds since epoch." } }, "required": [] }, "soulfire.v1.SettingsEntryIdentifier": { "type": "object", "additionalProperties": false, "description": "Uniquely identifies a single setting entry by its namespace and key.\nUsed to reference settings in page definitions and for granular updates.\nThe combination of namespace + key must be unique within a configuration scope.", "properties": { "namespace": { "type": "string", "description": "The namespace containing this setting.\nMust match a namespace from a registered SettingsNamespace." }, "key": { "type": "string", "description": "The key of the setting within its namespace.\nMust match a key from a SettingsEntry in the corresponding namespace." } }, "required": [] }, "soulfire.v1.SettingsPageEntryScopeType": { "type": "string", "description": "The scope/level at which a setting applies.\nDetermines where the setting value is stored and when it takes effect.\nUsed in SettingsDefinition to indicate the setting's configuration scope.", "enum": ["SERVER", "INSTANCE", "BOT"] }, "soulfire.v1.StringSetting": { "type": "object", "additionalProperties": false, "description": "UI definition for a string/text setting.\nUsed to render text input fields in the client UI with appropriate validation\nand visual styling based on the input type.", "properties": { "ui_name": { "type": "string", "description": "The display name shown in the UI label for this setting." }, "description": { "type": "string", "description": "A longer description explaining what this setting does.\nTypically shown as a tooltip or help text." }, "def": { "type": "string", "description": "The default value used when no value is configured." }, "input_type": { "description": "The type of input field to render (affects keyboard, validation, and display).", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.StringSetting.InputType" } ] }, "placeholder": { "type": "string", "description": "Placeholder text shown when the input is empty.\nProvides a hint about expected format or content." }, "min_length": { "type": "integer", "format": "int32", "description": "Minimum required string length (0 means no minimum)." }, "max_length": { "type": "integer", "format": "int32", "description": "Maximum allowed string length (0 means no maximum)." }, "pattern": { "type": "string", "description": "Regular expression pattern for value validation.\nEmpty string means no pattern validation." }, "disabled": { "type": "boolean", "description": "Whether this setting is disabled (read-only) in the UI.\nDisabled settings display their value but cannot be modified." } }, "required": [] }, "soulfire.v1.IntSetting": { "type": "object", "additionalProperties": false, "description": "UI definition for an integer number setting.\nUsed to render numeric input fields with validation constraints.\nSupports range limits, step increments, and locale-aware formatting.", "properties": { "ui_name": { "type": "string", "description": "The display name shown in the UI label for this setting." }, "description": { "type": "string", "description": "A longer description explaining what this setting does." }, "def": { "type": "integer", "format": "int32", "description": "The default value used when no value is configured." }, "min": { "type": "integer", "format": "int32", "description": "The minimum allowed value (inclusive)." }, "max": { "type": "integer", "format": "int32", "description": "The maximum allowed value (inclusive)." }, "step": { "type": "integer", "format": "int32", "description": "The step increment for value adjustments (e.g., for spinbox controls).\nA value of 0 means any integer is valid within the min/max range." }, "placeholder": { "type": "string", "description": "Placeholder text shown when the input is empty." }, "thousand_separator": { "type": "boolean", "description": "Whether to display the number with thousand separators (e.g., 1,000,000).\nImproves readability for large numbers." }, "disabled": { "type": "boolean", "description": "Whether this setting is disabled (read-only) in the UI." } }, "required": [] }, "soulfire.v1.DoubleSetting": { "type": "object", "additionalProperties": false, "description": "UI definition for a floating-point number setting.\nUsed to render decimal number input fields with precision control.\nSupports range limits, step increments, and decimal formatting options.", "properties": { "ui_name": { "type": "string", "description": "The display name shown in the UI label for this setting." }, "description": { "type": "string", "description": "A longer description explaining what this setting does." }, "def": { "type": "number", "format": "double", "description": "The default value used when no value is configured." }, "min": { "type": "number", "format": "double", "description": "The minimum allowed value (inclusive)." }, "max": { "type": "number", "format": "double", "description": "The maximum allowed value (inclusive)." }, "step": { "type": "number", "format": "double", "description": "The step increment for value adjustments.\nA value of 0 means any decimal is valid within the min/max range." }, "placeholder": { "type": "string", "description": "Placeholder text shown when the input is empty." }, "thousand_separator": { "type": "boolean", "description": "Whether to display the integer part with thousand separators." }, "decimal_scale": { "type": "integer", "format": "int32", "description": "The number of decimal places to display/allow.\nUsed for formatting and input validation." }, "fixed_decimal_scale": { "type": "boolean", "description": "Whether to always show the exact number of decimal places specified by decimal_scale.\nIf true, trailing zeros are preserved (e.g., 1.50 instead of 1.5)." }, "disabled": { "type": "boolean", "description": "Whether this setting is disabled (read-only) in the UI." } }, "required": [] }, "soulfire.v1.BoolSetting": { "type": "object", "additionalProperties": false, "description": "UI definition for a boolean toggle setting.\nUsed to render checkbox or toggle switch controls in the UI.\nCommonly used for enabling/disabling features.", "properties": { "ui_name": { "type": "string", "description": "The display name shown in the UI label for this setting." }, "description": { "type": "string", "description": "A longer description explaining what this setting does." }, "def": { "type": "boolean", "description": "The default value used when no value is configured." }, "disabled": { "type": "boolean", "description": "Whether this setting is disabled (read-only) in the UI." } }, "required": [] }, "soulfire.v1.ComboSetting": { "type": "object", "additionalProperties": false, "description": "UI definition for a dropdown/select setting with predefined options.\nUsed to render combo boxes or dropdown menus where users select from a fixed list.\nEach option has an ID (stored value) and a display name (shown to user).", "properties": { "ui_name": { "type": "string", "description": "The display name shown in the UI label for this setting." }, "description": { "type": "string", "description": "A longer description explaining what this setting does." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.ComboSetting.Option" }, "description": "The list of available options to choose from.\nThe order determines display order in the dropdown." }, "def": { "type": "string", "description": "The default option ID used when no value is configured.\nMust match one of the option IDs in the options list." }, "disabled": { "type": "boolean", "description": "Whether this setting is disabled (read-only) in the UI." } }, "required": [] }, "soulfire.v1.StringListSetting": { "type": "object", "additionalProperties": false, "description": "UI definition for a list of strings setting.\nUsed to render a multi-value input where users can add/remove string items.\nCommonly used for lists of allowed values, server addresses, or tags.", "properties": { "ui_name": { "type": "string", "description": "The display name shown in the UI label for this setting." }, "description": { "type": "string", "description": "A longer description explaining what this setting does." }, "def": { "type": "array", "items": { "type": "string" }, "description": "The default list of values used when no value is configured.\nCan be empty for an initially empty list." }, "disabled": { "type": "boolean", "description": "Whether this setting is disabled (read-only) in the UI." } }, "required": [] }, "soulfire.v1.MinMaxSetting": { "type": "object", "additionalProperties": false, "description": "UI definition for a min/max range setting with two integer values.\nUsed to render paired input fields for specifying a numeric range.\nCommonly used for delay ranges, count ranges, or any min/max pair.\nValues are stored as a JSON object with \"min\" and \"max\" properties.", "properties": { "min": { "type": "integer", "format": "int32", "description": "The minimum allowed value for both entries (inclusive).\nBoth min and max entries must be >= this value." }, "max": { "type": "integer", "format": "int32", "description": "The maximum allowed value for both entries (inclusive).\nBoth min and max entries must be <= this value." }, "step": { "type": "integer", "format": "int32", "description": "The step increment for value adjustments." }, "thousand_separator": { "type": "boolean", "description": "Whether to display numbers with thousand separators." }, "minEntry": { "description": "Configuration for the minimum value input field.\nThe actual value must be <= maxEntry value.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.MinMaxSetting.Entry" } ] }, "maxEntry": { "description": "Configuration for the maximum value input field.\nThe actual value must be >= minEntry value.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.MinMaxSetting.Entry" } ] }, "disabled": { "type": "boolean", "description": "Whether this setting is disabled (read-only) in the UI." } }, "required": [] }, "soulfire.v1.DialogPlainMessage": { "type": "object", "additionalProperties": false, "description": "Plain text message in a dialog body.", "properties": { "contents": { "type": "string", "description": "Text content, typically a JSON text component string.\nMay contain formatting, colors, click events, etc." }, "width": { "type": "integer", "format": "int32", "description": "Display width in pixels.\nRange: 1-1024, default: 200." } }, "required": [] }, "soulfire.v1.DialogItem": { "type": "object", "additionalProperties": false, "description": "Item display element in a dialog body.", "properties": { "item_id": { "type": "string", "description": "Minecraft item identifier.\nExample: \"minecraft:diamond\", \"minecraft:netherite_sword\"" }, "count": { "type": "integer", "format": "int32", "description": "Item count/stack size to display." }, "description": { "type": "string", "description": "Optional description text below the item." }, "show_decoration": { "type": "boolean", "description": "Whether to show the item frame decoration around the item.\nDefault: true." }, "show_tooltip": { "type": "boolean", "description": "Whether to show the item tooltip on hover.\nDefault: true." }, "width": { "type": "integer", "format": "int32", "description": "Display width in pixels.\nRange: 1-256, default: 16." }, "height": { "type": "integer", "format": "int32", "description": "Display height in pixels.\nRange: 1-256, default: 16." } }, "required": [] }, "soulfire.v1.DialogTextInput": { "type": "object", "additionalProperties": false, "description": "Text input field in a dialog.", "properties": { "key": { "type": "string", "description": "Identifier used when submitting the dialog." }, "label": { "type": "string", "description": "Display label for the field." }, "width": { "type": "integer", "format": "int32", "description": "Display width in pixels.\nRange: 1-1024, default: 200." }, "label_visible": { "type": "boolean", "description": "Whether to show the label.\nDefault: true." }, "initial": { "type": "string", "description": "Initial/default value." }, "max_length": { "type": "integer", "format": "int32", "description": "Maximum character length.\nDefault: 32." }, "multiline": { "type": "boolean", "description": "Whether to allow multi-line input." }, "multiline_max_lines": { "type": "integer", "format": "int32", "description": "Maximum lines for multiline input." }, "multiline_height": { "type": "integer", "format": "int32", "description": "Display height for multiline input in pixels." } }, "required": [] }, "soulfire.v1.DialogBooleanInput": { "type": "object", "additionalProperties": false, "description": "Boolean checkbox input in a dialog.", "properties": { "key": { "type": "string", "description": "Identifier used when submitting the dialog." }, "label": { "type": "string", "description": "Display label for the checkbox." }, "initial": { "type": "boolean", "description": "Initial checked state.\nDefault: false." }, "on_true": { "type": "string", "description": "String value to submit when checked.\nDefault: \"true\"." }, "on_false": { "type": "string", "description": "String value to submit when unchecked.\nDefault: \"false\"." } }, "required": [] }, "soulfire.v1.DialogSingleOptionInput": { "type": "object", "additionalProperties": false, "description": "Single option selection input (dropdown/combo box) in a dialog.", "properties": { "key": { "type": "string", "description": "Identifier used when submitting the dialog." }, "label": { "type": "string", "description": "Display label for the dropdown." }, "label_visible": { "type": "boolean", "description": "Whether to show the label.\nDefault: true." }, "width": { "type": "integer", "format": "int32", "description": "Display width in pixels.\nRange: 1-1024, default: 200." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.DialogOption" }, "description": "Available options to choose from." }, "initial_option_id": { "type": "string", "description": "ID of the initially selected option." } }, "required": [] }, "soulfire.v1.DialogNumberRangeInput": { "type": "object", "additionalProperties": false, "description": "Number range slider input in a dialog.", "properties": { "key": { "type": "string", "description": "Identifier used when submitting the dialog." }, "label": { "type": "string", "description": "Display label for the slider." }, "label_format": { "type": "string", "description": "Translation key for formatting the label with the current value." }, "width": { "type": "integer", "format": "int32", "description": "Display width in pixels.\nRange: 1-1024, default: 200." }, "start": { "type": "number", "format": "double", "description": "Minimum value (left side of slider)." }, "end": { "type": "number", "format": "double", "description": "Maximum value (right side of slider)." }, "step": { "type": "number", "format": "double", "description": "Step size for discrete values.\nIf 0, continuous values are allowed." }, "initial": { "type": "number", "format": "double", "description": "Initial/default value." } }, "required": [] }, "soulfire.v1.DialogAction": { "type": "object", "additionalProperties": false, "description": "Action that can be triggered by a dialog button.", "properties": { "open_url": { "description": "Open a URL in the browser.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogOpenUrlAction" } ] }, "run_command": { "description": "Run a chat command.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogRunCommandAction" } ] }, "suggest_command": { "description": "Suggest a command (put in chat box without sending).", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogSuggestCommandAction" } ] }, "copy_to_clipboard": { "description": "Copy text to clipboard.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogCopyToClipboardAction" } ] }, "show_dialog": { "description": "Show another dialog.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogShowDialogAction" } ] }, "custom": { "description": "Custom server-defined action.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogCustomAction" } ] }, "dynamic_run_command": { "description": "Run a command with input placeholders.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogDynamicRunCommandAction" } ] }, "dynamic_custom": { "description": "Custom action with additional data.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.DialogDynamicCustomAction" } ] } }, "required": [] }, "soulfire.v1.SlotRegionType": { "type": "string", "description": "Describes how a region of slots should be rendered in the UI.\nDifferent region types have different visual treatments.", "enum": [ "SLOT_REGION_NORMAL", "SLOT_REGION_OUTPUT", "SLOT_REGION_DISPLAY", "SLOT_REGION_HOTBAR", "SLOT_REGION_ARMOR" ] }, "soulfire.v1.Position": { "type": "object", "additionalProperties": false, "description": "Represents the 2D position of a node in the visual script editor canvas.\nUsed for rendering the node graph and preserving user layout preferences.", "properties": { "x": { "type": "number", "format": "double", "description": "The horizontal position in canvas coordinates.\nPositive values extend to the right." }, "y": { "type": "number", "format": "double", "description": "The vertical position in canvas coordinates.\nPositive values extend downward." } }, "required": [] }, "google.protobuf.Value": { "type": "object", "additionalProperties": false, "description": "`Value` represents a dynamically typed value which can be either\nnull, a number, a string, a boolean, a recursive struct value, or a\nlist of values. A producer of value is expected to set one of these\nvariants. Absence of any variant indicates an error.\n\nThe JSON representation for `Value` is JSON value.", "properties": { "null_value": { "description": "Represents a null value.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.NullValue" } ] }, "number_value": { "type": "number", "format": "double", "description": "Represents a double value." }, "string_value": { "type": "string", "description": "Represents a string value." }, "bool_value": { "type": "boolean", "description": "Represents a boolean value." }, "struct_value": { "description": "Represents a structured value.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.Struct" } ] }, "list_value": { "description": "Represents a repeated `Value`.", "allOf": [ { "$ref": "#/components/schemas/google.protobuf.ListValue" } ] } }, "required": [] }, "soulfire.v1.EdgeType": { "type": "string", "description": "The type of connection between nodes in the visual script editor.\nDetermines how data and control flow between nodes.", "enum": ["EDGE_TYPE_EXECUTION", "EDGE_TYPE_DATA"] }, "soulfire.v1.TypeDescriptor": { "type": "object", "additionalProperties": false, "description": "A recursive type descriptor for generic/parameterized port types.\nSupports simple types (NUMBER, STRING), parameterized types (List, Map),\nand type variables (T, K, V) that are resolved based on connections.", "properties": { "simple": { "description": "A simple, non-parameterized type (e.g., NUMBER, STRING, BOT).", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.PortType" } ] }, "parameterized": { "description": "A parameterized type like List or Map.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.ParameterizedType" } ] }, "type_variable": { "type": "string", "description": "A type variable name (e.g., \"T\", \"K\", \"V\") that gets resolved from connections.\nType variables are scoped per node: each node instance has its own bindings." } }, "required": [] }, "soulfire.v1.ProxyProto": { "type": "object", "additionalProperties": false, "description": "Represents a network proxy configuration used for routing bot connections.\nProxies can be used to mask the origin of bot traffic or to distribute connections\nacross multiple IP addresses. Used in instance configuration and proxy checking services.", "properties": { "type": { "description": "The proxy protocol type. Determines how the connection is established.", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.ProxyProto.Type" } ] }, "address": { "type": "string", "description": "The proxy server address in \"host:port\" format (e.g., \"proxy.example.com:8080\").\nThe address must be resolvable and the port must be valid (1-65535)." }, "username": { "type": "string", "description": "Optional username for proxy authentication.\nRequired if the proxy server requires authentication.\nIf password is set, username must also be set." }, "password": { "type": "string", "description": "Optional password for proxy authentication.\nUsed with username for SOCKS5 or HTTP proxy authentication.\nNot supported for SOCKS4 proxies (will cause an error if set)." } }, "required": [] }, "soulfire.v1.InstancePermission": { "type": "string", "description": "Permissions that apply to a specific instance.\nThese permissions are scoped to individual instances and control what operations\na user can perform on that instance. Checked via PermissionContext.instance() method.\nPermission grants are stored per-user per-instance in the database.", "enum": [ "INSTANCE_COMMAND_EXECUTION", "READ_INSTANCE", "UPDATE_INSTANCE_META", "UPDATE_INSTANCE_CONFIG", "DELETE_INSTANCE", "CHANGE_INSTANCE_STATE", "AUTHENTICATE_MC_ACCOUNT", "CHECK_PROXY", "DOWNLOAD_URL", "ACCESS_OBJECT_STORAGE", "INSTANCE_SUBSCRIBE_LOGS", "READ_INSTANCE_AUDIT_LOGS", "READ_BOT_INFO", "UPDATE_BOT_CONFIG" ] }, "google.protobuf.Struct": { "type": "object", "additionalProperties": false, "description": "`Struct` represents a structured data value, consisting of fields\nwhich map to dynamically typed values. In some languages, `Struct`\nmight be supported by a native representation. For example, in\nscripting languages like JS a struct is represented as an\nobject. The details of that representation are described together\nwith the proto support for the language.\n\nThe JSON representation for `Struct` is JSON object.", "properties": { "fields": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/google.protobuf.Value" }, "description": "Unordered map of dynamically typed values." } }, "required": [] }, "soulfire.v1.StringSetting.InputType": { "type": "string", "description": "The type of text input to render in the UI.\nMaps to HTML input types for appropriate keyboard and validation behavior.", "enum": [ "TEXT", "PASSWORD", "EMAIL", "SEARCH", "TEL", "URL", "TEXTAREA" ] }, "soulfire.v1.ComboSetting.Option": { "type": "object", "additionalProperties": false, "description": "A single selectable option in the combo box.", "properties": { "id": { "type": "string", "description": "The internal identifier for this option.\nThis value is stored in the configuration when selected.\nTypically a machine-readable string (e.g., enum name, UUID)." }, "display_name": { "type": "string", "description": "The human-readable name displayed to the user.\nCan include spaces and special characters for readability." }, "icon_id": { "type": "string", "description": "Optional icon identifier to display next to the option.\nUses lucide.dev icon IDs (e.g., \"user\", \"settings\", \"shield\")." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Additional keywords for filtering/searching options.\nAllows finding this option by typing related terms." } }, "required": [] }, "soulfire.v1.MinMaxSetting.Entry": { "type": "object", "additionalProperties": false, "description": "Configuration for a single entry in the min/max pair.", "properties": { "ui_name": { "type": "string", "description": "The display name for this entry (e.g., \"Minimum Delay\")." }, "description": { "type": "string", "description": "A description explaining what this entry represents." }, "def": { "type": "integer", "format": "int32", "description": "The default value for this entry." }, "placeholder": { "type": "string", "description": "Placeholder text shown when the input is empty." } }, "required": [] }, "soulfire.v1.DialogOption": { "type": "object", "additionalProperties": false, "description": "An option in a single-option input.", "properties": { "id": { "type": "string", "description": "Option identifier (submitted value)." }, "display": { "type": "string", "description": "Display text for the option.\nIf empty, the id is used for display." } }, "required": [] }, "soulfire.v1.DialogOpenUrlAction": { "type": "object", "additionalProperties": false, "description": "Action to open a URL in the user's browser.", "properties": { "url": { "type": "string", "description": "The URL to open." } }, "required": [] }, "soulfire.v1.DialogRunCommandAction": { "type": "object", "additionalProperties": false, "description": "Action to execute a chat command.", "properties": { "command": { "type": "string", "description": "The command to run (including the leading /)." } }, "required": [] }, "soulfire.v1.DialogSuggestCommandAction": { "type": "object", "additionalProperties": false, "description": "Action to suggest a command (place in chat input).", "properties": { "command": { "type": "string", "description": "The command to suggest." } }, "required": [] }, "soulfire.v1.DialogCopyToClipboardAction": { "type": "object", "additionalProperties": false, "description": "Action to copy text to the clipboard.", "properties": { "value": { "type": "string", "description": "The text to copy." } }, "required": [] }, "soulfire.v1.DialogShowDialogAction": { "type": "object", "additionalProperties": false, "description": "Action to display another dialog.", "properties": { "dialog_id": { "type": "string", "description": "Dialog ID to show (references a registered dialog)." } }, "required": [] }, "soulfire.v1.DialogCustomAction": { "type": "object", "additionalProperties": false, "description": "Custom server-defined action.", "properties": { "id": { "type": "string", "description": "Action identifier known to the server." }, "payload": { "type": "string", "description": "Optional JSON payload for the action." } }, "required": [] }, "soulfire.v1.DialogDynamicRunCommandAction": { "type": "object", "additionalProperties": false, "description": "Dynamic command action with input value substitution.", "properties": { "template": { "type": "string", "description": "Command template with placeholders for input values.\nPlaceholders are replaced with user input before execution." } }, "required": [] }, "soulfire.v1.DialogDynamicCustomAction": { "type": "object", "additionalProperties": false, "description": "Dynamic custom action with additional NBT data.", "properties": { "id": { "type": "string", "description": "Custom action identifier." }, "additions": { "type": "string", "description": "Additional NBT data as JSON string." } }, "required": [] }, "google.protobuf.NullValue": { "type": "string", "description": "`NullValue` is a singleton enumeration to represent the null value for the\n`Value` type union.\n\nThe JSON representation for `NullValue` is JSON `null`.", "enum": ["NULL_VALUE"] }, "google.protobuf.ListValue": { "type": "object", "additionalProperties": false, "description": "`ListValue` is a wrapper around a repeated field of values.\n\nThe JSON representation for `ListValue` is JSON array.", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/google.protobuf.Value" }, "description": "Repeated field of dynamically typed values." } }, "required": [] }, "soulfire.v1.ParameterizedType": { "type": "object", "additionalProperties": false, "description": "A parameterized type with a base type and type arguments.\nFor example, List has base=LIST and params=[Simple(BOT)].", "properties": { "base": { "description": "The container type (e.g., LIST, MAP).", "allOf": [ { "$ref": "#/components/schemas/soulfire.v1.PortType" } ] }, "params": { "type": "array", "items": { "$ref": "#/components/schemas/soulfire.v1.TypeDescriptor" }, "description": "The type arguments (e.g., [BOT] for List, [STRING, NUMBER] for Map)." } }, "required": [] }, "soulfire.v1.ProxyProto.Type": { "type": "string", "description": "The type of proxy protocol to use for the connection.", "enum": ["HTTP", "SOCKS4", "SOCKS5"] } } }, "security": [ { "bearerAuth": [] }, { "basicTokenAuth": [] } ], "externalDocs": { "description": "Interactive Armeria DocService", "url": "http://127.0.0.1:38765/docs" }, "x-soulfire": { "httpJsonTranscodingEnabled": true, "unframedJsonEnabled": true, "openApiDocument": "http://127.0.0.1:38765/openapi.json", "docService": "http://127.0.0.1:38765/docs", "mcp": "http://127.0.0.1:38765/mcp", "limitations": [ "Only unary RPC methods are included.", "Streaming RPCs stay gRPC-only and are intentionally excluded.", "Operations describe the JSON HTTP surface, not framed gRPC semantics." ], "authorization": { "publicService": "soulfire.v1.LoginService", "bearerHeader": "Authorization: Bearer ", "basicHeader": "Authorization: Basic " } } }