{"openapi":"3.1.1","info":{"title":"Customer API documentation","version":"1.0.0","description":"Access requires all three: an API-enabled server type, access to the server, and the matching key permission. Free Servers have customer API access disabled. Disabled servers are omitted from lists and direct requests return HTTP 403 with api_disabled. Existing keys do not bypass a later plan restriction. Browser sessions are separate from customer API keys."},"servers":[{"url":"https://hosting.marvinmc.net/api/client/v1"}],"security":[{"customerKey":[]}],"components":{"securitySchemes":{"customerKey":{"type":"http","scheme":"bearer","description":"Create a key under Security > API keys, select servers and permissions, and authenticate with Authorization: Bearer <key>. Use HTTPS. Keys start with mmc_ and are shown only once. Never put keys in URLs, public JavaScript or repositories."}}},"paths":{"/servers":{"get":{"operationId":"servers","summary":"List servers","description":"Returns servers with id and name. Only selected, accessible, API-enabled servers are included.","x-required-scope":null,"parameters":[],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or operation failed. Read the error field.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Server type, account permissions, key scope or CAPTCHA policy denies access.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"The API endpoint is unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"Another operation is active for this server.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit reached. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":60}}}}}}},"/servers/{id}/stats":{"get":{"operationId":"stats","summary":"Read server statistics","description":"Returns current state and node statistics. Available metrics depend on the runtime.","x-required-scope":"server.read","parameters":[{"name":"id","in":"path","required":true,"description":"Your server ID as a string, not a JavaScript number.","schema":{"type":"string"}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or operation failed. Read the error field.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Server type, account permissions, key scope or CAPTCHA policy denies access.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"The API endpoint is unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"Another operation is active for this server.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit reached. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":60}}}}}}},"/servers/{id}/console":{"get":{"operationId":"console","summary":"Read console output","description":"Returns logs, log_cursor, log_mode and log_reset with live state and statistics. The initial snapshot is bounded to the latest 500 lines / 256 KiB; later requests can fetch only new lines. An offline server has no active console output.","x-required-scope":"console.read","parameters":[{"name":"id","in":"path","required":true,"description":"Your server ID as a string, not a JavaScript number.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque log_cursor from the previous response. Omit for the initial snapshot. Append logs only when log_mode is delta and log_reset is false.","schema":{"type":"string"}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or operation failed. Read the error field.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Server type, account permissions, key scope or CAPTCHA policy denies access.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"The API endpoint is unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"Another operation is active for this server.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit reached. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":60}}}}}}},"/servers/{id}/command":{"post":{"operationId":"command","summary":"Send a console command","description":"Sends a command to the actual server console. /say hi becomes say hi; //say hi becomes /say hi. Requires a running compatible server.","x-required-scope":"console.write","parameters":[{"name":"id","in":"path","required":true,"description":"Your server ID as a string, not a JavaScript number.","schema":{"type":"string"}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or operation failed. Read the error field.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Server type, account permissions, key scope or CAPTCHA policy denies access.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"The API endpoint is unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"Another operation is active for this server.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit reached. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":60}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"command":{"type":"string","description":"Console command. One leading slash is removed; embedded slashes are kept."}},"required":["command"]},"example":{"command":"say hi"}}}}}},"/servers/{id}/power":{"post":{"operationId":"power","summary":"Change power state","description":"Queues start, stop, restart or kill. Kill terminates immediately. CAPTCHA-required actions must be performed in the web panel.","x-required-scope":"power","parameters":[{"name":"id","in":"path","required":true,"description":"Your server ID as a string, not a JavaScript number.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"For a new power or backup action, send a unique Idempotency-Key (up to 200 characters). Reuse it only when retrying that exact action. Retries return the original job instead of executing twice. Retained for the job retention period (90 days for completed jobs).","schema":{"type":"string","maxLength":200}}],"responses":{"202":{"description":"Job accepted; execution is pending.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or operation failed. Read the error field.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Server type, account permissions, key scope or CAPTCHA policy denies access.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"The API endpoint is unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"Another operation is active for this server.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit reached. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":60}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","description":"One of start, stop, restart or kill. Start/restart still require an unexpired server.","enum":["start","stop","restart","kill"]}},"required":["action"]},"example":{"action":"restart"}}}}}},"/servers/{id}/files":{"get":{"operationId":"files","summary":"List a directory","description":"Lists files and directories below path. Defaults to /server; does not recursively list contents.","x-required-scope":"files.read","parameters":[{"name":"id","in":"path","required":true,"description":"Your server ID as a string, not a JavaScript number.","schema":{"type":"string"}},{"name":"path","in":"query","required":false,"description":"Path relative to the server file root, for example /server/server.properties or /backups. URL-encode query values.","schema":{"type":"string","default":"/server"}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or operation failed. Read the error field.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Server type, account permissions, key scope or CAPTCHA policy denies access.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"The API endpoint is unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"Another operation is active for this server.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit reached. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":60}}}}}}},"/servers/{id}/file":{"get":{"operationId":"file_read","summary":"Read a text file","description":"Returns a text file for editing, not a binary download. Existing editor size limits and file permissions apply.","x-required-scope":"files.read","parameters":[{"name":"id","in":"path","required":true,"description":"Your server ID as a string, not a JavaScript number.","schema":{"type":"string"}},{"name":"path","in":"query","required":true,"description":"Path relative to the server file root, for example /server/server.properties or /backups. URL-encode query values.","schema":{"type":"string"}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or operation failed. Read the error field.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Server type, account permissions, key scope or CAPTCHA policy denies access.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"The API endpoint is unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"Another operation is active for this server.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit reached. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":60}}}}}},"put":{"operationId":"file_write","summary":"Save a text file","description":"Writes content to path. Existing file, storage and server-operation restrictions apply. This is not a binary upload endpoint.","x-required-scope":"files.write","parameters":[{"name":"id","in":"path","required":true,"description":"Your server ID as a string, not a JavaScript number.","schema":{"type":"string"}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or operation failed. Read the error field.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Server type, account permissions, key scope or CAPTCHA policy denies access.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"The API endpoint is unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"Another operation is active for this server.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit reached. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":60}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","description":"Path relative to the server file root, for example /server/server.properties or /backups. URL-encode query values."},"content":{"type":"string","description":"Full text content to save, including line breaks."}},"required":["path","content"]},"example":{"path":"/server/example.txt","content":"example"}}}}}},"/servers/{id}/search":{"get":{"operationId":"search","summary":"Search files recursively","description":"Returns entries with path, directory and, for text matches, line and snippet. Append each page and follow next_cursor until null. An empty page does not end the search if next_cursor is present. total_scanned reports progress; skipped indicates unreadable folders/files or the depth limit. limited indicates unfinished or incomplete results. Per-request limits: 100 results, 20,000 traversal steps, 2.5 seconds, 16 MiB text. Text files up to 512 KiB, maximum depth 24, no symlink traversal. Deduplicate by path if files change during the search. API rate limits apply to each page.","x-required-scope":"files.read","parameters":[{"name":"id","in":"path","required":true,"description":"Your server ID as a string, not a JavaScript number.","schema":{"type":"string"}},{"name":"path","in":"query","required":false,"description":"Path relative to the server file root, for example /server/server.properties or /backups. URL-encode query values.","schema":{"type":"string","default":"/server"}},{"name":"query","in":"query","required":true,"description":"Search term, 2 to 100 characters.","schema":{"type":"string","minLength":2,"maxLength":100}},{"name":"content","in":"query","required":false,"description":"0 searches names only; 1 also searches bounded text contents.","schema":{"type":"string","enum":["0","1"],"default":"0"}},{"name":"cursor","in":"query","required":false,"description":"Unchanged next_cursor from the previous search response. Keep path, query and content unchanged. Expires after 30 minutes. Omit to start a new search.","schema":{"type":"string","maxLength":7500}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or operation failed. Read the error field.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Server type, account permissions, key scope or CAPTCHA policy denies access.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"The API endpoint is unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"Another operation is active for this server.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit reached. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":60}}}}}}},"/servers/{id}/backups":{"get":{"operationId":"backups","summary":"List backups","description":"Returns existing backups and backup storage information, subject to the server permissions.","x-required-scope":"backups.read","parameters":[{"name":"id","in":"path","required":true,"description":"Your server ID as a string, not a JavaScript number.","schema":{"type":"string"}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or operation failed. Read the error field.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Server type, account permissions, key scope or CAPTCHA policy denies access.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"The API endpoint is unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"Another operation is active for this server.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit reached. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":60}}}}}},"post":{"operationId":"backup_create","summary":"Create a backup","description":"Queues a tar.gz backup with an automatic timestamp name. A running server requires confirm_stop=true and the power scope. It stops for the backup and restarts after success if still active. Without confirmation, only offline backups are permitted. The backup quota still applies.","x-required-scope":"backups.create","parameters":[{"name":"id","in":"path","required":true,"description":"Your server ID as a string, not a JavaScript number.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"For a new power or backup action, send a unique Idempotency-Key (up to 200 characters). Reuse it only when retrying that exact action. Retries return the original job instead of executing twice. Retained for the job retention period (90 days for completed jobs).","schema":{"type":"string","maxLength":200}}],"responses":{"202":{"description":"Job accepted; execution is pending.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or operation failed. Read the error field.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Server type, account permissions, key scope or CAPTCHA policy denies access.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"The API endpoint is unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"Another operation is active for this server.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit reached. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":60}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm_stop":{"type":"boolean","description":"Optional boolean, default false. Authorizes stopping and restarting a running server for this operation. Requires the power scope and start/stop permission, rechecked when the job runs."}}},"example":{"confirm_stop":true}}}}}},"/jobs/{id}":{"get":{"operationId":"job","summary":"Read a job","description":"Returns job status, phases, timestamps and any error/reference. Only the creating API key may read it, and its current server type, scope and server access must still permit it.","x-required-scope":"same_key_as_job_submission","parameters":[{"name":"id","in":"path","required":true,"description":"Job ID returned when creating the job, as a string.","schema":{"type":"string"}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or operation failed. Read the error field.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Server type, account permissions, key scope or CAPTCHA policy denies access.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"The API endpoint is unknown.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"Another operation is active for this server.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit reached. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":60}}}}}}}},"externalDocs":{"url":"https://hosting.marvinmc.net/api/docs","description":"Customer API documentation"}}