Customer API v1. Select an action to see its inputs and responses. Writes made with a browser session require X-CSRF-Token.
- Account
- Connected assistants
- Account security
- Members
- Notifications
- MobileNotificationEndpoints
- Sign-in
- Client errors
- Public analytics
- Feedback
- Public support
- Support
- Servers
- Workspaces
- Alerts
- Integration keys
- Audit
- Server backups
- Players
- Bulk plans
- Plugins
- Dashboard
- Discord link
- Discord
- Hosts
- Evidence
- Performance
- Schedules
- Server software
- Workspace bans
- Server adoption and removal
- Server capabilities
- Integrations
- Maps
- Nexus networks
- Operations
- Rented servers
- Reports
- Rules
- Server groups
- Shell
- Server lifecycle
- Commands and broadcasts
- World
- Worlds
- Server files
- Server configuration
- Console
- Message templates
- Mod commands
- Plugin library
- Quick actions
- Release channels
- Temporary changes
- Settings profiles
- Temporary access
Account
Read your own alertsGET /api/v1/account/alerts
getAccountAlerts
The alerts you switched on for your own account, for example a new sign-in. They are yours alone: no workspace setting or template changes them, and they go only to your own browsers. All off until you save them.
Success: 200 AccountAlertsResponse. Errors use Problem.
Response statuses: 200, 401, default.
Save your own alertsPUT /api/v1/account/alerts
setAccountAlerts
Saves the whole set. With new sign-in on, each sign-in to your account tells your browsers that have alerts turned on, with the browser or app, the system and an approximate country. It never names an address.
Request body AccountAlertsRequest
newSignIn(boolean, required)
Success: 200 AccountAlertsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 422, default.
Download a completed data request exportGET /api/v1/account/data-requests/{requestId}/exports/{artifactId}
downloadPrivacyExport
- requestId (path, required)
- See the downloadable contract for the field schema.
- artifactId (path, required)
- See the downloadable contract for the field schema.
Success: 200. Errors use Problem.
Response statuses: 200, 401, 404, 503, default.
Read the expiry of a completed data request exportGET /api/v1/account/data-requests/{requestId}/exports/{artifactId}/status
getPrivacyExportStatus
- requestId (path, required)
- See the downloadable contract for the field schema.
- artifactId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PrivacyExportStatus. Errors use Problem.
Response statuses: 200, 401, 404, 503, default.
Keep my accountDELETE /api/v1/account/deletion
cancelAccountDeletion
Cancels a scheduled or waiting deletion and reopens the workspaces that this deletion closed. Workspaces the account left stay left. Cancelling when nothing is scheduled succeeds and changes nothing.
Success: 200 AccountDeletionResponse. Errors use Problem.
Response statuses: 200, 401, 409, default.
Read what deleting my account would doGET /api/v1/account/deletion
getAccountDeletion
Whether a deletion is scheduled and when, and for each workspace the account belongs to what happens to it: it closes (the account is its only member), the account leaves it, it is already closing, or it blocks the deletion (the account is the last owner of a workspace with other members).
Success: 200 AccountDeletionResponse. Errors use Problem.
Response statuses: 200, 401, default.
Delete my accountPOST /api/v1/account/deletion
requestAccountDeletion
Closes the workspaces the account is the only member of, leaves the others, ends the account's other sessions and schedules the account to be erased after the window of 30 days. Until then the person can sign in, download a copy and keep the account. Without cancelPlan the request is refused with 409 plan_active, and nothing changed. Refused with 409 last_owner, and nothing changed, while the account is the last owner of a workspace with other members. Repeating it is safe.
- cancelPlan (query)
- See the downloadable contract for the field schema.
Success: 200 AccountDeletionResponse. Errors use Problem.
Response statuses: 200, 401, 409, 503, default.
Download a copy of my dataGET /api/v1/account/export
exportAccount
A JSON file with the account and, for each workspace the account owns, the workspace's settings, members, servers, configuration, schedules and audit trail. Nothing secret is included.
Success: 200. Errors use Problem.
Response statuses: 200, 401, default.
Unlink a Discord, Google or Apple accountDELETE /api/v1/account/logins/{provider}
removeLogin
Removes the link at once and signs out the other browsers that signed in with it. The account is emailed. 422 with the reason last_way_in when it is the account's only way in. The provider word is google, discord or apple.
- provider (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 422, default.
Read whether you get product updates by emailGET /api/v1/account/marketing
getMarketingPreference
True for an account that signed up with the sign-up step (it is on by default and the step says so) and has not turned it off; false for an account that never had a choice recorded.
Success: 200 MarketingPreferenceResponse. Errors use Problem.
Response statuses: 200, 401, default.
Turn product updates by email on or offPUT /api/v1/account/marketing
setMarketingPreference
Takes effect at once and answers with the choice as it now reads. Sending the value it already has changes nothing. The time and the source (profile) are kept for audit.
Request body SetMarketingPreferenceBody
optedIn(boolean, required): True to get product updates and news by email, false to stop them.
Success: 200 MarketingPreferenceResponse. Errors use Problem.
Response statuses: 200, 401, 403, 422, default.
Turn the passkey offer off or onPUT /api/v1/account/passkey-offer
setPasskeyOffer
Sets whether the offer to add a passkey after signing in is shown to this account, on every device. It changes nothing about how the account signs in. Sending the same value again is fine.
Request body PasskeyOfferRequest
off(boolean, required): True for "Don't remind me again", false to offer it again.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, default.
Add a passkeyPOST /api/v1/account/passkeys
addPasskey
Checks the browser's answer to the creation options and keeps the public key. 201 with the passkey. 422 with passkey_limit when the account has the most it keeps, passkey_exists when this authenticator is already added, passkey_failed when the answer did not verify.
Request body PasskeyAddRequest
challengeId(string, required)credential(JsonElement, required): The result of `navigator.credentials.create` as JSON (`credential.toJSON()`).name(string): A name the person recognises, such as "Phone".
Success: 201 PasskeyResponse. Errors use Problem.
Response statuses: 201, 401, 403, 422, default.
Get the options for adding a passkeyPOST /api/v1/account/passkeys/options
startAddPasskey
Needs a session. The options exclude the passkeys the account already has. Send the browser's answer to the add passkey route.
Success: 200 PasskeyOptionsResponse. Errors use Problem.
Response statuses: 200, 401, 403, default.
Remove a passkeyDELETE /api/v1/account/passkeys/{passkeyId}
removePasskey
Removes it at once. When it was the last passkey, the other browsers that signed in with a passkey are signed out. The account is emailed. 422 with the reason last_way_in when it is the account's only way in.
- passkeyId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 422, default.
Rename a passkeyPATCH /api/v1/account/passkeys/{passkeyId}
renamePasskey
Changes the name shown in the list. Nothing else about the passkey changes.
- passkeyId (path, required)
- See the downloadable contract for the field schema.
Request body PasskeyRenameRequest
name(string, required)
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 422, default.
List your recent sign-in activityGET /api/v1/account/security-events
listAccountActivity
The last 20 security events of your own account, newest first: sign-ins (and failed ones), sign-outs, sessions ended, methods and passkeys added or removed, and a deletion asked for or cancelled, each with the browser, system, a shortened address and an approximate country when the request said them. The User-Agent text and the full address are never returned. Events are kept for the audit period and stay for it after an account is deleted.
Success: 200 AccountActivityResponse. Errors use Problem.
Response statuses: 200, 401, default.
Sign out everywhereDELETE /api/v1/account/sessions
endAllBrowserSessions
Ends every browser and app session of the account, this one included, and clears the cookie. Signing in again works as usual. Repeating it is safe.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, default.
List where you are signed inGET /api/v1/account/sessions
listBrowserSessions
The browsers and the phone and tablet apps of your account that still work, newest first, with how each signed in, when, when it was last used, and what it said about itself (browser or app, system, device, a shortened address and an approximate country). The one making this request is marked current. The apps' own list under device sessions is unchanged.
Success: 200 BrowserSessionsResponse. Errors use Problem.
Response statuses: 200, 401, default.
Sign out one browser or appDELETE /api/v1/account/sessions/{sessionId}
endBrowserSession
Ends that browser (ses_) or app (dvs_) session at once; its next request is signed out. A session of another account answers not found. Ending the current browser is the same as signing out.
- sessionId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, default.
List how the account signs inGET /api/v1/account/sign-in-methods
getSignInMethods
The linked Google and Discord accounts, the passkeys and the providers that can still be linked. There is no emailed code to fall back on, so the last way in cannot be removed.
Success: 200 SignInMethodsResponse. Errors use Problem.
Response statuses: 200, 401, default.
Unsubscribe from product updates with the link in an emailPOST /api/v1/marketing/unsubscribe
unsubscribeMarketing
Needs no sign-in: the link's own t value in the email names the account. Turns product updates off and answers unsubscribed, or already_unsubscribed when they were off (repeating the link is safe and records nothing). A damaged link answers 422 link_invalid; an old link answers 422 link_expired, and the choice is then changed on Your account. This is also the target of the List-Unsubscribe-Post one-click header (RFC 8058): any form body is ignored.
- t (query)
- See the downloadable contract for the field schema.
Success: 200 UnsubscribeResponse. Errors use Problem.
Response statuses: 200, 422, default.
Connected assistants
Read an assistant's sign-in requestGET /api/v1/account/assistant-consent
getAssistantConsent
For the page that asks you to let an assistant in: who the assistant is, the address it asks to be sent back to, whether it asks to change things, and the workspaces you can connect it to with the connection each already has. returnTo (required) is the sign-in request the assistant started, as the consent page was given it: a path that starts with /connect/authorize. Only your own session reads it.
- returnTo (query)
- See the downloadable contract for the field schema.
Success: 200 AssistantConsentResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Let an assistant inPOST /api/v1/account/assistant-consent
assistantConsent
Connects the assistant to the workspace you chose as a Viewer, or keeps the connection you already have with it as it is, and answers where to send the browser so the sign-in goes on. A new assistant looks and changes nothing until you raise its role in Connected assistants (setAssistantRole); signing in again never raises it. allServers and serverIds say which servers it can see: sent, they set them; left out, a new assistant sees no server and one you already let in keeps its servers. Only your own session consents.
Request body AssistantConsentBody
allServers(boolean): True to let the assistant see every server, those added later too.returnTo(string, required): The sign-in request the assistant started, as the page was given it (`returnTo`).serverIds(list of string): The servers the assistant can see when `allServers` is not true.workspaceId(string, required): The workspace to connect the assistant to.
Success: 200 AssistantConsentAnswer. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List what assistants ask you to approveGET /api/v1/workspaces/{workspaceId}/assistant-approvals
listAssistantApprovals
The risky actions your assistants asked for, newest first: what will happen, and whether it is waiting, approved, declined, used or expired. Only the person the assistant acts for sees them.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 AssistantApprovalListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read one assistant approvalGET /api/v1/workspaces/{workspaceId}/assistant-approvals/{approvalId}
getAssistantApproval
What an assistant asked to do, in plain words, with the call's details. Only the person the assistant acts for reads it: anyone else gets not found.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- approvalId (path, required)
- See the downloadable contract for the field schema.
Success: 200 AssistantApprovalResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Approve or decline what an assistant askedPOST /api/v1/workspaces/{workspaceId}/assistant-approvals/{approvalId}/decision
decideAssistantApproval
approve lets the assistant do exactly what the page said, once, within a short time (15 minutes). decline ends the request. Deciding the same way again changes nothing; a request that expired or was already decided the other way answers 409 approval_closed. Only the person's own session decides: an assistant or a key never approves.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- approvalId (path, required)
- See the downloadable contract for the field schema.
Request body AssistantApprovalDecisionBody
decision(string, required): `approve` or `decline`.
Success: 200 AssistantApprovalResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List connected assistantsGET /api/v1/workspaces/{workspaceId}/assistant-connections
listAssistantConnections
The AI assistants signed in to this workspace, newest first: your own, or everyone's with apikeys.manage, with the name the assistant gave itself, whether RustSC proved where it comes from, its role and when it was last used. A disconnected assistant is not listed. Never a token.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 AssistantConnectionListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Disconnect an assistantDELETE /api/v1/workspaces/{workspaceId}/assistant-connections/{connectionId}
revokeAssistantConnection
The assistant stops working at its next request and has to be signed in again. Disconnecting a disconnected assistant changes nothing. Your own connection needs no permission; someone else's needs apikeys.manage. Only a person's own session disconnects an assistant.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Choose what an assistant asks firstPUT /api/v1/workspaces/{workspaceId}/assistant-connections/{connectionId}/ask-first
changeAssistantAskFirst
Switches an assistant's two questions on or off: risky actions (wipes, deleting, restoring, long ban lists, file writes, plugin install or removal) and free-form console commands. Both are on when an assistant connects and wait for your approval; switching one off lets that assistant do those things without asking, which is your choice and your risk. Your own assistant needs no permission; someone else's needs apikeys.manage. Only a person's own session changes it.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Request body AssistantAskFirstBody
askBeforeConsole(boolean, required): False to let this assistant run free-form console commands without asking.askBeforeRisky(boolean, required): False to let this assistant run wipes, deleting, restoring, long ban lists, file writes and plugin install or removal without asking.
Success: 200 AssistantConnectionResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Set an assistant's safety limitsPUT /api/v1/workspaces/{workspaceId}/assistant-connections/{connectionId}/limits
setAssistantLimits
You can raise each one, up to ten times its starting value (the wait: down to a tenth), and never remove one. The body is the whole set: a limit left out or sent as null goes back to its starting value. A value outside the range is 422 out_of_range. Changing a limit is recorded. Your own connection needs no permission; someone else's needs apikeys.manage. Only a person's own session sets limits: an assistant or a key cannot.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Request body AssistantLimitsBody
approvalsWaiting(integer)changesPerHour(integer)massBanPlayers(integer)pauseMinutes(integer)playerActionsPerHour(integer)serversPerPlan(integer)
Success: 200 AssistantLimitsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Pause an assistantPOST /api/v1/workspaces/{workspaceId}/assistant-connections/{connectionId}/pause
pauseAssistantConnection
Cuts off this assistant at its next request with assistants_paused, without disconnecting it. Your own connection needs no permission; someone else's needs apikeys.manage. Pausing again changes nothing.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Resume an assistantPOST /api/v1/workspaces/{workspaceId}/assistant-connections/{connectionId}/resume
resumeAssistantConnection
Ends this assistant's own pause. It stays paused while the whole workspace is paused. Your own connection needs no permission; someone else's needs apikeys.manage. Resuming when it is not paused changes nothing.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Set an assistant's rolePUT /api/v1/workspaces/{workspaceId}/assistant-connections/{connectionId}/role
setAssistantRole
Sets the role of an assistant you connected: viewer, moderator, operator or administrator, the same roles people have except Owner (422 invalid_role at /role; owner is 422 administrator_at_most at /role, because an assistant is never an Owner). A new assistant is a Viewer. You cannot give a role above your own (422 above_your_role at /role); lowering is always allowed. At every request the assistant holds only what its role and you both hold then, so lowering your own role lowers it at once. Only your own session sets a role: a key or an assistant never does, and someone else's assistant is 404 not_found.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Request body SetAssistantRoleBody
role(string, required): `viewer`, `moderator`, `operator`, `administrator` or `owner`.
Success: 200 AssistantConnectionResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Choose the servers an assistant can seePUT /api/v1/workspaces/{workspaceId}/assistant-connections/{connectionId}/servers
setAssistantServers
Sets which servers an assistant you connected can reach, as a whole: allServers true for every server (servers added later too), or serverIds for only those (a list does not include servers added later; an empty list is no server, which is what a new assistant starts with). A server that is not one of the workspace's is 422 not_found at /serverIds/n, a server twice is 422 duplicate_server. The assistant never holds more than you do, and calls, lists, searches and bulk plans reach only these servers. The audit trail records what the choice was and what it became. Only your own session sets it: a key or an assistant never does, and someone else's assistant is 404 not_found.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Request body SetAssistantServersBody
allServers(boolean): True for every server of the workspace, those added later too.serverIds(list of string): The servers when `allServers` is false.
Success: 200 AssistantConnectionResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Pause all assistantsPOST /api/v1/workspaces/{workspaceId}/assistants/pause
pauseAssistants
Cuts off every AI assistant of the workspace, agent keys included, at their next request: calls, agent-key API calls and token renewals are refused with assistants_paused. Work an assistant already started continues; nothing new is admitted. Nothing is disconnected, and a person resumes with resumeAssistants. Needs apikeys.manage. Only a person or a plain key pauses: an assistant never does. Pausing again changes nothing.
Workspace permission: apikeys.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Resume all assistantsPOST /api/v1/workspaces/{workspaceId}/assistants/resume
resumeAssistants
Ends the pause of the whole workspace. An assistant paused on its own stays paused until resumeAssistantConnection. Needs apikeys.manage. Resuming when nothing is paused changes nothing.
Workspace permission: apikeys.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Account security
Read your signed-in devicesGET /api/v1/account/device-sessions
listDeviceSessions
Reads active first-party native device sessions for your account. Uses limit and account-bound cursor paging. Workspace membership is not required.
- limit (query)
- Page size.
- cursor (query)
- Opaque position from the previous page, bound to your account.
Success: 200 DeviceSessionListResponse. Errors use Problem.
Response statuses: 200, 401, 422, 503, default.
Sign out a deviceDELETE /api/v1/account/device-sessions/{deviceSessionId}
revokeDeviceSession
Revokes your native device session and its authorization family. Repeating a successful revocation has no further effect. Another account's device answers not found.
- deviceSessionId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 503, default.
Members
Invitations waiting for youGET /api/v1/account/invitations
listWaitingInvitations
For the signed-in person: the invitations sent to their own email address that they can accept now, newest first, with the workspace and the access each gives. Empty when there are none. Never names an address or a link.
Success: 200 WaitingInvitationListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Accept a waiting invitationPOST /api/v1/account/invitations/accept
acceptWaitingInvitation
Makes the signed-in person a member with the access of an invitation listWaitingInvitations gave, by its workspace and ID. The same rules as accepting by the link. An invitation that is not yours answers 404, like one that does not exist; one that was withdrawn, ran out or was used since is a 409 no_longer_valid; a person who is a member already gets 409 already_member. Accepting an invitation this account already accepted answers the same success.
Request body AcceptWaitingInvitationBody
invitationId(string, required): Invitation ID.workspaceId(string, required): Workspace ID.
Success: 200 InvitationAcceptedResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Accept an invitationPOST /api/v1/invitations/accept
acceptInvitation
Makes the signed-in person a member with the invitation's access. The same rules as reading it, and a person who is a member already gets 409 already_member. Accepting an invitation this account already accepted answers the same success.
Request body InvitationLinkBody
token(string, required): The token of the link.workspaceId(string, required): Workspace ID.
Success: 200 InvitationAcceptedResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read an invitationPOST /api/v1/invitations/preview
previewInvitation
For the signed-in person who opened an invitation link: the workspace and the access it gives, so they can see what accepting does. The body is the link's workspace and token. The signed-in address must be the one invited (409 other_address); an expired, withdrawn or already accepted invitation is a 409 with that reason (expired, revoked, accepted). Anything else about the link answers 404.
Request body InvitationLinkBody
token(string, required): The token of the link.workspaceId(string, required): Workspace ID.
Success: 200 InvitationOfferResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read your chat nameGET /api/v1/workspaces/{workspaceId}/chat-name
getChatName
The name your chat messages from the Chat view go out under in this workspace (empty when you chose to send with no name), whether you chose it, and the name you get when you have not chosen one (your Discord display name, otherwise Staff). Needs only your membership.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ChatNameResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Set your chat namePUT /api/v1/workspaces/{workspaceId}/chat-name
setChatName
Sets the name your chat messages go out under in this workspace (the other members see it, and so do the players). chatName is always sent: a text of 1 to 32 characters (leading and trailing spaces are removed), an empty or blank text to send your messages with no name, or null to go back to the default (your Discord display name). 422 validation_failed on /chatName: too_long, control_character, markup_not_allowed (no < or >, because the game draws chat as rich text), reserved_name (SERVER, Console, RustSC, System) or name_taken (another member already goes out under that name). Only a member who manages members (an Owner or an Administrator) changes a chat name; anyone else gets 403 forbidden, and canChange on the read says so. Only your signed-in session changes it, not a key or an assistant. One audit record (member.chat_name.changed, target your membership) that holds the new name; answers the chat name as it is now.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body SetChatNameBody
chatName(string, required): 1 to 32 characters.
Success: 200 ChatNameResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List pending invitationsGET /api/v1/workspaces/{workspaceId}/invitations
listInvitations
The invitations that have not been accepted or withdrawn, newest first. An expired one stays until it is sent again or withdrawn. Needs members.read.
Workspace permission: members.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 InvitationListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Invite someonePOST /api/v1/workspaces/{workspaceId}/invitations
createInvitation
Invites a person by email with a role for the whole workspace (workspaceRoleId) or with roles on some servers (servers), or both, and optionally hosts the person may see, read-only (hosts). The access is checked as you: you can give only roles you hold, an Administrator or any role that manages members is for the whole workspace only (admin_level_workspace_scope_only), and the Owner role is not given here. One pending invitation per address: inviting again updates it and sends a new link. An address that already belongs to a member is refused (already_member). The email is sent when the invitation is saved; emailSent says whether the email provider accepted it, and a false leaves the invitation pending so it can be sent again. Answers 201, or 200 when an earlier pending invitation was updated. Needs members.manage.
Workspace permission: members.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body CreateInvitationBody
email(string, required): One plain email address.hosts(list of HostAccessBody): The hosts the person may see, read-only (status, last seen, version, and the servers on it they may see).servers(list of ServerAccessBody, required): The roles on single servers, at most one per server; empty when the role for the whole workspace is enough.workspaceRoleId(string, required): The role for the whole workspace, or null for a person who is invited to servers only.
Success: 200 InvitationSentResponse, 201 InvitationSentResponse. Errors use Problem.
Response statuses: 200, 201, 401, 403, 404, 409, 422, default.
Withdraw an invitationDELETE /api/v1/workspaces/{workspaceId}/invitations/{invitationId}
revokeInvitation
The invitation's link stops working. Withdrawing a withdrawn invitation changes nothing; an accepted one is a 409 (remove the member instead). Needs members.manage.
Workspace permission: members.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- invitationId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Send an invitation againPOST /api/v1/workspaces/{workspaceId}/invitations/{invitationId}/resend
resendInvitation
Makes a new link with a new lifetime, sends it, and stops the old link. The access is checked again as you. A withdrawn or accepted invitation is a 409. Needs members.manage.
Workspace permission: members.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- invitationId (path, required)
- See the downloadable contract for the field schema.
Success: 200 InvitationSentResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Remove a member or leave the workspaceDELETE /api/v1/workspaces/{workspaceId}/members/{membershipId}
removeMember
Removes the member: their roles go and everything they started through a key stops working at the next request. With your own membership ID it is leaving the workspace, which needs no permission. Removing someone else needs members.manage, and members.owners.manage for an Owner. The last Owner cannot leave or be removed (409 state_conflict, reason last_owner): transfer ownership first. Servers, history and the audit trail stay. One audit record (member.removed or member.left). Answers 204.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- membershipId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Set what a member can doPUT /api/v1/workspaces/{workspaceId}/members/{membershipId}/access
setMemberAccess
Sets the member's role for the whole workspace and their roles on single servers in one change, and returns the member. Send the whole of it: workspaceRoleId is the member's role for the whole workspace or null for none, and servers lists at most one role per server; roles on servers not listed are taken away, and roles given for a server group are left alone. The Owner role is not given here (owner_role_not_here). Nobody gives a role they do not hold themselves. Each change is audited. Needs members.manage.
Workspace permission: members.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- membershipId (path, required)
- See the downloadable contract for the field schema.
Request body SetMemberAccessBody
hosts(list of HostAccessBody): The hosts the member may see, read-only: its status, when it was last seen and its version, and the servers on it they may see.servers(list of ServerAccessBody, required): The member's roles on single servers, at most one role per server; empty for none.workspaceRoleId(string, required): The member's role for the whole workspace, or null for none (the member then has only the servers listed).
Success: 200 MemberResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Make a member the OwnerPOST /api/v1/workspaces/{workspaceId}/members/{membershipId}/actions/transfer-ownership
transferOwnership
Makes this member the Owner and you an Administrator, in one change: the workspace always has an Owner. The new Owner's other roles are dropped because an Owner has every server. You need members.owners.manage (Owners have it). A member who is an Owner already is 422 validation_failed, already_owner. Open pages of both people change at their next request. One audit record (ownership.transferred). Answers both members as they are now.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- membershipId (path, required)
- See the downloadable contract for the field schema.
Success: 200 OwnershipTransferResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Set a member's chat namePUT /api/v1/workspaces/{workspaceId}/members/{membershipId}/chat-name
setMemberChatName
Sets the name a member's chat messages go out under in this workspace, whoever the member is. The body and the answer are those of setChatName, for the member in the path. chatName is always sent: a text of 1 to 32 characters, an empty or blank text for no name, or null for the default (the member's Discord display name). 422 validation_failed on /chatName: too_long, control_character, markup_not_allowed, reserved_name or name_taken (another member already goes out under that name, compared without regard to case or the number of spaces; two administrators saving the same name together get one success and one refusal). A membership of another workspace is 404 not_found. Needs members.manage. Only a signed-in session changes it, not a key or an assistant. A change that changes nothing writes no record; otherwise one audit record (member.chat_name.changed, target the membership) that holds the new name.
Workspace permission: members.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- membershipId (path, required)
- See the downloadable contract for the field schema.
Request body SetChatNameBody
chatName(string, required): 1 to 32 characters.
Success: 200 ChatNameResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List permissionsGET /api/v1/workspaces/{workspaceId}/permissions
listPermissions
Every permission a role can hold, in catalog order: its access (read or write), the narrowest scope it applies at and whether a role you make can hold it. Needs members.read.
Workspace permission: members.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PermissionListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List rolesGET /api/v1/workspaces/{workspaceId}/roles
listRoles
The workspace's roles: the five presets, then custom roles by name. serverScopable tells which roles can be given on specific servers (not admin-level, and holding at least one permission that applies to a server). Needs members.read.
Workspace permission: members.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RoleListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Make a rolePOST /api/v1/workspaces/{workspaceId}/roles
createRole
Makes a role of your own from a name and permissions (see the permissions list). You can give only permissions you hold yourself, and the Owner-only permissions (members.owners.manage, hosts.reboot) are not grantable. Give it to members with the member access change or an invitation. Needs roles.manage. Answers 201 with the role.
Workspace permission: roles.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body RoleBody
name(string, required): The name members see.permissions(list of string, required): The permission names the role holds, at least one.
Success: 201 RoleResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Delete a roleDELETE /api/v1/workspaces/{workspaceId}/roles/{roleId}
deleteRole
Deletes a role of your own. A role a member holds, or a pending invitation gives, is 409 state_conflict, reason role_in_use: change or withdraw that first. Presets cannot be deleted (422 preset_role). Needs roles.manage. Answers 204.
Workspace permission: roles.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- roleId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Change a rolePUT /api/v1/workspaces/{workspaceId}/roles/{roleId}
updateRole
Changes the name and the whole set of permissions of a role of your own; the limits of making one apply. People who hold it get the change at their next request. Owner, Administrator, Operator, Moderator and Viewer cannot be changed (422 preset_role). Needs roles.manage.
Workspace permission: roles.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- roleId (path, required)
- See the downloadable contract for the field schema.
Request body RoleBody
name(string, required): The name members see.permissions(list of string, required): The permission names the role holds, at least one.
Success: 200 RoleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Notifications
Remove this device's notification routeDELETE /api/v1/account/notification-device
removeNotificationDevice
Old provider replies and old registration generations cannot restore it.
- installationId (query, required)
- Random app installation UUID, retained in protected local storage.
- generation (query, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Read this device's notification setupGET /api/v1/account/notification-device
getNotificationDevice
Reads your installation in the authenticated native app namespace. No provider token is returned.
- installationId (query, required)
- Random app installation UUID, retained in protected local storage.
Success: 200 NotificationDeviceResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Register this device for notificationsPUT /api/v1/account/notification-device
registerNotificationDevice
Registers the signed-in account's installation for notifications. Use a higher generation when changing the request. Repeat the same generation only with identical content.
Request body NotificationDeviceBody
apnsEnvironment(string): Apple aps-environment of the signed binary; omitted by Android and older clients.appVersion(string)generation(integer)installationId(string)locale(string)permission(string)token(string)urgentChannel(boolean): True when an Android phone made the channel for critical alerts; omitted by iPhones and older clients.
Success: 200 NotificationDeviceResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, 429, default.
Read your workspace noticesGET /api/v1/workspaces/{workspaceId}/customer-notices
listWorkspaceCustomerNotices
Returns only delivered in-app notices for the current account and active workspace membership; reading changes nothing.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- cursor (query)
- See the downloadable contract for the field schema.
- limit (query)
- See the downloadable contract for the field schema.
Success: 200 CustomerNoticePageResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read the alerts your phone takesGET /api/v1/workspaces/{workspaceId}/notification-devices/{deviceId}/alerts
getMobileAlertChoices
Lists the alerts the workspace has on that may reach a phone, with whether this phone takes each. Only this phone's own choices are read; they are not the workspace's alert settings and need no alert-management permission.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- deviceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 MobileAlertChoicesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Hand an alert back to your own choiceDELETE /api/v1/workspaces/{workspaceId}/notification-devices/{deviceId}/alerts/{kind}
clearMobileAlertChoice
Removes this phone's own choice for the alert, so the phone follows your own phone choice for it again. The answer is the list as it now is.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- deviceId (path, required)
- See the downloadable contract for the field schema.
- kind (path, required)
- See the downloadable contract for the field schema.
Success: 200 MobileAlertChoicesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Switch an alert on or off for your phonePUT /api/v1/workspaces/{workspaceId}/notification-devices/{deviceId}/alerts/{kind}
setMobileAlertChoice
Changes only this phone: not the workspace's alert settings, not other members, not your other phones or browsers. Saved at once; the answer is the list as it now is.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- deviceId (path, required)
- See the downloadable contract for the field schema.
- kind (path, required)
- See the downloadable contract for the field schema.
Request body MobileAlertChoiceBody
on(boolean, required): True to take the alert on this phone, false to never take it.
Success: 200 MobileAlertChoicesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read your device's alert preferencesGET /api/v1/workspaces/{workspaceId}/notification-devices/{deviceId}/preferences
getMobileNotificationPreferences
Only the current native device owner can read its personal route.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- deviceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 MobilePreferenceResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save your device's alert preferencesPUT /api/v1/workspaces/{workspaceId}/notification-devices/{deviceId}/preferences
saveMobileNotificationPreferences
Choose categories and servers for this device. This does not require managing workspace integrations.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- deviceId (path, required)
- See the downloadable contract for the field schema.
Request body MobilePreferenceBody
allServers(boolean, required)categories(list of string, required)enabled(boolean, required)includeSummary(boolean, required)serverIds(list of string, required)
Success: 200 MobilePreferenceResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read your alertsGET /api/v1/workspaces/{workspaceId}/notification-inbox
listMobileNotificationInbox
Current server authority filters every item. Read state belongs to your account and is separate from acknowledgement.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- state (query)
- See the downloadable contract for the field schema.
- category (query)
- See the downloadable contract for the field schema.
- serverId (query)
- See the downloadable contract for the field schema.
- cursor (query)
- See the downloadable contract for the field schema.
- limit (query)
- See the downloadable contract for the field schema.
Success: 200 MobileInboxResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Mark all your alerts readPOST /api/v1/workspaces/{workspaceId}/notification-inbox/mark-all-read
markAllMobileNotificationsRead
Marks every unread active alert you can see as read for you only, or only those about one server (optional query serverId). It never acknowledges anything, a repeat changes nothing, and the answer says how many were marked and how many unread alerts you have left.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (query)
- See the downloadable contract for the field schema.
Success: 200 MobileInboxMarkAllReadResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Count your unread alertsGET /api/v1/workspaces/{workspaceId}/notification-inbox/unread-count
countMobileUnreadAlerts
Counts the unread alerts you can see that are still active (open or acknowledged); a cleared alert is not counted. Read state is separate from acknowledgement.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 MobileInboxUnreadCountResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read an alertGET /api/v1/workspaces/{workspaceId}/notification-inbox/{incidentId}
getMobileNotificationIncident
Reads current incident state and authorized server context.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- incidentId (path, required)
- See the downloadable contract for the field schema.
Success: 200 MobileInboxItemResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Clear an acknowledgementDELETE /api/v1/workspaces/{workspaceId}/notification-inbox/{incidentId}/acknowledgement
clearMobileNotificationAcknowledgement
Takes the acknowledgement back so the alert is open and unacknowledged again; the history keeps who cleared it and when. Needs alerts.manage, like acknowledging.
Workspace permission: alerts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- incidentId (path, required)
- See the downloadable contract for the field schema.
Success: 200 MobileIncidentAcknowledgementResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Acknowledge an alertPOST /api/v1/workspaces/{workspaceId}/notification-inbox/{incidentId}/acknowledgement
acknowledgeMobileNotificationIncident
Uses the shared incident acknowledgement operation and its alerts.manage permission. This stops reminders and keeps read state separate. The body is optional: a comment (at most 500 characters) is kept in the alert's history and shown while it stays acknowledged.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- incidentId (path, required)
- See the downloadable contract for the field schema.
Success: 200 MobileIncidentAcknowledgementResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read alert historyGET /api/v1/workspaces/{workspaceId}/notification-inbox/{incidentId}/history
getMobileIncidentHistory
Authoritative state transitions since historyAvailableFrom. Actor names are not exposed. Reauthorizes the incident and its servers.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- incidentId (path, required)
- See the downloadable contract for the field schema.
Success: 200 MobileIncidentHistoryResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Mark an alert read or unreadPUT /api/v1/workspaces/{workspaceId}/notification-inbox/{incidentId}/read
setMobileNotificationRead
Changes only your read state. It never acknowledges the shared incident.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- incidentId (path, required)
- See the downloadable contract for the field schema.
Request body MobileInboxReadBody
read(boolean, required)
Success: 200 MobileInboxItemResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
MobileNotificationEndpoints
Open a notificationGET /api/v1/account/notification-reference
resolveMobileNotificationReference
The opaque reference is account-bound and expires. Every linked incident is reauthorized before return. No server work is performed.
Success: 200 MobileNotificationResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Sign-in
Send a sign-in codePOST /api/v1/auth/email/start
startEmailSignIn
Requests a one-time code when email sign-in is available. If unavailable, use another sign-in option shown in the portal. For a new request, send a UUIDv7 requestId and resend=false. If the response is lost, repeat the same request. To request another code, send a new requestId and resend=true.
Request body EmailSignInStartRequest
analytics(SignInAnalyticsRequest)email(string, required): The email address to send the code to.requestId(string): Optional UUIDv7 identity for this initial request or explicit resend.resend(boolean): False for a new initial request and its retries; true for one explicit new resend with a new requestId.
Success: 202 EmailChallengeResponse. Errors use Problem.
Response statuses: 202, 403, 404, 422, 429, 503, default.
Verify a sign-in codePOST /api/v1/auth/email/verify
verifyEmailSignIn
Signs the browser in using the emailed code when email sign-in is available. Each code works once. A first sign-in returns 201 if account creation is available.
Request body EmailSignInVerifyRequest
challengeId(string, required): The `challengeId` returned when the code was requested.code(string, required): The code from the email.privacyVersion(string): The Privacy Policy version the page showed; see `termsVersion`.termsVersion(string): Development and test sign-up by emailed code only: the Terms version the page showed when the person continued.
Success: 200 SignInResponse, 201 SignInResponse. Errors use Problem.
Response statuses: 200, 201, 403, 404, 422, 503, default.
Finish a first Google or Discord sign-in with an email codePOST /api/v1/auth/external/complete
completeExternalSignIn
Request the code with the ordinary email sign-in start, then send it here. The provider account is linked to the account of that address (created when new) and the browser is signed in. Works once; the code has the usual attempt limit.
Request body EmailSignInVerifyRequest
challengeId(string, required): The `challengeId` returned when the code was requested.code(string, required): The code from the email.privacyVersion(string): The Privacy Policy version the page showed; see `termsVersion`.termsVersion(string): Development and test sign-up by emailed code only: the Terms version the page showed when the person continued.
Success: 200 SignInResponse, 201 SignInResponse. Errors use Problem.
Response statuses: 200, 201, 403, 422, default.
Forget the provider account waiting for an email codeDELETE /api/v1/auth/external/pending
cancelExternalSignIn
Used when the person chooses another way to sign in. Succeeds when nothing is waiting.
Success: 204. Errors use Problem.
Response statuses: 204, default.
Read the provider account waiting for an email codeGET /api/v1/auth/external/pending
getExternalSignInPending
After a first Google or Discord sign-in the person confirms an email address with a code. This returns the provider account waiting in this browser, or 404 when nothing is waiting or it waited too long.
Success: 200 ExternalPendingResponse. Errors use Problem.
Response statuses: 200, 404, default.
List the ways to sign inGET /api/v1/auth/options
getSignInOptions
Returns the Google and Discord sign-in this deployment has set up and whether passkeys work, so the sign-in page shows only buttons that work. Needs no session.
Success: 200 SignInOptionsResponse. Errors use Problem.
Response statuses: 200, default.
Get the options for signing in with a passkeyPOST /api/v1/auth/passkey/options
startPasskeySignIn
No account is named: the browser offers the passkeys it has for this site. Send the browser's answer to the passkey sign-in route.
Success: 200 PasskeyOptionsResponse. Errors use Problem.
Response statuses: 200, 403, default.
Sign in with a passkeyPOST /api/v1/auth/passkey/sign-in
signInWithPasskey
Checks the browser's answer to the options. A passkey made for another site, an answer that was used before and an unknown passkey all fail the same way (422 passkey_failed).
Request body PasskeySignInRequest
challengeId(string, required)credential(JsonElement, required): The result of `navigator.credentials.get` as JSON (`credential.toJSON()`).
Success: 200 SignInResponse. Errors use Problem.
Response statuses: 200, 403, 422, default.
Sign outDELETE /api/v1/session
signOut
Ends the browser session and clears its cookie, or revokes the authenticated native device authorization family. Signing out without a session also succeeds.
Success: 204. Errors use Problem.
Response statuses: 204, 403, default.
Read your signed-in accountGET /api/v1/session
getSession
Accepts the browser session or a validated first-party native API bearer. Returns account identity and a request forgery token for unsafe browser requests, setting the antiforgery cookie. Native bearer callers do not need that token.
Success: 200 SessionResponse. Errors use Problem.
Response statuses: 200, 503, default.
Client errors
Tell us a screen failed to loadPOST /api/v1/client-errors
recordClientError
Sent by the portal when a screen cannot be loaded: the screen's pattern, the failed answer's status (0 when there was none) and reference, the error's type name and the portal's version. Nothing else is accepted. A few a minute per sign-in (429 rate_limited).
Request body ClientErrorBody
appVersion(string): The portal's version.errorName(string): The error's type name such as `TypeError`.route(string): The route pattern such as `/w/:workspaceId/servers/:serverId`, never a real identifier or a query.status(integer): The failed answer's status, or 0 when the screen failed without one.traceId(string): The failed answer's reference, when it gave one.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 422, 429, default.
Public analytics
Read optional first-party measurement availabilityGET /api/v1/public/analytics-context
getPublicAnalyticsContext
Returns the current geography rule without setting cookies or recording a page event. Unknown geography requires consent. Development, synthetic and privacy-signal requests never enable collection.
Success: 200 AnalyticsContextResponse. Errors use Problem.
Response statuses: 200, default.
Submit an optional identifier-free page measurementPOST /api/v1/public/analytics-events
recordPublicAnalyticsEvent
Accepts only the documented bounded browser catalog. Credentials are ignored. Privacy signals, opted-out requests, support/test traffic, unknown routes and requests without required consent are discarded. A missing measurement never changes product behavior.
Request body AnalyticsEventRequest
bundle(string)campaign(object)consentGranted(boolean)cta(string)device(string)entry(boolean)errorClass(string)kind(string)language(string)line(integer)navigation(string)optOut(boolean)path(string)ratings(object)referrerHost(string)release(string)site(string)
Success: 204. Errors use Problem.
Response statuses: 204, 400, 413, 429, default.
Feedback
Send feedback from the public sitePOST /api/v1/public/feedback
sendPublicFeedback
No sign-in, text only (at most 2,000 characters, body at most 8 KiB), with an optional reply address. A hidden website field catches bots. At most 5 an hour per address (429 rate_limited).
Request body PublicFeedbackBody
kind(string)message(string)replyTo(string): Where to answer, if they want an answer.website(string): A field people never see; a filled one means a bot.
Success: 201 FeedbackSentResponse. Errors use Problem.
Response statuses: 201, 422, 429, default.
Read the public roadmapGET /api/v1/public/roadmap
getPublicRoadmap
No sign-in. Every roadmap item with its status and the number of accounts that voted. Same address limit as the directory (429 rate_limited).
Success: 200 RoadmapResponse. Errors use Problem.
Response statuses: 200, 429, default.
Read the roadmap as a signed-in accountGET /api/v1/roadmap
getRoadmap
Every roadmap item with its votes and whether this account voted. Needs a session.
Success: 200 RoadmapResponse. Errors use Problem.
Response statuses: 200, 401, default.
Take a vote backDELETE /api/v1/roadmap/{itemId}/vote
removeRoadmapVote
Removes this account's vote on the item; repeating it changes nothing.
- itemId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RoadmapItemResponse. Errors use Problem.
Response statuses: 200, 401, 404, default.
Vote for a roadmap itemPUT /api/v1/roadmap/{itemId}/vote
voteRoadmapItem
One vote per account per item; repeating it changes nothing. An account holds at most 50 votes.
- itemId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RoadmapItemResponse. Errors use Problem.
Response statuses: 200, 401, 404, 409, default.
Send feedback or a bug reportPOST /api/v1/workspaces/{workspaceId}/feedback
sendFeedback
Any active member sends one report: a kind (problem or idea), their words (at most 2,000 characters) and optionally the page, the app version, the browser and one PNG or JPEG screenshot of at most 1 MiB (base64). Keys, addresses and URL queries in the text are removed before it is stored. Reports are kept 90 days and read only by the platform owner. At most 10 a day per account.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body FeedbackBody
appVersion(string)browser(string)kind(string): `problem` or `idea`.message(string): Their words, at most 2,000 characters.page(string): The page they were on, as a path.screenshot(string): One PNG or JPEG of at most 1 MiB, base64.
Success: 201 FeedbackSentResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Public support
Send a support requestPOST /api/v1/public/support-requests
submitPublicSupportRequest
Creates a private support ticket through the platform's support desk. No sign-in is required. Keep the same submissionKey when checking an uncertain result; an uncertain delivery is never sent again automatically. A successful response means the desk confirmed a ticket identity.
Request body PublicSupportRequest
email(string, required)message(string, required)name(string)subject(string, required)submissionKey(string)topic(string, required)website(string)
Success: 200 PublicSupportResponse, 202 PublicSupportResponse. Errors use Problem.
Response statuses: 200, 202, 400, 403, 409, 413, 415, 429, 503, default.
Support
Send an account support requestPOST /api/v1/support-requests
submitSupportRequest
Requires a browser or first-party native session. Uses your account email. Accepts JSON without files or multipart fields topic, subject, message, submissionKey, optional workspaceId and up to five attachments. Keep the same key and identical content when checking uncertain delivery; a ticket is never blindly resent. Sending without a workspace needs no workspace membership; an optional workspace is associated only with a current membership.
Request body AccountSupportRequest
message(string, required)subject(string, required)submissionKey(string, required)topic(string, required)workspaceId(string): Optional explicit workspace association, using the typed workspace ID from your directory.
Success: 200 PublicSupportResponse, 202 PublicSupportResponse. Errors use Problem.
Response statuses: 200, 202, 400, 401, 403, 409, 413, 415, 429, 503, default.
Servers
Stop upkeep alerts or snooze a cupboard with the link in a messagePOST /api/v1/upkeep/link
applyUpkeepLink
Needs no sign-in: the link's own t value names the server, the player and the one action. Answers stopped or snoozed (repeating the link is safe). A damaged or ended link answers 422 link_invalid and says nothing more.
- t (query)
- See the downloadable contract for the field schema.
Success: 200 UpkeepLinkResponse. Errors use Problem.
Response statuses: 200, 422, default.
Read linking in the gameGET /api/v1/workspaces/{workspaceId}/in-game-linking
getInGameLinking
Whether a form saved linking in the game (/link) for the workspace's servers, and whether it was saved as on. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 InGameLinkingResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save linking in the gamePUT /api/v1/workspaces/{workspaceId}/in-game-linking
setInGameLinking
Turns in-game linking on or off for every affected server. Offline hosts receive the change when they reconnect. Needs servers.software.manage.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body InGameLinkingBody
command(string): The command players type in the game, without the slash: 1 to 32 of a to z, 0 to 9 and _, saved in lower case, not a plugin framework's own (oxide, o, c, carbon, umod).enabled(boolean): True lets players link in the game (/link) on every server a host runs; false stops it.
Success: 200 InGameLinkingResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List serversGET /api/v1/workspaces/{workspaceId}/servers
listServers
The workspace's servers you can read, by name. Filter with hostId (repeatable). Removed servers are left out.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (query)
- Only servers on these hosts; repeat it for several.
- limit (query)
- Page size within the documented range.
- cursor (query)
- The nextCursor of the previous page.
Success: 200 ServerListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Add a serverPOST /api/v1/workspaces/{workspaceId}/servers
addServer
Returns the operation; its target is the new server. The server is installing until the operation ends, then ready or install_failed. Needs servers.create.
Workspace permission: servers.create
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body AddServerRequestBody
admission(AdmissionBody)branch(string): The Steam branch to install; leave it out for the default branch, `public`.crashRecovery(boolean): The form's pre-ticked "Restart it if it crashes" switch.hostId(string): The full host to add the server on, for example `host_01jb8z3k4q7v9w2x5y6z8a0b1c`.map(ServerMapBody)name(string): Display name, a label for lists and operation summaries.playerLink(boolean): The form's pre-ticked "Let players link in the game" switch.ports(ServerPortsBody)root(string): The existing folder on the host to install into, as an absolute path of ASCII letters, digits, '.', '_' and '-' segments, for example `/srv/rust/example-server`.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Install againPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/install
installServer
Installs the Rust dedicated server again into a server whose install failed, checking every file. Returns the operation. Needs servers.software.manage.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body InstallServerRequestBody
admission(AdmissionBody)branch(string): The Steam branch; leave it out to keep the branch of the failed install.root(string): A different folder to install into, for an install that failed because of the folder; leave it out to keep the server's folder.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Replace a serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/replace
replaceServer
Moves the server record to the supplied hostId and root, or keeps those settings if omitted. It keeps the server's ID, name, history, schedules, rules and backups. pushConfiguration and installFramework default to true. The new server stays stopped. Restore from a backup to recover settings, permissions or saved worlds that were not copied. If the result is root_in_use, choose another folder. Needs servers.software.manage and servers.create.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ReplaceServerRequestBody
admission(AdmissionBody)hostId(string): The host that holds the new game (`hst_` ID); leave it out for the server's own host.installFramework(boolean): Step 2: install the framework the server had.installGame(boolean): Step 1: install the game server.installPlugins(boolean): Step 3: install the plugins that can be downloaded from uMod.installRustscPlugin(boolean): Step 3, continued: install the RustSC plugin after the framework (needs the framework step and a framework the server had).ports(ServerPortsBody)pushConfiguration(boolean): Step 4: push the saved settings (server.cfg values, launch arguments, world settings, ports, schedules).restoreFromCloud(boolean): Step 5, the safety override: download the cloud copy of the backup even when the host holds an intact copy of it.restoreRecoveryPointId(string)root(string): The game folder on that host; leave it out to keep the folder the server has.
Success: 202 ReplaceServerResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read whether commands reach a rented serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/command-route
getServerCommandRoute
rented is false for a server on a host with RustSC installed: its commands go through that host and state is absent. For a rented server, state is available (console commands, chat lines and saved and moderator commands are sent through the server's own route), console_needed (the host has no command route of its own: add the server's console on the Rented server page), not_offered (a route exists but is not offered yet), not_possible_on_host (no route on this host can send a command) or not_connected (the server has no saved connection). Needs servers.console.read.
Workspace permission: servers.console.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ServerCommandRouteResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read whether a server's console hides repeated errorsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/console-filter
getServerConsoleFilter
Whether the flood filter is on for the server, when it ends by itself, the durations a member can choose (durations) and whether the server's host applies it (onTheHost; false for a server with no agent, where the portal applies it to the lines it receives). Needs servers.console.read.
Workspace permission: servers.console.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ConsoleFilterResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Hide repeated errors in a server's console for a while, or stop hiding themPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/console-filter
setServerConsoleFilter
duration is 15m, 1h or until_off (the filter then still ends by itself after 30 days), or off to switch it off (422 invalid at /duration). While it is on, repeats of the same error stay out of the console views and are told as one summary line; the host's own log and the game are untouched. Needs servers.console.execute.
Workspace permission: servers.console.execute
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body SetConsoleFilterBody
duration(string, required): 15m, 1h or until_off to switch the filter on for that long; off to switch it off.
Success: 200 ConsoleFilterResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the times a server's console repeated the same lineGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/console-storms
listServerConsoleStorms
The times the server's console repeated one line over and over, newest first: when it began and ended, how many repeats were counted instead of kept, and the repeated line with its changing values masked and anything private removed. Older than 14 days are not shown. limit is 1 to 20 (default 10). Needs servers.console.read.
Workspace permission: servers.console.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- limit (query)
- See the downloadable contract for the field schema.
Success: 200 ConsoleStormListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List the ends of a server's gameGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/game-exits
listServerGameExits
The ends of the server's game processes, newest first: the exit code or signal, how long it ran, whether a stop was recorded, what crash recovery decided, what was true when the game was called ready and the redacted last lines of the game's and the framework's log. Older than 30 days are not shown. Needs servers.console.read.
Workspace permission: servers.console.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- limit (query)
- See the downloadable contract for the field schema.
Success: 200 GameExitListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read what a rented server's host says happened to the serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/host-activity
listRentedHostActivity
Reads, on this request only, the host's own record of what happened to the server: started, stopped, restarted, killed, a backup made or restored, and a file changed, newest first (at most 50). Only what someone did outside RustSC is listed: what the member asked RustSC to start, stop, restart or kill is left out (the Activity list already holds it), and a backup or file change is listed only when the host says its own page or file login made it. No person's name, address, command or file name is read from the host. offered is false when this server has no such record (a host that has none, a key that may not read it, or no answer), and the list is then empty. A recent answer may be given again; readAt says when it was read, and refresh=true reads it now. 404 for a server that is not a connected rented server. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- refresh (query)
- See the downloadable contract for the field schema.
Success: 200 RentedHostActivityResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read what the host of a rented server allowsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/host-allows
getServerHostAllows
onPanelHost is false for a server with an agent and then lines is empty. Otherwise each line is something a wipe or timed change does, whether the host offers it, and one sentence for why not when it does not. refusal is set only when wipe plans cannot run there at all. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelHostAllowsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read the launch arguments an adoption importedGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/launch-baseline
getServerLaunchBaseline
The launch arguments read, as text and never run, from the start scripts of an adopted server when the import choice was on: known ones with their values, the others as found, and the ones whose value came from a variable or command the file does not set. The RCON password and salt are never kept. Empty for a server RustSC installed. Nothing here is applied. world lists the values that decide which world loads (map link, map, size, seed, save folder) with where each was read from, in words. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 LaunchBaselineResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Rename a server in RustSCPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/name
renameServer
Changes the name RustSC shows for the server, everywhere. It never changes the server's Rust hostname, its folder or any setting. 1 to 100 characters after trimming, no control characters. Needs servers.config.write.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body RenameBody
name(string, required): 1 to 100 characters after trimming, no control characters.
Success: 200 RenamedResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read whether RustSC may change files on a server through its hosting panelGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-executor
getServerPanelExecutor
on is true only after a member saved it on for this server; changedAt is absent until a choice was saved. Nothing changes on the server until it is on and a wipe or timed change uses it.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelExecutorResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Allow or switch off RustSC changing files on a server through its hosting panelPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-executor
setServerPanelExecutor
on true saves the choice, false saves it off. Saving changes nothing on the server by itself; files change only when a wipe or timed change on this server is set to use it.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body SetPanelExecutorBody
on(boolean, required): True allows RustSC to change files on this server through its hosting panel; false stops it.
Success: 200 PanelExecutorResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read who restarts a rented serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-restarts
getServerPanelRestarts
onPanelHost is false for a server with an agent. line is one plain sentence when the host starts, stops or restarts the server on a schedule of its own, and is absent when it does not or when the host did not answer. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelLifecycleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List the temporary changes, wipes and restarts saved for a rented serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule
getServerPanelSchedule
onPanelHost is false for a server with an agent, which keeps its own schedules, and then every list is empty. restarts (state waiting, running, done, failed or missed) are listed oldest first, and restartRoute says whether the host offers a restart through its own power control (offered) and whether RustSC can say a line to players first (canWarn). wipeRoute says whether the host offers a wipe (offered is true only where a wipe ran live on that kind of host) and is absent where no route can wipe there. filesSwitchOn is the saved choice of setServerPanelExecutor: while it is false, waiting changes and wipes do not run. Otherwise changes (state waiting, active, ended or missed) and wipes (state waiting, running, done, failed or missed) are listed oldest first with the last thing that happened to each in line. Reading changes nothing. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelScheduleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a temporary change for a rented serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/changes
createServerPanelChange
Saves a change that takes files away or puts saved files in place from startAt to endAt, then puts everything back. Each item is a path in the server's Oxide or Carbon folder and a savedPart, or none to take the file away while the change is on. Saving changes nothing on the server: RustSC acts on it only while the saved choice of setServerPanelExecutor is on, so a new change is refused while it is off (409 executor_off). startAt must be in the future and endAt after it. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body PanelChangeBody
endAt(string)items(list of PanelItemBody)name(string): The name the member knows it by, 1 to 40 characters.startAt(string)
Success: 201 PanelChangeResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Delete a temporary change of a rented serverDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/changes/{changeId}
deleteServerPanelChange
Deletes a change that is waiting, ended or skipped. A change that is in place is 409 in_place: it is taken out at its end time. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Change a temporary change of a rented serverPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/changes/{changeId}
changeServerPanelChange
Saves the change as given. Only a change that is still waiting can be changed (409 already_started).
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
Request body PanelChangeBody
endAt(string)items(list of PanelItemBody)name(string): The name the member knows it by, 1 to 40 characters.startAt(string)
Success: 200 PanelChangeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Take a temporary change of a rented server out nowPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/changes/{changeId}/end-now
endServerPanelChangeNow
Moves the end of a change that is in place to now, so the original files are put back at once. Works only while the saved choice of setServerPanelExecutor is on (409 executor_off otherwise). Repeating it after the change ended changes nothing. 409 not_in_place for a change that is waiting or was skipped. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelChangeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Put a saved temporary change of a rented server in place nowPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/changes/{changeId}/start-now
startServerPanelChangeNow
Moves the start of a change that is waiting to now, so the files change at once instead of at the saved time; it still ends at its saved end time. The files change only while the saved choice of setServerPanelExecutor is on (409 executor_off otherwise). Repeating it on a change already in place changes nothing. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelChangeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the timed chat lines and console commands saved for a rented serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/console
getServerPanelConsoleSchedules
onPanelHost is false for a server with an agent, which keeps its own schedules, and then the list is empty. offered says whether commands reach the server now through its host or its game console; where it is false a save is refused. Each schedule has its kind (say or command), its text, its next time (dueAt, state waiting) or state done for a one time schedule that ran, how it repeats (everyMinutes, or repeat with a timeOfDay, timeZone and days) and its newest results first (recent: at, state sent, failed, missed or unknown, the line in plain words and, for a command, the game's reply). Reading changes nothing. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelConsoleListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a timed chat line or console command for a rented serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/console
createServerPanelConsoleSchedule
Saves a schedule that says text in game chat (kind say) or runs text as a console command (kind command) at dueAt, then every everyMinutes minutes (1 to 10080), or at the time and on the days of repeat, until it is deleted; with neither it runs once. With everyMinutes a dueAt that passed starts at its next step. A time missed while RustSC could not reach the host is skipped, not made up. Saving changes nothing on the server until its time. 409 not_offered where commands do not reach the server, 409 not_on_panel_host for a server with an agent. Kind backup takes a backup at the time and on the days of repeat (repeat is required, everyMinutes is not allowed) and keeps the newest keepLast scheduled copies (1 to 14); it is refused with not_offered where backupOffered is false and needs backups.create.
Workspace permission: automation.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body PanelConsoleBody
dueAt(string): The first time.everyMinutes(integer): Repeats every this many minutes, 1 to 10080.keepLast(integer): For a backup: how many scheduled copies to keep, 1 to 14 (7 when left out).kind(string): say (a line said in game chat), command (a console command) or backup (a backup of the server's own copy in RustSC's storage).name(string): The name the member knows it by, 1 to 40 characters.repeat(PanelRestartRepeatBody)text(string): The line or the command, up to 500 characters, one line.
Success: 201 PanelConsoleResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Delete a timed chat line or console command of a rented serverDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/console/{scheduleId}
deleteServerPanelConsoleSchedule
Deletes the schedule; nothing more is sent for it. Needs schedules.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- scheduleId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Save a restart for a rented serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/restarts
createServerPanelRestart
Saves a restart for dueAt: RustSC restarts the server through the host's own power control at that time, and says message in game chat warnSeconds before when the host lets it say one (0 or absent says nothing; at most 3600), or at each of warnings (up to 5 times in seconds) when given. With repeat (a timeOfDay as HH:mm, a timeZone and optional days, 1 Monday to 7 Sunday, none meaning every day) it runs at that time on those days until it is deleted: dueAt is then not read, the first run is the next one the repeat names, and a run missed while RustSC could not reach the host is skipped, not made up. Saving changes nothing on the server until its time; a restart changes no file, so it does not need the saved choice of setServerPanelExecutor. Without repeat, dueAt must be in the future. 409 not_offered where the host offers no restart yet (restartRoute.offered is false in getServerPanelSchedule), 409 not_on_panel_host for a server with an agent. Needs schedules.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body PanelRestartBody
dueAt(string)message(string): The line players read, up to 200 characters; absent says a plain line with the time left.name(string): The name the member knows it by, 1 to 40 characters.repeat(PanelRestartRepeatBody)warnSeconds(integer): How many seconds before the restart players are told, 0 to 3600; absent or 0 says nothing.warnings(list of integer): When players are told, in seconds before the restart (each 1 to 3600, at most 5).
Success: 201 PanelRestartResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Delete a saved restart of a rented serverDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/restarts/{restartId}
deleteServerPanelRestart
Deletes a restart that is waiting, done, failed or skipped. Deleting the waiting run of a restart that repeats ends the repeat. A restart that was sent and is being read back is 409 running. Needs schedules.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- restartId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Change a saved restart of a rented serverPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/restarts/{restartId}
changeServerPanelRestart
Saves the restart as given. Only a restart that is still waiting can be changed (409 already_started); a changed restart is warned again. For a restart that repeats this is its next run, and a change applies to the runs after it too. Needs schedules.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- restartId (path, required)
- See the downloadable contract for the field schema.
Request body PanelRestartBody
dueAt(string)message(string): The line players read, up to 200 characters; absent says a plain line with the time left.name(string): The name the member knows it by, 1 to 40 characters.repeat(PanelRestartRepeatBody)warnSeconds(integer): How many seconds before the restart players are told, 0 to 3600; absent or 0 says nothing.warnings(list of integer): When players are told, in seconds before the restart (each 1 to 3600, at most 5).
Success: 200 PanelRestartResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Save a wipe template for a rented serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/wipe-templates
createServerPanelWipeTemplate
Saves a named recipe for wipes: what to remove, the warning, the save folder, whether to start the server again, and the files, delete lines and plugin updates. The wipe form fills itself from a template; nothing runs from a template and nothing changes on the server. At most 20 a server, names unique in any case. The fields follow the rules of createServerPanelWipe. 409 not_offered where the host offers no wipe, or no file steps when the template has some. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body PanelWipeTemplateBody
categories(list of string): What a wipe from it removes: map, blueprints, player_data and clans.deletions(list of string): Files deleted at the wipe: a path, or a name pattern with * and ? in the last name, in the oxide or carbon folder.files(list of PanelWipeCopyBody): Files put in place at the wipe until the next wipe.name(string): The name the member knows it by, 1 to 40 characters, unique on the server in any case.pluginUpdates(list of PanelWipeCopyBody): Plugin files replaced at the wipe and kept.saveFolder(string)startAfter(boolean)warning(string)
Success: 201 PanelWipeTemplateResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Delete a wipe template of a rented serverDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/wipe-templates/{templateId}
deleteServerPanelWipeTemplate
Deletes the template. A wipe already saved from it is not changed. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- templateId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Change a wipe template of a rented serverPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/wipe-templates/{templateId}
changeServerPanelWipeTemplate
Saves the template as given. A wipe already saved keeps the steps it was saved with. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- templateId (path, required)
- See the downloadable contract for the field schema.
Request body PanelWipeTemplateBody
categories(list of string): What a wipe from it removes: map, blueprints, player_data and clans.deletions(list of string): Files deleted at the wipe: a path, or a name pattern with * and ? in the last name, in the oxide or carbon folder.files(list of PanelWipeCopyBody): Files put in place at the wipe until the next wipe.name(string): The name the member knows it by, 1 to 40 characters, unique on the server in any case.pluginUpdates(list of PanelWipeCopyBody): Plugin files replaced at the wipe and kept.saveFolder(string)startAfter(boolean)warning(string)
Success: 200 PanelWipeTemplateResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Save a wipe for a rented serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/wipes
createServerPanelWipe
Saves a wipe for dueAt: it says warning in game chat, saves, stops the game, removes the world files of the chosen categories (map, blueprints, player_data, clans) from saveFolder and starts the game again unless startAfter is false. warnings tells players that many seconds before it. With repeat (a timeOfDay, a timeZone and optional days, or forceWipeDay with minutesAfter the monthly update) it runs at each time the repeat names until it is deleted, dueAt is not read, and a run missed while RustSC could not reach the host is skipped, not made up. pauseRestarts holds back the repeating restarts on the wipe's day until it ran; each one held back is skipped with skipReason paused_for_wipe. Saving changes nothing on the server: RustSC acts on it only while the saved choice of setServerPanelExecutor is on, so a new wipe is refused while it is off (409 executor_off). dueAt must be in the future. 409 not_offered where the host offers no wipe (wipeRoute.offered is false or wipeRoute is absent in getServerPanelSchedule), 409 not_on_panel_host for a server with an agent. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body PanelWipeBody
backUpFirst(boolean): True backs up the server once it has stopped and before the wipe changes anything, and the wipe does not go on if the backup cannot be made.categories(list of string): What to remove: map, blueprints, player_data and clans.deletions(list of string): Files deleted at the wipe and not put back: a path, or a name pattern with * and ? in the last name, in the oxide or carbon folder.dueAt(string)files(list of PanelWipeCopyBody): Files put in place at the wipe until the next wipe, which takes them out and puts the originals back.name(string): The name the member knows it by, 1 to 40 characters.pauseRestarts(boolean): True pauses the usual restarts on the wipe's day until the wipe ran.pluginUpdates(list of PanelWipeCopyBody): Plugin files replaced at the wipe and kept; a plugin that does not load gets its earlier file back where the host shows the game's answer.repeat(PanelWipeRepeatBody)saveFolder(string): The server's save folder in its files, for example `server/rust`.startAfter(boolean): False leaves the game stopped at the end.warning(string): The line said in game chat first; absent says nothing.warnings(list of integer): When players are told before the wipe, in seconds before it (each 1 to 3600, at most 5); absent or empty says nothing before it.
Success: 201 PanelWipeResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Preview a wipe of a rented server before it is savedPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/wipes/preview
previewServerPanelWipe
Takes the same body as createServerPanelWipe and says, step by step and in plain words, what the wipe would do on the server as it is now: the world files it would remove, the files each delete line matches, and whether each file to place or plugin to update is there. It reads the server's folders through the host and changes nothing; nothing is saved. A body the save would refuse is refused the same way (422). 409 not_on_panel_host for a server with an agent. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body PanelWipeBody
backUpFirst(boolean): True backs up the server once it has stopped and before the wipe changes anything, and the wipe does not go on if the backup cannot be made.categories(list of string): What to remove: map, blueprints, player_data and clans.deletions(list of string): Files deleted at the wipe and not put back: a path, or a name pattern with * and ? in the last name, in the oxide or carbon folder.dueAt(string)files(list of PanelWipeCopyBody): Files put in place at the wipe until the next wipe, which takes them out and puts the originals back.name(string): The name the member knows it by, 1 to 40 characters.pauseRestarts(boolean): True pauses the usual restarts on the wipe's day until the wipe ran.pluginUpdates(list of PanelWipeCopyBody): Plugin files replaced at the wipe and kept; a plugin that does not load gets its earlier file back where the host shows the game's answer.repeat(PanelWipeRepeatBody)saveFolder(string): The server's save folder in its files, for example `server/rust`.startAfter(boolean): False leaves the game stopped at the end.warning(string): The line said in game chat first; absent says nothing.warnings(list of integer): When players are told before the wipe, in seconds before it (each 1 to 3600, at most 5); absent or empty says nothing before it.
Success: 200 PanelWipePreviewResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Delete a saved wipe of a rented serverDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/wipes/{wipeId}
deleteServerPanelWipe
Deletes a wipe that is not running. A wipe that is running is 409 running. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- wipeId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Change a saved wipe of a rented serverPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-schedule/wipes/{wipeId}
changeServerPanelWipe
Saves the wipe as given. Only a wipe that is still waiting can be changed (409 already_started). Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- wipeId (path, required)
- See the downloadable contract for the field schema.
Request body PanelWipeBody
backUpFirst(boolean): True backs up the server once it has stopped and before the wipe changes anything, and the wipe does not go on if the backup cannot be made.categories(list of string): What to remove: map, blueprints, player_data and clans.deletions(list of string): Files deleted at the wipe and not put back: a path, or a name pattern with * and ? in the last name, in the oxide or carbon folder.dueAt(string)files(list of PanelWipeCopyBody): Files put in place at the wipe until the next wipe, which takes them out and puts the originals back.name(string): The name the member knows it by, 1 to 40 characters.pauseRestarts(boolean): True pauses the usual restarts on the wipe's day until the wipe ran.pluginUpdates(list of PanelWipeCopyBody): Plugin files replaced at the wipe and kept; a plugin that does not load gets its earlier file back where the host shows the game's answer.repeat(PanelWipeRepeatBody)saveFolder(string): The server's save folder in its files, for example `server/rust`.startAfter(boolean): False leaves the game stopped at the end.warning(string): The line said in game chat first; absent says nothing.warnings(list of integer): When players are told before the wipe, in seconds before it (each 1 to 3600, at most 5); absent or empty says nothing before it.
Success: 200 PanelWipeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read a server's RCON connection detailsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/rcon
getRconAccess
Asks the server's host where the console (WebRCON) listens, its port and where the password comes from: RustSC's own for a server RustSC starts, or for a server another tool runs the command line, the start script (with its file name), server.cfg or a password the Owner typed. Never returns the password. For a rented server (runBy host) the answer is what its host shows: port, address, gamePort, queryPort and whether a password is known, each absent when the host did not say. Offline is capability_unavailable (host_offline); a host with an older RustSC is capability_unavailable (host_update_needed); no answer in time is dependency_unavailable (host, timed_out). Needs servers.secrets.write, which only the Owner holds.
Workspace permission: servers.secrets.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RconAccessResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Set a server's RCON password or where its console listensPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/rcon
saveRconAccess
For a server RustSC starts: password (8 to 64 characters: English letters, digits, _ . and -, not starting with -) and listen (this_computer or all_networks) are saved on the server's host and used from its next start; a running server keeps its current values until it restarts. Nothing restarts and no firewall rule changes. For a server another tool runs: password is the one that tool uses, kept on the server's host to read its console when RustSC finds none in the tool's own files; listen is refused (validation_failed on /listen) and the tool's own files are never changed. A password that breaks the rules is validation_failed on /password. Audited without the value. Needs servers.secrets.write, which only the Owner holds.
Workspace permission: servers.secrets.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body SaveRconAccessBody
listen(string): `this_computer` or `all_networks`, for a server RustSC starts, from the next start.password(string): The new password.
Success: 200 RconAccessResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Show a server's RCON passwordPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/rcon/reveal
revealRconPassword
Returns the password with the connection details, fetched from the server's host for this request only and never kept by RustSC's cloud. For a server RustSC starts it is the password the next start uses; for a server another tool runs, the one RustSC read from that tool's files or the one the Owner typed. Each reveal is written to the audit log without the value; for a rented server it is the password its host shows. No password known is capability_unavailable (no_password). Needs servers.secrets.write, which only the Owner holds.
Workspace permission: servers.secrets.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RconAccessResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read the status of a rented serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/rented-status
getRentedServerStatus
Asks the server once, only while a page that shows it is open: the server's public query port first (the address the member entered for it), then the game's console where one is set up. state is answering (the figures are the game's own), not_answering (nothing that was set up answered; no figures, and never a stopped server) or not_set (no query address and no console yet). route is console or query. name, players, maxPlayers, map, waiting players, framerate, uptimeSeconds and build are absent when the game did not say. nextRestartAt is the soonest saved restart still waiting, absent when none. queryAddress and queryPort are the saved entry; queryFoundBy names the host when the host gave the address and the member has not typed one. power is running or stopped and absent when it cannot be told. Reads of one server are shared between viewers. 404 for a server that is not a connected rented server. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RentedStatusResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read whether history is kept for a rented serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/rented-status/history
getRentedServerHistory
keepHistory is true while the member has history switched on for the server. Reads one saved setting and asks nothing of the host or the game. 404 for a server that is not a connected rented server. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RentedHistoryResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Switch history on or off for a rented serverPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/rented-status/history
setRentedServerHistory
While keepHistory is true the server's processor, memory and players are recorded every minute and drawn on its Performance tab with gaps where nothing was read; false stops recording and keeps what was recorded until it ages out. Saving sends nothing to the host or the game. Needs servers.config.write.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body RentedHistoryBody
keepHistory(boolean, required): True to record the server's processor, memory and players while nobody looks; false to stop.
Success: 200 RentedHistoryResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Save the query address of a rented serverPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/rented-status/query-address
setRentedServerQueryAddress
Saves, or with a null address clears, the public IPv4 address and query port the member typed for their own game server. 422 on /address (not_ipv4, not_public) or /port (bad_port). Saving sends nothing. Needs servers.config.write.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body RentedQueryAddressBody
address(string): A public IPv4 address, or null to clear the saved one.port(integer): The query port, 1024 to 65535.
Success: 200 RentedQueryAddressResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Check a replacementGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/replacement-plan
getServerReplacementPlan
What Replace would do, written nothing: the host and folder, the platform, the ports the new game would use, one line for each port another server on that host is set up with, and what the portal would and would not push. Query: hostId (default the server's own host) and root. Needs servers.software.manage.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- hostId (query)
- The host that would hold the game; leave it out for the server's own.
- root (query)
- The game folder; leave it out for the server's own folder.
Success: 200 ReplacementPlanResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Read whether a rented server is started again when it stops by itselfGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/start-again
getRentedStartAgain
on is true only after a member saved it on for this server. offered is false where the host has no start RustSC can use or the server has no saved query address, and then it cannot be switched on. held is true while RustSC has stopped trying after 3 starts in 30 minutes. changedAt is absent until a choice was saved.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RentedStartAgainResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Start a rented server again when it stops by itself, or switch that offPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/start-again
setRentedStartAgain
on true saves the choice, false saves it off. Saving calls no host. Once on, a server that was seen running, then stopped by itself while the host reports it stopped, is started through the host's own start, at most 3 times in 30 minutes. A stop through RustSC is never undone. Saving either way ends a hold and starts the count again.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body SetRentedStartAgainBody
on(boolean, required): True starts the server again when it stops by itself; false stops that.
Success: 200 RentedStartAgainResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Choose the time zone of a server's schedulesPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/time-zone
setServerTimeZone
Sets the time zone new schedules of the server use, an IANA id such as Europe/Berlin, or null to use the zone its host reports again. Schedules already saved keep the zone they were saved with. Needs servers.config.write. Answers with the server's schedule time zone. An unknown zone is 422 unknown_time_zone.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body ServerTimeZoneRequestBody
timeZone(string): An IANA zone id such as `Europe/Berlin`, or null to use the host's zone again.
Success: 200 ServerTimeZoneResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read a server's Upkeep settingGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/upkeep
getServerUpkeep
Whether the Upkeep setting is saved for the server, whether players are told (tellPlayers), the first level in hours (lowHours), when players who are away are told by Discord (discordWhen), how many cupboards were read and when. Until it is saved, saved is false and the other values are the ones the form pre-fills. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 UpkeepSettingResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save or switch off a server's Upkeep settingPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/upkeep
setServerUpkeep
on saves the setting and starts tracking cupboards; off removes it. tellPlayers switches alerts to players; lowHours is the first level, 7 to 168 (422 invalid at /lowHours). discordWhen is always (the default) or all_offline, which tells players who are away only once every player authorised on that cupboard is offline (422 invalid at /discordWhen). Nothing is read or sent for a server before the setting is saved. Needs servers.config.write.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body SetUpkeepBody
discordWhen(string): When a player who is away is told by Discord: always (the default) or all_offline, only once every player authorised on that cupboard is offline.lowHours(integer): The first level in hours, 7 to 168.on(boolean, required): True saves the setting; false removes it.tellPlayers(boolean): Whether players are told when a cupboard runs low.
Success: 200 UpkeepSettingResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Workspaces
List my workspacesGET /api/v1/workspaces
listWorkspaces
The workspaces the signed-in account is an active member of, with its permissions in each.
Success: 200 WorkspaceListResponse. Errors use Problem.
Response statuses: 200, 401, default.
Create a workspacePOST /api/v1/workspaces
createWorkspace
Creates a workspace with the preset roles and makes the signed-in account its Owner. Send an Idempotency-Key to repeat safely: a repeat returns the workspace the first request created.
- Idempotency-Key (header)
- Recommended. A new key, for example a UUID, per creation; repeat it only to repeat the same request after a lost response.
Request body CreateWorkspaceRequestBody
name(string, required): The workspace name members see, at most 64 characters with no line breaks or hidden characters (else `too_long` or `control_character`).
Success: 201 WorkspaceResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Read a workspaceGET /api/v1/workspaces/{workspaceId}
getWorkspace
The workspace and the caller's membership in it, with the permissions the caller holds on each server where they differ from the workspace-wide ones (serverPermissions). A workspace the caller is not a member of is not found.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WorkspaceResponse. Errors use Problem.
Response statuses: 200, 401, 404, default.
Rename a workspacePATCH /api/v1/workspaces/{workspaceId}
renameWorkspace
Gives the workspace a new name and returns the workspace. The name rules are those of workspace creation: leading and trailing spaces are removed and the name must not be empty. Needs workspace.manage (Owner and Administrator). The change is audited as workspace.manage.
Workspace permission: workspace.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body RenameWorkspaceRequestBody
name(string, required): The new workspace name members see.
Success: 200 WorkspaceResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Keep a closing workspaceDELETE /api/v1/workspaces/{workspaceId}/closing
cancelWorkspaceClosing
Needs workspace.close (Owner). Refused with 409 admin_workspace_limit when an administrator now manages another workspace, and with 409 closed_with_account for a workspace that closed because its last member deleted their account (keeping that account brings it back).
Workspace permission: workspace.close
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WorkspaceResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, default.
Read what closing a workspace doesGET /api/v1/workspaces/{workspaceId}/closing
getWorkspaceClosing
Needs workspace.close (Owner). Changes nothing.
Workspace permission: workspace.close
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WorkspaceClosingResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Close a workspacePOST /api/v1/workspaces/{workspaceId}/closing
closeWorkspace
Needs workspace.close (Owner). The workspace stops cloud work at once, its hosts disconnect and keep their games running, and its data stays available to download for 30 days, then is deleted. Cancel with DELETE on the same address. Closing a closing workspace changes nothing. Without cancelPlan the request is refused with 409 plan_active and nothing changed. When the payment provider cannot be reached the answer is 503 and nothing changed.
Workspace permission: workspace.close
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- cancelPlan (query)
- See the downloadable contract for the field schema.
Success: 200 WorkspaceResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 503, default.
Download a workspace's dataGET /api/v1/workspaces/{workspaceId}/export
exportWorkspace
Needs workspace.export (Owner); allowed while the workspace is closing. A JSON file (format rustsc.workspace-export, version 1) with the workspace, members, roles, invitations, hosts, servers, configuration, schedules and audit trail. Nothing secret is included.
Workspace permission: workspace.export
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List membersGET /api/v1/workspaces/{workspaceId}/members
listMembers
Active members and their role assignments. Needs members.read.
Workspace permission: members.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 MemberListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read the workspace's sign-in ruleGET /api/v1/workspaces/{workspaceId}/security-policy
getSecurityPolicy
Which ways of signing in members may use here and how long a sign-in lasts, or null for no limit. Needs workspace.read.
Workspace permission: workspace.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 SecurityPolicyResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Replace the workspace's sign-in rulePUT /api/v1/workspaces/{workspaceId}/security-policy
setSecurityPolicy
Replaces the rule as a whole: signInMethods (at least one of passkey, apple, google, discord, or null for every way) and sessionDays (1, 7 or 30, or null). Members who do not meet it sign in again to use this workspace; other workspaces are unaffected. 409 state_conflict with reason policy_blocks_you when the caller's own sign-in would not meet the rule: sign in with an allowed way first. Needs workspace.manage.
Workspace permission: workspace.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body SetSecurityPolicyRequestBody
sessionDays(integer): 1, 7 or 30, or null to keep the account's own session length.signInMethods(list of string): The ways of signing in to allow, at least one, or null for every way.
Success: 200 SecurityPolicyResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Alerts
Clear an acknowledgementDELETE /api/v1/workspaces/{workspaceId}/alert-incidents/{incidentId}/acknowledgement
clearAlertAcknowledgement
Takes the acknowledgement back: the alert is open and unacknowledged again. The history keeps who cleared it and when. Clearing an alert that is not acknowledged changes nothing; an alert that is over is 409 incident_not_acknowledged. Needs alerts.manage on the alert's server.
Workspace permission: alerts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- incidentId (path, required)
- See the downloadable contract for the field schema.
Success: 200 MobileIncidentAcknowledgementResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Acknowledge an alertPOST /api/v1/workspaces/{workspaceId}/alert-incidents/{incidentId}/acknowledgement
acknowledgeAlertIncident
Stops the reminders of an open alert. The optional comment (at most 500 characters) is kept in the alert's history and shown while it stays acknowledged. Acknowledging an acknowledged alert changes nothing; an alert that is over is 409 incident_not_open. Needs alerts.manage on the alert's server.
Workspace permission: alerts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- incidentId (path, required)
- See the downloadable contract for the field schema.
Success: 200 MobileIncidentAcknowledgementResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read the alert managerGET /api/v1/workspaces/{workspaceId}/alert-manager
getAlertManager
Every alert with its switch, reminder, wait and limit as they are now, what the template they began from said (and which fields differ), the workspace's channels (for a caller who holds integrations.read) and how many hosts differ for the four alerts a host decides. A workspace that never saved its settings shows the recommended ones as a draft (chosen false): nothing is applied and no alert fires until a member saves. Needs alerts.read.
Workspace permission: alerts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 AlertManagerResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save alert settingsPUT /api/v1/workspaces/{workspaceId}/alert-manager
saveAlertManager
Replaces each alert named in kinds as a whole and leaves the others. A number left out is the standard one. An alert a host decides (low disk space, processor, memory, disk) is written to every host only when this save changed it. revision, when sent, must be the one read: otherwise 409 settings_changed. A value outside its bounds is refused with 422 at /kinds/{kind}/{field} (out_of_range, invalid, no_server). channels may name Discord channels (rte_) and webhooks (whk_) and may be empty; browser and phone say whether members' browsers and phones get the alert; servers limits an event about a server, or the alert server_not_restarted, to some servers (allServers true is every server; a server left out is not checked). pingRoleId (a Discord role ID, 17 to 20 digits) is the role the first notice of an alert about a server pings in Discord, with pingRoleName for the screen; left out pings nobody; only for an entry whose offersPing is true (422 invalid at /kinds/{kind}/pingRoleId otherwise). The words of every alert are RustSC's and fixed. A save that changes nothing keeps the revision, except the first save of a workspace that never chose: that stores the settings as they are, which turns alerts on. Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body AlertManagerSaveBody
kinds(list of AlertKindBody, required)revision(integer): The revision that was read; a save on an older one is refused with `settings_changed`.
Success: 200 AlertManagerResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Apply a templatePOST /api/v1/workspaces/{workspaceId}/alert-manager/apply
applyAlertTemplate
Copies the template's values over every alert, writes the four host alerts to every host, and keeps the template's name and version so the manager can show what was changed afterwards. Channels are untouched. templateVersion is the version that was previewed: if the template has changed since, nothing is applied and the answer is 409 template_changed. Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body AlertTemplateApplyBody
templateId(string, required)templateVersion(integer, required): The template's version in the preview; a different one is refused with `template_changed`.
Success: 200 AlertManagerResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Send a test card of an alert to DiscordPOST /api/v1/workspaces/{workspaceId}/alert-manager/discord-posts/{kind}/test
testAlertDiscordPost
Posts RustSC's card for the alert once in one Discord channel (channel, rte_), filled in with example values, the workspace's first server's name and the time now, so the channel shows exactly what it will. The card's words are RustSC's and cannot be changed. It is a real post: the role the alert pings (pingRoleId) is pinged. Nothing is changed. The answer says sent, or a stable problem code. An alert that has no card (a host's alerts, the Discord link events) is 404. Needs alerts.settings.manage, which only an Owner holds; 503 dependency_unavailable (alert_routes) where the service has no secret store.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- kind (path, required)
- See the downloadable contract for the field schema.
Request body DiscordPostTestBody
channel(string, required): The Discord channel to post in (`rte_`).
Success: 200 DiscordPostTestResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Preview applying a templatePOST /api/v1/workspaces/{workspaceId}/alert-manager/preview
previewAlertTemplate
Says what applying the template would change, field by field, and how many hosts would be set to match, without changing anything. Needs alerts.read.
Workspace permission: alerts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body AlertTemplateChoiceBody
templateId(string, required): `standard`, `essentials`, `everything` or a member-made template's ID (`atp_`).
Success: 200 AlertPreviewResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List alert routesGET /api/v1/workspaces/{workspaceId}/alert-routes
listAlertRoutes
The routes that carry the workspace's alerts, oldest first: for each the Discord channel (channelId and channelName), the kinds of alert it takes, whether it is on, whether it needsReconnect (it has no channel and sends nothing until one is picked) and the newest finished delivery (so a channel the bot can no longer post in shows here). canManage says whether the caller may change routes. Needs integrations.read.
Workspace permission: integrations.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 AlertRouteListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Send alerts to a Discord channelPOST /api/v1/workspaces/{workspaceId}/alert-routes
createAlertRoute
Adds a route: channelId is a channel from listDiscordPostChannels (checked again against the workspace's own connected Discord server, so a channel of another server is refused), categories what it takes (availability, operations, resources; at least one) and enabled whether it sends now (default true). A new route sends from the next alert on; nothing already open is replayed. A value that cannot be used is refused: 422 at /channelId (required, channel_not_found, channel_not_text), no_category or invalid at /categories, too_long at /name; 409 state_conflict with reason not_connected, bot_not_in_server, missing_permission (state names the channel and what is missing) or discord_unavailable. An optional name (at most 60 characters) is how Alert settings lists the channel. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body AlertRouteCreateBody
categories(list of string, required): What the route sends: any of `availability` (a server or host offline or crashed), `operations` (a backup, update or start that failed) and `resources` (low disk space, high CPU...channelId(string, required): The channel's Discord ID, from the list of `listDiscordPostChannels`.enabled(boolean): Whether the route sends now.name(string): A name for the channel, shown in the menus of Alert settings (at most 60 characters).showSteamIds(boolean): Whether this channel's alerts add each player's Steam ID and profile link after the name.
Success: 201 AlertRouteResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Send a test alert to a picked channelPOST /api/v1/workspaces/{workspaceId}/alert-routes/test
testAlertChannel
Posts one short test card in the channel channelId, so a member sees the bot can post there before saving it. The channel is checked against the workspace's own connected Discord server first and a permission the bot lacks is named in missing. Changes nothing. The answer says sent, or a stable problem code. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body AlertRouteTestBody
channelId(string): The channel to test, for example one just picked and not yet saved.
Success: 200 AlertRouteTestResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Remove an alert routeDELETE /api/v1/workspaces/{workspaceId}/alert-routes/{routeId}
deleteAlertRoute
Removes the route; a link it still holds from before the bot became the only way to post is deleted. Alerts waiting to go to it are not sent. The messages already in the channel stay; delete them in Discord. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- routeId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Change an alert routePUT /api/v1/workspaces/{workspaceId}/alert-routes/{routeId}
changeAlertRoute
Replaces the route's categories and switch (enabled default true). A channelId moves the route to another channel, or reconnects a route that needsReconnect (absent keeps the saved channel); it is checked as a new route's is. A name replaces the saved name (blank removes it; absent keeps it; 422 too_long at /name). A change that alters nothing keeps the revision. The delivery reads the route when it sends, so a route switched off or moved sends nothing to the old channel from then on. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- routeId (path, required)
- See the downloadable contract for the field schema.
Request body AlertRouteChangeBody
categories(list of string, required): What the route sends; at least one of `availability`, `operations` and `resources`.channelId(string): A different channel for the route, or the channel that reconnects a route that needs it; absent keeps the saved one.enabled(boolean): Whether the route sends.name(string): A new name for the channel; absent keeps the saved name, blank removes it.showSteamIds(boolean): Whether this channel's alerts add each player's Steam ID and profile link after the name; absent keeps the saved choice.
Success: 200 AlertRouteResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Send a test alert to a saved routePOST /api/v1/workspaces/{workspaceId}/alert-routes/{routeId}/test
testAlertRoute
Posts one short test card in the route's channel, or in the channelId of the body when one is sent. Changes nothing. The answer says sent, or a stable problem code (reconnect when the route has no channel yet). Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- routeId (path, required)
- See the downloadable contract for the field schema.
Request body AlertRouteTestBody
channelId(string): The channel to test, for example one just picked and not yet saved.
Success: 200 AlertRouteTestResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List alert templatesGET /api/v1/workspaces/{workspaceId}/alert-templates
listAlertTemplates
The built-in templates (standard, essentials, everything), then the ones members saved, each with its version and how many alerts it switches on. Needs alerts.read.
Workspace permission: alerts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 AlertTemplateListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save the current settings as a templatePOST /api/v1/workspaces/{workspaceId}/alert-templates
saveAlertTemplate
Saves the workspace's current alert settings (never its channels) under a name that the workspace's owners can apply. The name is used once in a workspace, ignoring capitals (422 name_taken at /name); at most 20 templates (409 too_many). Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body AlertTemplateSaveBody
name(string, required)
Success: 201 AlertTemplateResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Remove a templateDELETE /api/v1/workspaces/{workspaceId}/alert-templates/{templateId}
deleteAlertTemplate
Removes a member-made template. Workspaces that applied it keep their settings. A built-in template cannot be removed (409 built_in_template). Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- templateId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Rename a template or update it from the current settingsPUT /api/v1/workspaces/{workspaceId}/alert-templates/{templateId}
changeAlertTemplate
name renames the template; fromCurrent true replaces its values with the workspace's current settings and raises its version. No workspace's settings change: the manager tells a workspace that applied it that a newer version exists. A built-in template cannot be changed (409 built_in_template). Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- templateId (path, required)
- See the downloadable contract for the field schema.
Request body AlertTemplateUpdateBody
fromCurrent(boolean): True replaces the template's values with the workspace's current settings and raises its version.name(string)
Success: 200 AlertTemplateResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List open resource alertsGET /api/v1/workspaces/{workspaceId}/alerts
listResourceAlerts
The low disk space, CPU, memory and disk queue alerts that are open now, oldest first, each with a plain message and, for low disk space, the one next step. Needs alerts.read.
Workspace permission: alerts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ResourceAlertListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List my browsers for alertsGET /api/v1/workspaces/{workspaceId}/browser-notifications
listBrowserNotifications
The caller's own browsers in the workspace, oldest first: for each its name, the kinds of alert it gets, whether it is on and, when RustSC turned it off, why. The push address and keys are never returned. Any active member.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BrowserNotificationsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Turn on alerts in a browserPOST /api/v1/workspaces/{workspaceId}/browser-notifications
turnOnBrowserNotifications
Turning notifications on again in the same browser finds its route, refreshes the keys and turns it on. A new route gets alerts from the next one on. A value that cannot be used is refused with 422 at its field: invalid_push_subscription at /endpoint, no_category or invalid at /categories; 409 too_many_browsers when the member has as many browsers as allowed. Any active member.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body BrowserSubscribeBody
auth(string, required)categories(list of string, required): What it gets: any of `availability`, `operations` and `resources`.endpoint(string, required): Stored as a protected secret and never returned.label(string): What this browser is called in the list, for example "Chrome on Windows".p256dh(string, required)
Success: 201 BrowserResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Turn off alerts in a browser for goodDELETE /api/v1/workspaces/{workspaceId}/browser-notifications/{browserId}
removeBrowserNotifications
Removes the browser's route and deletes its stored push address and keys. Alerts waiting for it are not shown. Any active member, for their own browsers only.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- browserId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Change a browser's alertsPUT /api/v1/workspaces/{workspaceId}/browser-notifications/{browserId}
changeBrowserNotifications
Replaces the kinds a browser gets and its switch (enabled default true). A change that alters nothing keeps the route as it is. Any active member, for their own browsers only.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- browserId (path, required)
- See the downloadable contract for the field schema.
Request body BrowserChangeBody
categories(list of string, required): What it gets; at least one of `availability`, `operations` and `resources`.enabled(boolean): Whether it gets alerts.
Success: 200 BrowserResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Send a test notificationPOST /api/v1/workspaces/{workspaceId}/browser-notifications/{browserId}/test
testBrowserNotifications
Sends one short test notification to the browser through the same path as an alert. It changes nothing: no alert and no failure count. The answer says delivered (the push service accepted it), or a stable problem code. Any active member, for their own browsers only.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- browserId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BrowserTestResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List chat wordsGET /api/v1/workspaces/{workspaceId}/chat-words
listChatWords
The words and phrases that alert when said in a server's public chat, oldest first, with the bounds of a word. Needs alerts.read.
Workspace permission: alerts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ChatWordListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Add a chat wordPOST /api/v1/workspaces/{workspaceId}/chat-words
createChatWord
Adds a word or phrase. phrase is 2 to 60 characters (422 required, too_short, too_long at /phrase), mode is word or contains (422 invalid at /mode), servers names the servers it covers unless allServers (422 no_server, invalid at /servers). A phrase already listed in any capitals is refused with 409 phrase_taken; at most 50 words (409 too_many_chat_words). A word alerts only in public chat, from the next message on, and only while the Chat words alert is on. Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body ChatWordBody
allServers(boolean): True (the default) covers every server; false needs `servers`.enabled(boolean): Default true.mode(string, required): `word` or `contains`.phrase(string, required)servers(list of string): The servers (`srv_`) the word covers when `allServers` is false.
Success: 201 ChatWordResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Remove a chat wordDELETE /api/v1/workspaces/{workspaceId}/chat-words/{wordId}
deleteChatWord
Removes the word. Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- wordId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Change a chat wordPUT /api/v1/workspaces/{workspaceId}/chat-words/{wordId}
changeChatWord
Replaces the word as a whole with the same checks as adding one. A save that changes nothing keeps the revision. Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- wordId (path, required)
- See the downloadable contract for the field schema.
Request body ChatWordBody
allServers(boolean): True (the default) covers every server; false needs `servers`.enabled(boolean): Default true.mode(string, required): `word` or `contains`.phrase(string, required)servers(list of string): The servers (`srv_`) the word covers when `allServers` is false.
Success: 200 ChatWordResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List console wordsGET /api/v1/workspaces/{workspaceId}/console-words
listConsoleWords
The words and patterns that alert when a server's console prints them, oldest first, with the bounds of a word. Needs alerts.read.
Workspace permission: alerts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ConsoleWordListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Add a console wordPOST /api/v1/workspaces/{workspaceId}/console-words
createConsoleWord
Adds a word, phrase or pattern. phrase is 2 to 60 characters, 2 to 100 for a pattern (422 required, too_short, too_long, invalid_pattern, too_big, matches_everything at /phrase), mode is word, contains or pattern (422 invalid at /mode), servers names the servers it covers unless allServers (422 no_server, invalid at /servers). A phrase already listed in any capitals is refused with 409 phrase_taken; at most 25 words (409 too_many_console_words). A word is matched by the server's host over its console, from the next line on, and only while the Console words alert is on. Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body ConsoleWordBody
allServers(boolean): True (the default) covers every server; false needs `servers`.enabled(boolean): Default true.mode(string, required): `word`, `contains` or `pattern`.phrase(string, required)servers(list of string): The servers (`srv_`) the word covers when `allServers` is false.
Success: 201 ConsoleWordResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Remove a console wordDELETE /api/v1/workspaces/{workspaceId}/console-words/{wordId}
deleteConsoleWord
Removes the word. Removing the last word stops all matching on the hosts. Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- wordId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Change a console wordPUT /api/v1/workspaces/{workspaceId}/console-words/{wordId}
changeConsoleWord
Replaces the word as a whole with the same checks as adding one. A save that changes nothing keeps the revision. Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- wordId (path, required)
- See the downloadable contract for the field schema.
Request body ConsoleWordBody
allServers(boolean): True (the default) covers every server; false needs `servers`.enabled(boolean): Default true.mode(string, required): `word`, `contains` or `pattern`.phrase(string, required)servers(list of string): The servers (`srv_`) the word covers when `allServers` is false.
Success: 200 ConsoleWordResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Save a host's alert settingsPUT /api/v1/workspaces/{workspaceId}/hosts/{hostId}/alert-settings
saveHostAlertSettings
Saves the switches and limits of the host as the next revision and sends them to the host, which keeps alerting by them even when the cloud is unreachable. A save that changes nothing keeps the revision. Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Request body SaveHostAlertSettingsBody
cpu(AlertRuleSettingBody, required)diskEnabled(boolean, required): The low disk space alert; on until switched off.diskQueue(AlertRuleSettingBody, required)memory(AlertRuleSettingBody, required)
Success: 200 HostAlertSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read a host's alert settings and open alertsGET /api/v1/workspaces/{workspaceId}/hosts/{hostId}/alerts
getHostAlerts
The low disk space alert is on until switched off; the CPU, memory and disk queue alerts are off until a member turns them on. alerts lists what is open on the host and its servers. supported is false where the host does not measure resources yet. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Success: 200 HostAlertsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read your notification settingsGET /api/v1/workspaces/{workspaceId}/notification-settings
getMemberNotifications
Where and when you are told: the alerts sent to your own browsers (browserAlerts) and phones (phoneAlerts), empty until you choose, your quiet hours and their time zone, the notification template you follow (if any) and the short note after a change you did not make, with every alert you can choose and the templates an owner made. These narrow what reaches your own devices and nothing else: the workspace's alert settings and its shared channels are the owner's. Any active member reads their own.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 MemberNotificationResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save your notification settingsPUT /api/v1/workspaces/{workspaceId}/notification-settings
saveMemberNotifications
Replaces your settings as a whole. browserAlerts and phoneAlerts name alert keys (422 invalid at /values/browserAlerts/{index} or /values/phoneAlerts/{index}); quiet times are hh:mm (422 invalid at /values/quiet/start or /end, same_time when they are equal while quiet hours are on); timeZone is a time zone such as Europe/London (422 invalid at /timeZone) and is always your own. revision, when sent, must be the one read: otherwise 409 settings_changed. While you follow a template its values are yours: a save that changes them is refused with 409 following_template (stop following first). A save that changes nothing keeps the revision. Any active member saves their own.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body MemberNotificationSaveBody
revision(integer): The revision that was read; a save on an older one is refused with `settings_changed`.timeDisplay(string): "Show times in": `own` shows each time in its own zone (the schedule's or the server's), `mine` shows times in `timeZone`; left out keeps the current choice.timeZone(string): The time zone quiet hours are counted in (for example `Europe/London`); left out keeps the current one.values(NotificationValuesBody, required)
Success: 200 MemberNotificationResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Use a notification templatePOST /api/v1/workspaces/{workspaceId}/notification-settings/adopt
adoptNotificationTemplate
follow false copies the template's values over your settings once and leaves you free of it; true keeps your settings equal to the template's until you stop following, and tells you in a short note when an owner changes it. version is the version you looked at: if the template has changed since, nothing is adopted and the answer is 409 template_changed. Nothing about a template ever changes your settings unless you chose follow. Any active member adopts for themselves.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body NotificationTemplateAdoptBody
follow(boolean, required): False copies the values once; true keeps the member's settings equal to the template's until they stop following.templateId(string, required): The template's ID (`ntp_`).version(integer, required): The template's version that was looked at; a different one is refused with `template_changed`.
Success: 200 MemberNotificationResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Stop following a notification templatePOST /api/v1/workspaces/{workspaceId}/notification-settings/stop-following
stopFollowingNotificationTemplate
Keeps your current values and stops the template from changing them. Answers with your settings; nothing changes if you follow no template. Any active member.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 MemberNotificationResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Make a notification templatePOST /api/v1/workspaces/{workspaceId}/notification-templates
createNotificationTemplate
Makes a template of the values a member's own notification settings carry. The name is used once in a workspace, ignoring capitals (422 name_taken at /name); at most 20 templates (409 too_many). A new template changes nobody's settings. Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body NotificationTemplateCreateBody
name(string, required)values(NotificationValuesBody, required)
Success: 201 NotificationTemplateResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Remove a notification templateDELETE /api/v1/workspaces/{workspaceId}/notification-templates/{templateId}
deleteNotificationTemplate
Members who copied it keep their values. Members who followed it stop following, keep the values they had and get a short note. Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- templateId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Rename or change a notification templatePUT /api/v1/workspaces/{workspaceId}/notification-templates/{templateId}
changeNotificationTemplate
name renames the template. values replaces its values, raises its version and, in the same step, changes every member who follows it (each gets a short note); members who copied it or never adopted it are not touched. Values equal to the old ones change nothing. Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- templateId (path, required)
- See the downloadable contract for the field schema.
Request body NotificationTemplateChangeBody
name(string)values(NotificationValuesBody)
Success: 200 NotificationTemplateResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List notifications sentGET /api/v1/workspaces/{workspaceId}/notifications
listNotifications
The notifications themselves, not the open alerts, newest first: when, where (the channel and a place named in words, a link only by its last four characters), the status (waiting, sent, failed with why, skipped with why, or unsure when the post may have arrived), the words of the notification and the alerts it is tied to. An owner reads every notification of the workspace; any other member reads the ones addressed to them (their own browsers and phones). Reaches back as far as notifications are kept, 90 days. alert is an alert key; channel is discord, webhook, browser or phone; state is waiting, sent, failed, skipped or unsure; from and to are times (422 invalid, before_from). limit is 1 to 100 (default 50); cursor is the nextCursor of the page before. Needs an active membership.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- alert (query)
- See the downloadable contract for the field schema.
- channel (query)
- See the downloadable contract for the field schema.
- state (query)
- See the downloadable contract for the field schema.
- from (query)
- See the downloadable contract for the field schema.
- to (query)
- See the downloadable contract for the field schema.
- cursor (query)
- See the downloadable contract for the field schema.
- limit (query)
- See the downloadable contract for the field schema.
Success: 200 NotificationLogResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
List quiet timesGET /api/v1/workspaces/{workspaceId}/quiet-times
listQuietTimes
The quiet times that are running or still to come, soonest first: periods when alerts of some kinds are not sent for the workspace, a host or a server. Alert kinds are availability (a server or host offline or crashed), operations (a backup, update or start that failed) and resources (low disk space, high CPU or memory use). Needs alerts.read.
Workspace permission: alerts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 QuietTimeListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Plan a quiet timePOST /api/v1/workspaces/{workspaceId}/quiet-times
createQuietTime
Silences the given kinds of alert (all three when categories is empty) for the workspace, one host (scope host) or one server (scope server) from startsAt (default now) to endsAt. endsAt must be in the future and after the start (422 at /endsAt: before_start, in_past). A host or server of another workspace is 404. Needs servers.lifecycle (whoever can restart a server) on the server, or on the workspace for a host or the whole workspace.
Workspace permission: servers.lifecycle
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body QuietTimeCreateBody
categories(list of string): What is silenced: any of `availability`, `operations` and `resources`.endsAt(string, required): When it ends (RFC 3339).scope(string, required): `workspace` (every server and host), `host` (one host) or `server`.startsAt(string): When the quiet time starts (RFC 3339).targetId(string): The host (`host_...`) or server (`srv_...`) for those scopes; absent for `workspace`.
Success: 201 QuietTimeResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
End a quiet timeDELETE /api/v1/workspaces/{workspaceId}/quiet-times/{quietTimeId}
endQuietTime
Ends a running quiet time now, or withdraws one that has not started (it is gone). An ended one is 409 window_ended. Needs the permission creating it needs.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- quietTimeId (path, required)
- See the downloadable contract for the field schema.
Success: 200 QuietTimeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Change a quiet timePUT /api/v1/workspaces/{workspaceId}/quiet-times/{quietTimeId}
changeQuietTime
Replaces what the quiet time silences and its end, and its start while it has not started. The scope cannot change. revision, when sent, must be the one read: otherwise 409 revision_conflict. An ended quiet time is 409 window_ended. Needs the permission creating it needs.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- quietTimeId (path, required)
- See the downloadable contract for the field schema.
Request body QuietTimeChangeBody
categories(list of string): What is silenced; empty silences all three kinds.endsAt(string, required)revision(integer): The revision that was read; a different one is answered with 409.startsAt(string): The new start.
Success: 200 QuietTimeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Switch a quiet time offPOST /api/v1/workspaces/{workspaceId}/quiet-times/{quietTimeId}/actions/pause
pauseQuietTime
Keeps the quiet time, its place, kinds and times, but it silences nothing until resumeQuietTime: alerts that arrive meanwhile are sent as usual. Repeating it changes nothing. An ended one is 409 window_ended. Needs the permission creating it needs.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- quietTimeId (path, required)
- See the downloadable contract for the field schema.
Success: 200 QuietTimeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Switch a quiet time onPOST /api/v1/workspaces/{workspaceId}/quiet-times/{quietTimeId}/actions/resume
resumeQuietTime
Makes a quiet time that was switched off silence alerts again, for the rest of its time. Repeating it changes nothing. An ended one is 409 window_ended. Needs the permission creating it needs.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- quietTimeId (path, required)
- See the downloadable contract for the field schema.
Success: 200 QuietTimeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Save a server's alert settingsPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/alert-settings
saveServerAlertSettings
Saves the server's CPU and memory switches and thresholds, written to the host's installation like the host's own. The server's alerts apply only while it is ready, never while it starts, restarts or updates. Needs alerts.settings.manage, which only an Owner holds.
Workspace permission: alerts.settings.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body SaveServerAlertSettingsBody
cpu(AlertRuleSettingBody, required)memory(AlertRuleSettingBody, required)
Success: 200 ServerAlertSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read a server's alert settings and the alerts that concern itGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/alerts
getServerAlerts
The server's own CPU and memory alerts (off until switched on), the alerts open on it, and the host's alerts that name it: low disk space on a disk holding its folders, and CPU, memory or disk queue of a host it shares. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ServerAlertsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List webhooksGET /api/v1/workspaces/{workspaceId}/webhooks
listWebhooks
The workspace's webhooks, oldest first: for each the name, the kinds of alert it takes, whether it is on or paused and the newest delivery (so an address that stopped working shows here). The address and the signing key are never returned. canManage says whether the caller may change webhooks. Needs integrations.read.
Workspace permission: integrations.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WebhookListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Add a webhookPOST /api/v1/workspaces/{workspaceId}/webhooks
createWebhook
Adds a webhook: url is the address to send alerts to (https, a public name; the whole address is kept secret), label what you call it (optional), categories what it takes (availability, operations, resources; at least one) and enabled whether it sends now (default true). The answer carries the signing key, shown this once: use it as the Standard Webhooks secret to verify the webhook-signature header. A new webhook sends from the next alert on; nothing already open is replayed. A value that cannot be used is refused with 422 at its field: invalid_webhook_address at /url, no_category or invalid at /categories. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body WebhookCreateBody
categories(list of string, required): What the webhook gets: any of `availability`, `operations` and `resources`.enabled(boolean): Whether it sends now.label(string): What you call it, for example "Support bot".url(string, required): The address RustSC sends alerts to: `https://`, a public name and no sign-in in it.
Success: 201 WebhookKeyResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Show what a webhook receivesGET /api/v1/workspaces/{workspaceId}/webhooks/sample
previewWebhook
The body and headers of a test delivery, built by the same code as a real one, so a receiver can be written before anything is saved. Makes no connection. The body is documented as the WebhookEvent schema. Needs integrations.read.
Workspace permission: integrations.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WebhookSampleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Remove a webhookDELETE /api/v1/workspaces/{workspaceId}/webhooks/{webhookId}
deleteWebhook
Removes the webhook, its delivery log and its stored address and signing keys. Alerts waiting to go to it are not sent. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- webhookId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Change a webhookPUT /api/v1/workspaces/{workspaceId}/webhooks/{webhookId}
changeWebhook
Replaces the webhook's categories and switch (enabled default true), and its name and address when given (absent keeps them). Turning a paused webhook on resumes it. A change that alters nothing keeps the revision. The delivery reads the webhook when it sends, so a webhook switched off or given a new address sends nothing to the old one from then on. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- webhookId (path, required)
- See the downloadable contract for the field schema.
Request body WebhookChangeBody
categories(list of string, required): What the webhook gets; at least one of `availability`, `operations` and `resources`.enabled(boolean): Whether it sends.label(string): A new name; absent keeps the saved one.url(string): A different address; absent keeps the saved one.
Success: 200 WebhookResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Show a webhook's delivery logGET /api/v1/workspaces/{workspaceId}/webhooks/{webhookId}/deliveries
listWebhookDeliveries
The newest deliveries and tests of one webhook, newest first, each with how it ended and a stable problem code when it did not arrive. Never a body, header or address. Needs integrations.read.
Workspace permission: integrations.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- webhookId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WebhookDeliveriesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Make a new signing keyPOST /api/v1/workspaces/{workspaceId}/webhooks/{webhookId}/rotate-key
rotateWebhookKey
Makes a new signing key, the recovery for a key that was lost or leaked. The new key signs from now on and is returned this once; the old key keeps signing alongside it for the overlap (oldKeyValidUntil), so a receiver can switch without missing an alert. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- webhookId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WebhookKeyResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Send a test deliveryPOST /api/v1/workspaces/{workspaceId}/webhooks/{webhookId}/test
testWebhook
Sends one signed test to the saved address, built and sent like a real alert and marked type test and synthetic true. It changes nothing: no alert, no game work, and neither the failure count nor the switch. The answer says delivered, or a stable problem code. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- webhookId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WebhookTestResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Integration keys
List integration keysGET /api/v1/workspaces/{workspaceId}/api-keys
listApiKeys
The workspace's keys that are not revoked, newest first, with who made each, what it may do and when it was last used. An expired key stays listed. Never a secret. Needs apikeys.manage.
Workspace permission: apikeys.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ApiKeyListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Make an integration keyPOST /api/v1/workspaces/{workspaceId}/api-keys
createApiKey
Makes a key and returns its text once in secret. The key does what you can do, no more, as your permissions are when it is used: access read looks only, read_write can change things too. serverIds limits it to those servers, null or empty is the whole workspace. expiresInDays is 30, 90 or 365, or null for a key that never expires. agent true makes a key for an AI assistant or an unattended agent, which the remote MCP endpoint (/mcp) accepts as well as the API; it must expire, so expiresInDays is 30 or 90. A key can make a key only if it covers the whole workspace with read_write; the new one covers no more and does not last longer. A repeat with the same Idempotency-Key returns the key without its secret. Needs apikeys.manage.
Workspace permission: apikeys.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body CreateApiKeyBody
access(string, required): `read` or `read_write`.agent(boolean): True to make a key for an AI assistant or an unattended agent (the remote MCP endpoint accepts it).allServers(boolean): For an `agent` key only: true to let it reach every server, those added later too.expiresInDays(integer, required): Days until the key stops working: 30, 90 or 365; null for a key that does not expire.name(string, required): A name to recognise the key by, 1 to 60 characters.role(string): The role of an agent key: `viewer`, `moderator`, `operator`, `administrator` or `owner`.serverIds(list of string, required): The servers the key covers; null or empty for the whole workspace.
Success: 201 CreatedApiKeyResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Revoke an integration keyDELETE /api/v1/workspaces/{workspaceId}/api-keys/{keyId}
revokeApiKey
The key stops working at the next request. Revoking a revoked key changes nothing. Needs apikeys.manage.
Workspace permission: apikeys.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- keyId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Choose what an agent key asks firstPUT /api/v1/workspaces/{workspaceId}/api-keys/{keyId}/ask-first
changeApiKeyAskFirst
Switches the two questions of an agent key on or off, the same two a connected assistant has: risky actions (wipes, deleting, restoring, long ban lists, file writes, plugin install or removal) and free-form console commands. Both are on when an agent key is made and wait for your approval in the portal; a key that runs unattended simply waits there and the request expires. Switching one off lets that key do those things without asking, which is your choice and your risk. Needs apikeys.manage. Only a person's own session changes it: a key never does. A plain key has no such questions (404 not_found).
Workspace permission: apikeys.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- keyId (path, required)
- See the downloadable contract for the field schema.
Request body AssistantAskFirstBody
askBeforeConsole(boolean, required): False to let this assistant run free-form console commands without asking.askBeforeRisky(boolean, required): False to let this assistant run wipes, deleting, restoring, long ban lists, file writes and plugin install or removal without asking.
Success: 200 ApiKeyResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Choose the servers an agent key reachesPUT /api/v1/workspaces/{workspaceId}/api-keys/{keyId}/servers
setApiKeyServers
Sets which servers an agent key can reach, as a whole: allServers true for every server (servers added later too), or serverIds for only those (an empty list is no server). Needs apikeys.manage. Only a person's own session changes it: a key never does. A plain key is fixed when it is made (404 not_found).
Workspace permission: apikeys.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- keyId (path, required)
- See the downloadable contract for the field schema.
Request body SetAssistantServersBody
allServers(boolean): True for every server of the workspace, those added later too.serverIds(list of string): The servers when `allServers` is false.
Success: 200 ApiKeyResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Audit
List audit recordsGET /api/v1/workspaces/{workspaceId}/audit-records
listAuditRecords
The workspace audit trail, newest first: who authorized or performed what, on which target, with which outcome, and the operation and chain it belongs to. Narrow it with targetId (for example a server or host), operationId (an operation and its bulk children), correlationId or outcome (repeat it for several). Needs audit.read.
Workspace permission: audit.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- targetId (query)
- Only records about this target, for example srv_01jb8z3k4q7v9w2x5y6z8a0b1c or host_01jb8z3k4q7v9w2x5y6z8a0b1c.
- operationId (query)
- Only records of this operation and, for a bulk parent, of its children.
- correlationId (query)
- Only records of this chain, the correlationId of another record.
- outcome (query)
- Only these outcomes: allowed, denied, succeeded, failed, cancelled or outcome_unknown; repeat the parameter for several.
- assistantId (query)
- Only what this AI assistant did or asked for: the ID of one of its connections or agent keys.
- limit (query)
- Page size.
- cursor (query)
- The nextCursor of the previous page, with the same filters.
Success: 200 AuditRecordListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Download the audit trailGET /api/v1/workspaces/{workspaceId}/audit-records/export
exportAuditRecords
The audit trail as a file, newest first, every record that matches the same filters as the list (targetId, operationId, correlationId, outcome); no page size or cursor, the file holds them all. format is csv (the default; a byte order mark, one row per record, the details as JSON in the last column) or json (an array of the same records the list returns). The records are the ones the list shows, with the same redaction. A cell that starts with = + - or @ gets a leading quote. The download is recorded in the audit trail (audit.export, with the format and the filters) before the first record is read. Needs audit.read.
Workspace permission: audit.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- format (query)
- csv (the default) or json.
- targetId (query)
- Only records about this target, as in the list.
- operationId (query)
- Only records of this operation and, for a bulk parent, of its children.
- correlationId (query)
- Only records of this chain.
- assistantId (query)
- Only what this AI assistant did or asked for, as in the list.
- outcome (query)
- Only these outcomes, as in the list; repeat the parameter for several.
Success: 200. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Server backups
Read whether a backup export can be downloadedGET /api/v1/workspaces/{workspaceId}/backup-exports/{artifactId}
getBackupExport
state is ready, waiting or expired; expiresAt is when the file stops being available. Only the member who asked sees it. Needs backups.export.
Workspace permission: backups.export
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- artifactId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BackupExportResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Download a backup exportGET /api/v1/workspaces/{workspaceId}/backup-exports/{artifactId}/download
downloadBackupExport
Redeems the link made by makeBackupExportDownloadLink: the zip, once, for the member it was made for. Needs backups.export.
Workspace permission: backups.export
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- artifactId (path, required)
- See the downloadable contract for the field schema.
- grant (query)
- See the downloadable contract for the field schema.
Success: 200. Errors use Problem.
Response statuses: 200, 404, default.
Make a download link for a backup exportPOST /api/v1/workspaces/{workspaceId}/backup-exports/{artifactId}/download-link
makeBackupExportDownloadLink
Returns a link that works once, for the member who asks, for 5 minutes. Follow it to download the zip. Needs backups.export.
Workspace permission: backups.export
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- artifactId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BackupExportLinkResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read backup protection statusGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/backup-policy
getServerBackupPolicy
The policy last reported by the current installation, separately from pending or failed changes. Unknown is not disabled. Needs backups.read.
Workspace permission: backups.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BackupPolicyResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change backup protectionPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/backup-policy
setServerBackupPolicy
Sets whether to take a backup before starting the server. Send expectedRevision from the last read, including zero. Follow the operation to confirm the change. If it returns revision_conflict, read the current settings before retrying. Needs backups.manage.
Workspace permission: backups.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body SetBackupPolicyBody
admission(AdmissionBody)enabled(boolean, required)expectedRevision(integer, required): The last applied host policy revision, including zero; not an operation or configuration ETag.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read the host's backup protection settingPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/backup-policy/refresh
refreshServerBackupPolicy
An observable read operation on the current installation. Returns disabled revision zero for an unconfigured host policy. Does not change the setting. Needs backups.read.
Workspace permission: backups.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RefreshBackupPolicyBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read how many backups a server keepsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/backup-settings
getServerBackupSettings
keep is the number of backups the host keeps (0: every backup); after every backup the host removes the older ones beyond it, newest kept first in the order they were taken, and never the newest backup that restores whole. There is no largest number. makeRoom (off unless the member turned it on) says whether the host also removes old logs and then the oldest backups that are not protected when the disk is nearly full; limitGb is the most the backups may use (null: no limit); storedCount, storedBytes and newestBytes say what they use now. change is a change the host has not applied yet or that failed; cleanUp is the newest Clean up old files. Needs backups.read.
Workspace permission: backups.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BackupSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change how many backups a server keepsPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/backup-settings
setServerBackupRetention
One operation on the server's host. keep is a whole number of minimum or more (no largest number), 0 to keep every backup, or null for the default; makeRoom (default false) and limitGb (a whole number of GB from minimumLimitGb to maximumLimitGb, or null for no limit) are the space settings. A change states all of its settings. The host applies keep and the limit at once and the rest to the next backup. Needs backups.manage.
Workspace permission: backups.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body SetBackupRetentionBody
admission(AdmissionBody)beforeChanges(boolean): Whether a game update, a framework change and a wipe take a backup first unless that one change says otherwise.keep(integer, required): The number of backups to keep: `minimum` or more (there is no largest number), or 0 to keep every backup; null goes back to `defaultKeep`.limitGb(integer): The most the server's backups may use, in GB (1 GB is 1,073,741,824 bytes), from `minimumLimitGb` to `maximumLimitGb`; absent or null means no limit.location(string): The folder on the server's host where its backups are kept (a full folder path).makeRoom(boolean): Whether the host makes room when the disk is nearly full: it removes old logs, then the oldest backups that are not protected.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
List a server's backupsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/backups
listServerBackups
The backups the server's host stored on its own disk, newest first: manual backups and backups before a start or restart. state is complete when every essential file was captured with the consistency it needs; problems list what was not. A backup taken while the server ran restores like any other. A backup taken while the cloud was out of reach appears once the host reports it. cloudCopyAt says when a backup was also copied to the cloud and is null when it was not. Needs backups.read.
Workspace permission: backups.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- limit (query)
- Page size.
- cursor (query)
- The nextCursor of the previous page.
Success: 200 BackupListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Back up a server nowPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/backups
createServerBackup
One operation on the server's host: when the game runs it is saved over RCON first (save) and keeps running; then its world, player data, configuration and plugin files are copied to the host's backup folder, verified and listed (backup). A backup before a start (backupFirst on start or restart) is taken while the server is stopped. Returns the operation. Needs backups.create.
Workspace permission: backups.create
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body CreateBackupRequestBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Free up spacePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/backups/actions/clean-up
cleanUpServerFiles
One operation on the server's host: removes what the chosen rules list. rules are old_logs (log files unchanged for a week, in the server's and the framework's folders) and leftover_world (saves, maps and their cache files of a world the server does not use); left out, both run, the defaults. It never removes the world the server uses, a backup, a configuration, a plugin or its data, or anything outside the server's own folder and the framework's. Needs backups.manage.
Workspace permission: backups.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body CleanUpFilesBody
admission(AdmissionBody)rules(list of string): The rules to run: `old_logs` and `leftover_world`.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Check what can be cleaned upPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/backups/actions/plan-clean-up
planCleanUpServerFiles
Previews which files Free up space would remove and how much space it would free. The list shows up to 100 files per rule, with totals for all matching files. Needs backups.manage.
Workspace permission: backups.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body PlanCleanUpBody
admission(AdmissionBody)rules(list of string): The rules to list: `old_logs` and `leftover_world`.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Copy a backup as a new serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/backups/{backupId}/actions/copy
copyServerBackup
Creates a stopped server from a backup on the same host. Use previewServerCopy and send the preview's map, save identity and framework, if present, with the new folder. The new server is installed before restore. The original server and its backups stay as they are. Rust+ pairing is left out. The returned operation targets the new server. If installation fails, retry the new server's install. Needs servers.create and backups.restore on this server.
Workspace permission: servers.create
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- backupId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body CopyServerRequestBody
admission(AdmissionBody)framework(string): The framework the backup holds (from the check's backup member): `oxide` or `carbon`.identity(string): The save identity the backup holds (from the check), for example `rustsc`; leave it out for RustSC's own.map(ServerMapBody)name(string): The new server's display name, a label for lists and operation summaries.ports(ServerPortsBody)root(string): The existing folder on the host to install the new server into, as for adding a server.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Delete a backupPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/backups/{backupId}/actions/delete
deleteServerBackup
Host operation: removes this one backup from the disk and the list. A backup an unfinished restore or copy needs is refused before anything is sent: 409 state_conflict, reason backup_in_use (the host also refuses one an unfinished restore, copy, start or launch holds); one already gone completes as a no-op. Deleting the last restorable backup is allowed: noneRestorable says none is left. The result carries the backup, whether it was removed, its bytes and how many remain. On a rented server a backup kept by its host is removed through the host, and only one RustSC made. Returns the operation. Needs backups.manage.
Workspace permission: backups.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- backupId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body DeleteBackupBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Export a backup as a zipPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/backups/{backupId}/actions/export
exportServerBackup
Host operation: builds one zip of a whole backup. Needs backups.export.
Workspace permission: backups.export
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- backupId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ExportBackupBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Check a backup for a copyPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/backups/{backupId}/actions/preview-copy
previewServerCopy
One read-only operation on the server's host: it verifies the stored backup exactly as a restore does and describes it for a copy as a new server. A backup of a server with Oxide or Carbon is described with its framework: the copy installs the same framework on the new server first. Nothing is compared with any server's files and nothing changes. Returns the operation. Needs backups.restore.
Workspace permission: backups.restore
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- backupId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body PreviewRestoreRequestBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Preview restoring a backupPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/backups/{backupId}/actions/preview-restore
previewServerRestore
One read-only operation on the server's host: it verifies the stored backup is complete and compares it with the server's files now. Nothing is stopped, copied or changed. Returns the operation. Needs backups.restore.
Workspace permission: backups.restore
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- backupId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body PreviewRestoreRequestBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Restore a backupPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/backups/{backupId}/actions/restore
restoreServerBackup
It can be cancelled until the files are replaced. An interruption is undone or finished when the host's service restarts; a failure leaves the server stopped with the stage, the reason and the earlier backup in the operation. On a rented server (one reached through its hosting company's panel) backupId names a backup RustSC holds for it and no planSha256 is needed: RustSC warns the players, stops the server through its host, saves the current files first (a backup with trigger before_restore), puts the backup's files back and leaves the server stopped; start must be false or absent (true is 422 on /start). Offered only where the server's host allows it (otherwise 409 capability_unavailable). Running the same restore again finishes one that did not finish. Returns the operation. Needs backups.restore and servers.lifecycle.
Workspace permission: backups.restore
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- backupId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RestoreBackupRequestBody
admission(AdmissionBody)planSha256(string): The planSha256 of the preview the member confirmed.putBackOf(string): The id of the failed start that stopped the game because it came back on another world and waits for the member's OK.start(boolean): Start the server after its files are restored.warningMinutes(integer): Minutes of player warning before the server stops, from 0 to the longest warning (60); players see a countdown in chat.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Restore a backup over another serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/backups/{backupId}/actions/restore-over
restoreServerBackupOver
Host operation: puts a whole backup of sourceServerId over this stopped server on the same host. targetName must equal this server's name. It keeps the server's settings and pairing, its map size and seed must be the backup's, and a before_restore backup comes first. Needs backups.restore on both servers and servers.lifecycle on this one.
Workspace permission: backups.restore
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- backupId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RestoreOverBody
admission(AdmissionBody)sourceServerId(string)targetName(string)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Restore a backup to a folderPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/backups/{backupId}/actions/restore-to-folder
restoreServerBackupToFolder
Host operation: puts a whole backup's files into a new or empty folder (folder, or the default area). Files only; no server is made. Needs backups.export.
Workspace permission: backups.export
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- backupId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RestoreToFolderBody
admission(AdmissionBody)folder(string): A folder on the server's host.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read a server's cloud copyGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/offsite
getServerOffsite
While nothing was set up this is the defaults with revision 0. No key, credential or provider address is ever returned. Works while the server or its host is offline. Needs backups.read.
Workspace permission: backups.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 OffsiteResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Turn a server's cloud copy on or offPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/offsite
saveServerOffsite
Turns the copy on or off and sets how many cloud backups are kept (3 to 100); a field left out stays as it is. The cloud prepares the copy's place and the host makes and escrows its key before the first upload, so the state is setting_up until then. Turning it off stops the uploads and keeps the copies and the key, so a restore still works and turning it on again continues the same copies. A save that changes nothing records nothing. Works while the host is offline: the host is told when it connects. Needs backups.manage.
Workspace permission: backups.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body SaveOffsiteBody
enabled(boolean)excludedFolders(list of string): The whole list of folders and files to leave out of the cloud copy, as plain paths with forward slashes below the server's backed-up files (at most 50, each at most 200 characte...keepLast(integer): 3 to 100.
Success: 200 OffsiteResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List a server's cloud copiesGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/offsite/restore-points
listServerOffsiteRestorePoints
The cloud copies the cloud knows for the server, newest first, up to 100: the local backup each was made from, when it was taken and uploaded, its size and whether its check passed. Needs backups.read.
Workspace permission: backups.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 OffsiteRestorePointsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Get a cloud backup back onto the hostPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/offsite/restore-points/{recoveryPointId}/actions/fetch
fetchServerOffsiteBackup
Downloads a cloud copy for use as a restore point. Send recoveryPointId from the restore points list. If the backup is already available locally, restore that copy or set chosenOverLocal to choose the cloud copy. The game keeps running and the game folder stays as it is. Needs backups.restore.
Workspace permission: backups.restore
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- recoveryPointId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body FetchOffsiteBody
admission(AdmissionBody)chosenOverLocal(boolean): True only when the member chose the cloud copy of a backup that is also on the host ("Restore from the cloud copy instead").
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Restore a server's cloud backup onto its new hostPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/offsite/restore-points/{recoveryPointId}/actions/restore-here
restoreServerOffsiteBackupHere
Gets one backup ready on the server's host, the host's own copy first (owner direction, 5 November 2026). The host uses its copy of the backup when it is listed and whole and downloads nothing. When it has none (madeHere is false in the list of copies, because an earlier host made it, or the copy is gone) or its copy is damaged, it downloads the cloud copy of the same backup straight from the storage provider, adopts the repository key RustSC keeps so its next backup continues the same copies, registers the server if it does not know it yet and lists the backup like one it made. The normal restore then runs on it. restoreFromCloud true is the member's safety override: the cloud copy is downloaded even when the host's copy is whole, and a copy already on the host is put back if the download does not check. The result of the import stage says which copy was used (copy, because). Nothing is relayed through RustSC, the game folder does not change, and the host needs room for the copy. The read access made for it ends after 2 hours. recoveryPointId is the one from the restore points list, otherwise 422 on /recoveryPointId (unknown_copy). A removed server answers 409, a restricted host or an offline host answers 409 capability_unavailable. Returns the operation. Needs backups.restore.
Workspace permission: backups.restore
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- recoveryPointId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RestoreOffsiteBody
admission(AdmissionBody)restoreFromCloud(boolean): The safety override: download the cloud copy even when the host holds a whole copy of the same backup.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read how well a server's backups are keeping upGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/protection
getServerProtection
Says whether the server counts as protected: its newest good backup is recent enough (protected), older (stale), none is good yet (no_backup) or nothing is known yet (not_reported). Lists the newest backups with their kind, size and whether each can be restored, and which wipe each belongs to. Reads only; nothing is started or changed. Needs backups.read.
Workspace permission: backups.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ServerProtectionResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Download a rented server's backupGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/rented-backups/{backupId}/download
downloadRentedBackup
Redeems the link made by makeRentedBackupDownloadLink: the zip, for the member it was made for. A cut download continues with the Range header. Needs backups.read.
Workspace permission: backups.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- backupId (path, required)
- See the downloadable contract for the field schema.
- grant (query)
- See the downloadable contract for the field schema.
Success: 200, 206. Errors use Problem.
Response statuses: 200, 206, 404, default.
Make a download link for a rented server's backupPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/rented-backups/{backupId}/download-link
makeRentedBackupDownloadLink
Returns a link for the member who asks, good for 5 minutes, with the file name and size. Follow it to download the zip of the server's files as they were backed up. A backup that is no longer kept answers 404. Needs backups.read.
Workspace permission: backups.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- backupId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RentedBackupLinkResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Use the previous savePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/save-fallback/actions/approve
approveServerSaveFallback
Answers the request a damaged save left (the operation that waits at await_approval): the host moves the damaged file to a folder of its own, puts the previous save back and starts the server. operationId names the request, so an answer never reaches a newer one. A request that does not wait is refused with not_awaiting_approval. Returns the operation. Needs backups.restore and servers.lifecycle.
Workspace permission: backups.restore
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body AnswerSaveFallbackRequestBody
admission(AdmissionBody)operationId(string): The ID of the operation being answered (op_...), as the operation routes list it.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Keep the server stoppedPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/save-fallback/actions/decline
declineServerSaveFallback
Answers the request a damaged save left with no: the server stays stopped and the damaged file stays where it is. Returns the operation. Needs backups.restore and servers.lifecycle.
Workspace permission: backups.restore
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body AnswerSaveFallbackRequestBody
admission(AdmissionBody)operationId(string): The ID of the operation being answered (op_...), as the operation routes list it.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Players
List the players allowed anywayGET /api/v1/workspaces/{workspaceId}/ban-allow
listAllowedAnyway
The workspace's Allowed anyway list, newest first: players no ban list removes. The allowlist, the country rule and a server's own ban still apply. Needs players.read for the whole workspace.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 AllowAnywayResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Stop allowing a player anyway from the workspace settingsDELETE /api/v1/workspaces/{workspaceId}/ban-allow/{steamId}
removeWorkspaceAllowedAnyway
Takes one player off the Allowed anyway list. A player who is not on it is 404. Needs players.admit for the whole workspace.
Workspace permission: players.admit
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- steamId (path, required)
- See the downloadable contract for the field schema.
Success: 200 AllowAnywayResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read the ban list choices of the workspaceGET /api/v1/workspaces/{workspaceId}/ban-settings
getBanSettings
One choice for Steam bans and one for each community list, for every server of the workspace: enforce (a listed player is removed a few seconds after joining) or do not enforce (the answer is only shown on the player). A list is always asked; Steam is asked while the workspace holds its own Steam key (steamKeySet). updatedAt is null before the first save, when the choices are what the servers' own earlier choices stood for. Needs players.read for the whole workspace.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BanSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save the ban list choices of the workspacePUT /api/v1/workspaces/{workspaceId}/ban-settings
saveBanSettings
Saves Steam and community ban settings for the workspace's connected hosts. Choose whether to enforce bans, which bans count and what removed players see. A list the request leaves out keeps its settings. Needs players.admit for the whole workspace.
Workspace permission: players.admit
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body SaveBanSettingsBody
lists(list of BanListChoiceBody, required)steam(SteamBanSettingsBody, required)
Success: 200 BanSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Add a BattleMetrics ban listPOST /api/v1/workspaces/{workspaceId}/ban-settings/battlemetrics-lists
addBattleMetricsBanList
Adds one of your BattleMetrics ban lists to the workspace, not enforced. Give the list's id (or the address of its page on battlemetrics.com) and your own read-only BattleMetrics token. A refused token is 422 with the field token and the reason token_refused, a list that cannot be read is list_not_found and an id that is not a list is invalid_list. The token is never shown again and never logged. A host that is not up to date is refused with 409 capability_unavailable and the reason host_needs_update: update the host first. At most 5 community lists in all. Needs players.admit for the whole workspace.
Workspace permission: players.admit
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body AddBattleMetricsBanListBody
list(string, required): The list's id (a UUID) or the address of the list's page on battlemetrics.com; the id is read from it.name(string): What the member calls the list, 1 to 60 characters; optional (the list is called BattleMetrics ban list).token(string, required): The member's own read-only BattleMetrics token (it needs only the read bans scope).
Success: 200 BanSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Add a community ban listPOST /api/v1/workspaces/{workspaceId}/ban-settings/lists
addCommunityBanList
Adds a list in Rust's centralized banning format to the workspace (at most 5), not enforced. RustSC asks address + Steam ID from each server's host; 404 means not listed. The address may hold a key: it is stored, never shown again and never logged. Needs players.admit for the whole workspace.
Workspace permission: players.admit
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body AddCommunityBanListBody
address(string, required): The `https` address of a list in Rust's centralized banning format: RustSC asks `address + Steam ID`; 404 means not listed and a JSON answer means listed.appealsUrl(string): Where a listed player can appeal; an `https` or `http` address, optional.name(string, required): 1 to 60 characters.runBy(string, required): Who runs the list, 1 to 60 characters.
Success: 200 BanSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Remove a community ban listDELETE /api/v1/workspaces/{workspaceId}/ban-settings/lists/{listId}
removeCommunityBanList
Deletes the list from the workspace, every server's copy of it and every fact it gave. Needs players.admit for the whole workspace.
Workspace permission: players.admit
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- listId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BanSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Remove a community ban list's keyDELETE /api/v1/workspaces/{workspaceId}/ban-settings/lists/{listId}/key
disconnectBanListKey
Removes the key from RustSC and from every host it was sent to; the list keeps working on its address alone. A list with no key answers the same. Needs players.admit for the whole workspace.
Workspace permission: players.admit
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- listId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BanSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Add a community ban list's keyPUT /api/v1/workspaces/{workspaceId}/ban-settings/lists/{listId}/key
setBanListKey
Setting it again replaces it. placement says where it goes. Needs players.admit for the whole workspace.
Workspace permission: players.admit
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- listId (path, required)
- See the downloadable contract for the field schema.
Request body BanListKeyBody
key(string, required): The key the list's service gave: 1 to 512 characters, no spaces.placement(string, required): `api_key_header` (a header called x-api-key), `bearer` (the Authorization header) or `query_key` (the address gets ?key=).
Success: 200 BanSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read the join rule defaults of the workspaceGET /api/v1/workspaces/{workspaceId}/join-rule-settings
getJoinRuleSettings
The workspace's default for blocked countries, Steam profile must be public and the minimum Steam account age. A server follows a default unless it holds its own value for that rule; servers lists every server with a host and, for each rule, whether it uses the workspace or its own value. Every default is off until the workspace changes it, and updatedAt is null until then. Needs players.read for the whole workspace.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 JoinRuleSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save the join rule defaults of the workspacePUT /api/v1/workspaces/{workspaceId}/join-rule-settings
saveJoinRuleSettings
Saves the workspace defaults. Offline hosts receive them when they reconnect. Server-specific rules stay in place. Use previewJoinRuleSettings to see which servers a change affects. On the first save, any rule already enabled for a server stays enabled for that server. Needs players.admit for the whole workspace.
Workspace permission: players.admit
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body JoinRuleSettingsBody
countries(CountryRuleBody, required)steam(SteamRulesBody, required)
Success: 200 JoinRuleSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the servers a join rule default would newly apply toPOST /api/v1/workspaces/{workspaceId}/join-rule-settings/preview
previewJoinRuleSettings
Saves nothing. Lists the servers that follow the workspace for a rule that is off on them today and that the body's default switches on, with those rules. A server with its own value for a rule is not listed for it. An empty list means no server starts refusing players. Needs players.read for the whole workspace.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body JoinRuleSettingsBody
countries(CountryRuleBody, required)steam(SteamRulesBody, required)
Success: 200 JoinRuleSettingsPreviewResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read the permission sync of the workspaceGET /api/v1/workspaces/{workspaceId}/permission-sync
getPermissionSync
Nothing is on until a member turns it on. Needs players.read.sensitive for the whole workspace.
Workspace permission: players.read.sensitive
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PermissionSyncResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Turn the permission sync on or off and choose its serversPUT /api/v1/workspaces/{workspaceId}/permission-sync
savePermissionSync
Turns the sync on or off and sets which servers take part (none are ticked for you; a server added later is only offered). Turning it off needs neither, leaves every server as it is and keeps what was shared. A server the sync cannot read (no host service) is refused with the field /servers and the reason no_host. The first pass of a server only adds. Needs players.permissions.manage for the whole workspace.
Workspace permission: players.permissions.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body SavePermissionSyncBody
enabled(boolean, required)servers(list of string, required): The IDs of the servers that take part.
Success: 200 PermissionSyncResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read the history of the permission syncGET /api/v1/workspaces/{workspaceId}/permission-sync/history
listPermissionSyncHistory
Newest first: what the sync applied to each server (names of what changed and counts, never a file's text), every pause with the item's last changes and who made them, resumes, choices, edits made once in Global, and turning it on and off. These are audit entries read without the audit trail's own permission. Needs players.read.sensitive for the whole workspace.
Workspace permission: players.read.sensitive
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- cursor (query)
- See the downloadable contract for the field schema.
- limit (query)
- See the downloadable contract for the field schema.
Success: 200 PermissionSyncHistoryResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Make a missing group again, or delete it everywherePOST /api/v1/workspaces/{workspaceId}/permission-sync/missing-groups
resolveMissingPermissionGroup
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body ResolveMissingGroupBody
action(string, required)group(string, required)serverId(string): The server the group vanished from; required for `make_again`.
Success: 200 PermissionSyncResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Ask for a dry run, a check now, or a resume of the permission syncPOST /api/v1/workspaces/{workspaceId}/permission-sync/requests
requestPermissionSync
Asks for something that needs a host, so the answer comes shortly after: preview (what turning the sync on for the given servers would add to each, nothing is sent), check (run a pass now), resume_preview (what a resume would send) or resume (lift a pause and send one batch). Read getPermissionSync again shortly: waiting is true until the answer is in, and preview then holds the answer.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body RequestPermissionSyncBody
action(string, required)key(string)scope(string)serverId(string)servers(list of string)
Success: 200 PermissionSyncResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Choose what the sync does for players a server has not seen yetPUT /api/v1/workspaces/{workspaceId}/permission-sync/servers/{serverId}
choosePermissionSyncNewPlayers
wait (the default) applies a change to a player after their first join. add_before makes their entry in the saved files before they join, only while the game is stopped (a running game waits for its next stop). The server must already be in the sync. Needs players.permissions.manage for the whole workspace.
Workspace permission: players.permissions.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body ChoosePermissionSyncNewPlayersBody
newPlayers(string, required)
Success: 200 PermissionSyncResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Keep items Only on this server, or sync them againPUT /api/v1/workspaces/{workspaceId}/permission-sync/servers/{serverId}/only-here
setPermissionSyncOnlyHere
only true keeps the listed items out of the sync on this server: nothing is read from it or written to it for them, and the other servers neither get nor lose them because of it. only false puts them back (Sync it): the server's version then counts as a change like any other. A key is an item's key, or g:name for a whole group. Changes nothing on any server by itself. Needs players.permissions.manage for the whole workspace.
Workspace permission: players.permissions.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body SetOnlyHereBody
keys(list of string, required)only(boolean, required)
Success: 200 PermissionSyncResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the names players were seen underGET /api/v1/workspaces/{workspaceId}/player-names
listPlayerNames
Every name RustSC saw a player under across the workspace's servers, once per Steam ID and name however many sessions carried it, with when it was first and last seen, in how many sessions and on how many servers. The newest last seen comes first, 50 to a page (cursor for the next). search is text inside a name (case ignored), so an old name finds the player it belonged to; steamId narrows to one player; serverId narrows to one server. A player who changed name has one row per name. Sessions without a name add nothing. Reads only; nothing is sent to a game or to Steam, and no address is in it. Needs players.read for the whole workspace, or on the server when serverId is given.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- steamId (query)
- See the downloadable contract for the field schema.
- serverId (query)
- See the downloadable contract for the field schema.
- search (query)
- See the downloadable contract for the field schema.
- cursor (query)
- See the downloadable contract for the field schema.
Success: 200 PlayerNamesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List the saved permission templatesGET /api/v1/workspaces/{workspaceId}/player-permission-templates
listPlayerPermissionTemplates
The workspace's saved lists of group and permission changes, by name. A template is only data: applying it to a server (applyServerPlayerPermissions) is a separate press, and nothing applies it by itself. Needs players.permissions.manage.
Workspace permission: players.permissions.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PlayerPermissionTemplatesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a permission templatePOST /api/v1/workspaces/{workspaceId}/player-permission-templates
savePlayerPermissionTemplate
Saves 1 to 100 changes under a name of 1 to 60 characters, at most 50 templates in a workspace. A name already used (ignoring case) is 422 /name name_taken; a staff level is 422 /operations/{index} staff_not_in_template. Names of groups and permissions are written in lower case. Nothing is sent to a host or a game. Needs players.permissions.manage.
Workspace permission: players.permissions.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body SavePlayerPermissionTemplateBody
name(string): 1 to 60 characters, unique in the workspace ignoring case.operations(list of PlayerPermissionOperationBody): 1 to 100 changes; a staff level is not part of a template.
Success: 200 PlayerPermissionTemplateResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Delete a permission templateDELETE /api/v1/workspaces/{workspaceId}/player-permission-templates/{templateId}
deletePlayerPermissionTemplate
Deletes the template. Changes already added from it to a server's pending list stay there. Needs players.permissions.manage.
Workspace permission: players.permissions.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- templateId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Read the player statsGET /api/v1/workspaces/{workspaceId}/player-stats
getPlayerStats
Records and figures from the players RustSC saw connected: the most players at once and when, different and new players, hours played, the average online, the players with the most time and the busiest hour of the day. serverId names one server; without it every server the caller may read players on is counted together and each server's share is listed. period is wipe (one server only, and its default), 7d, 30d (the default for every server) or all; wipeStart picks a previous wipe from the answer's wipes. A server whose wipes are not known answers period all. timeZone is the zone of the busy hours (default UTC). allTime holds the same records for everything RustSC holds. Reads only. Needs players.read, on the server when serverId is given.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (query)
- See the downloadable contract for the field schema.
- period (query)
- See the downloadable contract for the field schema.
- wipeStart (query)
- See the downloadable contract for the field schema.
- timeZone (query)
- See the downloadable contract for the field schema.
Success: 200 PlayerStatsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
List the players of the workspaceGET /api/v1/workspaces/{workspaceId}/players
listWorkspacePlayers
Everyone the player history holds across the workspace's servers, connected or not, one row per Steam ID: connected players first, then the newest last seen, 50 to a page (cursor for the next). Each player has the newest name, when first and last seen, the servers seen on (connected ones first), globalBan (the global ban list bans the player now) and serverBans (the servers that ban the player on their own through RustSC). search is a Steam ID typed exactly or text inside a name (case ignored); serverId narrows to one server; state is all (the default), online or offline. Each player has sessionSeconds (the current session while online, otherwise the previous one) and totalSeconds (the time on every server of the workspace, removed ones included, also when serverId is given). A player is online only while a session is open on a server that exists and whose host is connected. A caller who holds links.manage, or players.moderate for every player the list can hold (the whole workspace, the server named by serverId, or every server a member limited to some servers may read), also gets discordName, the Discord name of each linked player (also when it is the in-game name). A caller who holds worlds.read on the server named by serverId also gets entities and entitiesAt, what the player owned in that server's newest count (a count the member asked for; nothing is counted on a timer). sort is session, total, name, status, servers, bans, discord (the linked Discord name; needs what discordName needs) or entities (needs serverId and worlds.read on it; a player with no count comes last) (absent: the order above) with order desc (the default) or asc, longest or Z first when desc; a player with no name or no Discord name comes last either way; with a sort the cursor is a position. canModerate says whether the caller may ban for this list. Bans made outside RustSC are not listed here; the server's own ban list (listBans) shows them. Needs players.read for the whole workspace, or on the server when serverId is given.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- search (query)
- See the downloadable contract for the field schema.
- serverId (query)
- See the downloadable contract for the field schema.
- state (query)
- See the downloadable contract for the field schema.
- cursor (query)
- See the downloadable contract for the field schema.
- sort (query)
- See the downloadable contract for the field schema.
- order (query)
- See the downloadable contract for the field schema.
Success: 200 WorkspacePlayersResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Ban a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/ban-player
banPlayer
Bans the Steam ID in the game's own ban list, which is saved and survives a restart, and drops the player if connected. The player need not be connected. A name and a reason are optional. Without expiresInSeconds the ban never ends; with it (60 to 31536000, one minute to 365 days) the game itself ends the ban at that moment and removes it from its list, (another end time in the game's list fails with expiry_not_kept). The stage result says what the game answered (banned or already_banned), whether the list shows it (effective) and whether it saved it (saved). A player who is still in the game when the ban takes effect is removed at once with the ban's reason; removal says what happened (not_connected, kicked, kick_failed or kick_unchecked) and a failed removal never undoes the ban. The game keeps one entry per Steam ID, so banning an owner or moderator replaces the role; with giveRoleBack true the host notes the role the ban replaced (removed_role in the stage result) and RustSC sets it again through the same operation as setGameRole when the ban is lifted with unbanPlayer or ends by itself, only if the player is not banned and holds no role then. Left out or false, nothing is put back. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body BanPlayerRequestBody
expiresInSeconds(integer): How long the ban lasts, in seconds from now: 60 (one minute) to 31536000 (365 days).giveRoleBack(boolean): True to have RustSC put the player's owner or moderator role back when the ban is lifted or ends.name(string): The name to store with the ban, optional, up to 64 characters.reason(string): Why; optional, up to 200 characters.steamId(string, required): The Steam ID to ban, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Also ban a player from DiscordPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/discord-ban-player
discordBanPlayer
Bans the Discord account the player linked in this workspace from the connected Discord server, and deletes that account's recent messages for the chosen period: deleteMessageSeconds is one of 0 (delete none), 3600, 21600, 43200, 86400, 259200 or 604800. Call it only after the server ban was accepted and only when the member asked; it is never part of banPlayer. The answer is 200 with an outcome: banned, needs_permission (give the RustSC role Ban Members in Discord), move_role (move the RustSC role above the person's roles in Discord), no_account (the Discord account no longer exists), busy (try again in a minute) or unavailable. 409 state_conflict with not_linked when the player has no link here and no Discord server is connected. Needs players.moderate on the server.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body DiscordBanPlayerBody
deleteMessageSeconds(integer): Whose recent messages to delete, in seconds: 0 (the default), 3600, 21600, 43200, 86400, 259200 or 604800.steamId(string, required): The player's Steam ID (17 digits).
Success: 200 DiscordBanResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Also lift a player's Discord banPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/discord-unban-player
discordUnbanPlayer
Lifts the Discord ban RustSC made on this player (Also ban from Discord). Call it only after the server unban was accepted and only when the member asked; it is never part of unbanPlayer. A ban a person made in Discord is never changed. The answer is 200 with an outcome: unbanned, needs_permission (give the RustSC role Ban Members in Discord), busy (try again in a minute) or unavailable. 409 state_conflict with not_banned when RustSC made no Discord ban on this player. Needs players.moderate on the server.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body DiscordUnbanPlayerBody
steamId(string, required): The player's Steam ID (17 digits).
Success: 200 DiscordUnbanResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Freeze a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/freeze-player
freezePlayer
Freezes a connected, living player for the supplied duration. The player stays frozen if they rejoin before it ends. Restarting the server or reloading the plugin ends the freeze. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body FreezePlayerRequestBody
minutes(integer): How long the freeze lasts, in whole minutes: 1 to 60, 10 when left out.name(string): The name the portal shows for the player, only so the activity line says it; optional, up to 64 characters.reason(string): The reason the player is told, up to 120 characters; optional.steamId(string, required): The Steam ID of the player, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Give items to a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/give-items
givePlayerItems
Send the item's short name and quantity. The result reports how many the connected player received and whether any did not fit. Needs players.inventory.manage.
Workspace permission: players.inventory.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body GivePlayerItemsRequestBody
amount(integer, required): How many, 1 to 100000.item(string, required)name(string): The name the portal shows for the player, only so the activity line says it; optional.skin(integer): A skin number; left out or 0 gives the item without a skin.steamId(string, required): The Steam ID of the player, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Heal a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/heal-player
healPlayer
Heals a connected, living player to full health. The result reports health_before and health_after, or why the player could not be healed. Needs players.actions.
Workspace permission: players.actions
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body HealPlayerRequestBody
name(string): The name the portal shows for the player, only so the activity line says it; optional, up to 64 characters.steamId(string, required): The Steam ID of the player, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Import a list of bansPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/import-bans
importBans
Bans the valid entries in the submitted list. Use previewBanImport to check the list first. The operation reports each entry's outcome. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body BanListTextRequestBody
text(string, required): The list as typed or read from a file, at most 262144 characters: one Steam ID per line with an optional reason after it, the file the export writes (`steam_id,name,reason,expir...
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Kick a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/kick-player
kickPlayer
Removes the player with this Steam ID from the server now, with an optional reason the player sees. The player can join again. Returns the operation; the game says whether the player was connected (outcome kicked or not_connected in the stage result). The target is the Steam ID, never a name. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body KickPlayerRequestBody
reason(string): Why, shown to the player; optional, up to 200 characters.steamId(string, required): The Steam ID of the player to kick, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Kill a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/kill-player
killPlayer
Kills a connected, living player. The result reports health_before and health_after, or why no change was made. Needs players.actions.
Workspace permission: players.actions
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body KillPlayerRequestBody
name(string): The name the portal shows for the player, only so the activity line says it; optional.steamId(string, required): The Steam ID of the player, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Save inventory changesPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/manage-inventory
managePlayerInventory
Applies one reviewed list of exact-stack quantities, deletions and Give additions to one connected player. Each change is checked first, then the actual outcome of each change is reported by the change ID the client gave. A Give is never repeated by mistake. Needs players.inventory.manage and a compatible companion.
Workspace permission: players.inventory.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ManagePlayerInventoryRequestBody
changes(list of InventoryEditChangeBody, required)name(string)revision(string, required)steamId(string, required)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Send a private message to a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/message-player
messagePlayer
Sends a private game chat message of 1 to 200 characters to one connected player. For a message to everyone, use a broadcast. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body MessagePlayerRequestBody
name(string): The name the portal shows for the player, only so the activity line says it; optional, up to 64 characters.steamId(string, required): The Steam ID of the player, 17 digits.text(string, required): The message, 1 to 200 characters.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Kick, ban, unban or mute several players of a rented serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/moderate-players
moderatePlayers
Does one thing to one to 20 players of a rented server whose console takes commands, in one operation: action is kick, ban, unban, mute or unmute. The cloud sends one console line for each player in the order given, with a short pause between lines, and has the game save its ban list once after the last ban or unban. The stage result lists every player as done, failed or unknown with the reason, and counts them. A ban or unban is recorded the way banPlayer and unbanPlayer record it. Any other server answers capability_unavailable. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ModeratePlayersRequestBody
action(string, required): What to do to every player: kick, ban, unban, mute or unmute.expiresInSeconds(integer): A ban only: how long it lasts, in seconds from now (60 to 31536000).players(list of BulkPlayerBody, required): One to 20 players.reason(string): A kick or a ban: why; optional, up to 200 characters.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Mute a player's chat through the game's consolePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/mute-chat
muteChat
Stops a connected player on a rented server from using chat. Send the player's Steam ID. If the RustSC plugin is installed, use mutePlayer instead to set a duration. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body MuteChatRequestBody
name(string): The name the member saw, for the activity line only; optional.steamId(string, required): The Steam ID of the player, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Mute a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/mute-player
mutePlayer
Set scope to text or voice and give a duration in minutes. Muting the same scope replaces its current mute. A mute lasts through a server restart. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body MutePlayerRequestBody
minutes(integer): How long the mute lasts, in whole minutes: 1 to 10080, 60 when left out.name(string): The name the portal shows for the player, only so the activity line says it; optional, up to 64 characters.reason(string): The reason the player is told, up to 120 characters; optional.scope(string): text (the default) or voice.steamId(string, required): The Steam ID of the player, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Preview a list of bansPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/preview-ban-import
previewBanImport
Reads a list of bans (one Steam ID per line with an optional reason, the file the export writes, or the game's banid lines) and counts what an import would do on this server, without sending anything: the new bans, those already on the ban list, the lines that are not valid with their line numbers, repeats, bans that had already ended and how many end by themselves. A list that cannot be used as a whole answers 200 with refusal not_text, too_large (over 262144 characters) or too_many (over 500 bans). Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body BanListTextRequestBody
text(string, required): The list as typed or read from a file, at most 262144 characters: one Steam ID per line with an optional reason after it, the file the export writes (`steam_id,name,reason,expir...
Success: 200 BanImportPreviewResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Look at what a player carriesPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/read-inventory
readPlayerInventory
Reads the connected player's main inventory, belt and clothing. Follow the returned operation, then read the inventory with getPlayerInventory. Needs players.inventory.read.
Workspace permission: players.inventory.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ReadPlayerInventoryRequestBody
name(string): The name the portal shows for the player, only so the activity line says it; optional.steamId(string, required): The Steam ID of the player, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read items available in the gamePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/read-item-catalogue
readPlayerItemCatalogue
Reads one revision-bound page of item definitions from the running game. Follow the operation, then read its private result. Later pages must carry the first revision. Needs players.inventory.read and a compatible companion.
Workspace permission: players.inventory.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ReadItemCatalogueRequestBody
cursor(integer)name(string)revision(string)steamId(string, required)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Release a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/release-player
releasePlayer
Ends RustSC mutes and freezes for this player. To end just one, set scope to text, voice or freeze. If no matching restriction is active, the result is not_restricted. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ReleasePlayerRequestBody
name(string): The name the portal shows for the player, only so the activity line says it; optional, up to 64 characters.scope(string): text, voice or freeze.steamId(string, required): The Steam ID of the player, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Take an owner or moderator role awayPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/remove-game-role
removeGameRole
Removes the game role owner or moderator from the Steam ID in the game's own list and has the game save it. A Steam ID that holds the other role keeps it: the stage result says not_in_role and nothing changes. Returns the operation (outcome removed or not_in_role, and effective). Needs players.gameroles.manage.
Workspace permission: players.gameroles.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RemoveGameRoleRequestBody
role(string, required): The role to take away, `owner` or `moderator`.steamId(string, required): The Steam ID, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Remove items from a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/remove-item
removePlayerItem
Permanently removes the requested quantity from one stack. Send the revision from getPlayerInventory. For revision_changed, read the inventory again before retrying. The result shows the removed quantity and new revision when successful. Needs players.inventory.manage.
Workspace permission: players.inventory.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RemovePlayerItemRequestBody
amount(integer, required): How many to remove, 1 up to what the stack holds.container(string, required): `main`, `belt` or `wear`.name(string): The name the portal shows for the player, only so the activity line says it; optional.revision(string, required): The revision of the inventory read the removal was decided on.steamId(string, required): The Steam ID of the player, 17 digits.uid(string, required): The item's unique number from that read.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Restore a player's blueprintsPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/restore-blueprints
restorePlayerBlueprints
Replaces a connected player's learned blueprints with the supplied list. Use the before list from a previous unlock to undo it. A name without a blueprint refuses the whole request. Needs players.actions.
Workspace permission: players.actions
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RestorePlayerBlueprintsRequestBody
items(list of string, required): Item short names, at most 2000; empty means no learned blueprint.name(string): The name the portal shows for the player, only so the activity line says it; optional, up to 64 characters.steamId(string, required): The Steam ID of the player, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Make a player an owner or moderatorPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/set-game-role
setGameRole
Gives the Steam ID the game role owner or moderator in the game's own list, which the game saves and keeps through a restart. The role replaces any other role the Steam ID holds, so changing a moderator to an owner is one request and never leaves them with none. The player does not have to be connected. A name is optional and stored with the role. Returns the operation, whose stage result says what the game answered (added or already_has_role) and whether the game's saved list shows it (effective). Game roles are the game's: this never changes a workspace role. Needs players.gameroles.manage.
Workspace permission: players.gameroles.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body SetGameRoleRequestBody
name(string): The name to store with the role, optional, up to 64 characters.role(string, required): `owner` or `moderator`.steamId(string, required): The Steam ID, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Change a player's health, hunger or thirstPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/set-vitals
setPlayerVitals
Send at least one whole value for health, calories or hydration. The player must be connected, alive and standing. A value outside the available range returns value_out_of_range without applying changes. The result reports the values before and after. Needs players.actions.
Workspace permission: players.actions
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body SetPlayerVitalsRequestBody
calories(integer): Calories (hunger) in whole points, from 0 to the game's maximum (500 today).health(integer): Health in whole points, from 1 to the player's maximum (100 normally).hydration(integer): Hydration (thirst) in whole points, from 0 to the game's maximum (250 today).name(string): The name the portal shows for the player, only so the activity line says it; optional, up to 64 characters.steamId(string, required): The Steam ID of the player, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Move a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/teleport-player
teleportPlayer
Send either toSteamId or x and z in whole metres from the map centre. A connected player or a sleeping player can be moved. A sleeping player wakes at the new location. The result reports x, y, z and asleep when available. If the position is refused, choose another. Needs players.actions.
Workspace permission: players.actions
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body TeleportPlayerRequestBody
name(string): The name the portal shows for the player, only so the activity line says it; optional.steamId(string, required): The Steam ID of the player to move, 17 digits.toSteamId(string): The Steam ID of the player to move them to, online or asleep in the world.x(integer): East of the map's centre in whole metres, -4000 to 4000.z(integer): North of the map's centre in whole metres, -4000 to 4000.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Unban a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/unban-player
unbanPlayer
Removes the Steam ID from the game's ban list and saves it. The Steam ID does not have to be in the list shown. Returns the operation (outcome unbanned or not_banned). Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body UnbanPlayerRequestBody
steamId(string, required): The Steam ID to unban, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Unlock a player's blueprintsPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/unlock-blueprints
unlockPlayerBlueprints
Send the short item name to unlock one blueprint, or leave it out to unlock all blueprints. If you need to undo the change, send the returned before list to restorePlayerBlueprints. An item without a blueprint returns unknown_blueprint. Needs players.actions.
Workspace permission: players.actions
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body UnlockPlayerBlueprintsRequestBody
item(string)name(string): The name the portal shows for the player, only so the activity line says it; optional, up to 64 characters.steamId(string, required): The Steam ID of the player, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Let a player chat again through the game's consolePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/unmute-chat
unmuteChat
Lets a connected player on a rented server use chat again. Send the player's Steam ID. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body MuteChatRequestBody
name(string): The name the member saw, for the activity line only; optional.steamId(string, required): The Steam ID of the player, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Stop allowing a player anywayDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/ban-allow/{steamId}
removePlayerAllowedAnyway
Takes one player off the Allowed anyway list. A player who is not on it is 404. Needs players.admit for the whole workspace.
Workspace permission: players.admit
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- steamId (path, required)
- See the downloadable contract for the field schema.
Success: 200 AllowAnywayResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Allow a player anywayPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/ban-allow/{steamId}
allowPlayerAnyway
Lets one player in whatever the ban lists say; adding a player who is already allowed changes nothing. At most 2000. Every server's copy is brought up to date. The list is the whole workspace's, so a role limited to one server is refused. Needs players.admit for the whole workspace.
Workspace permission: players.admit
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- steamId (path, required)
- See the downloadable contract for the field schema.
Request body AllowAnywayBody
playerName(string): The name the portal shows for the player, kept so the list reads when the player is away; optional.
Success: 200 AllowAnywayResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read the ban facts of playersGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/ban-facts
getBanFacts
What each ban list last said about up to 50 players (steamIds, comma separated): listed or not, Steam's VAC and game ban counts and days since the last ban, a community list's end time, with when it answered and, when it gave no answer, why. A fact a list did not give is null, never zero. A community list's own reason needs players.read.sensitive and is left out (reasonHidden) otherwise. Needs players.read.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- steamIds (query)
- See the downloadable contract for the field schema.
Success: 200 BanFactsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Check players against the ban lists againPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/ban-facts/check
checkBanFacts
Asks about up to 50 players now, ignoring what it kept; the answers arrive as ban facts, so read them again after a few seconds. Asking changes nothing in the game. A server with the RustSC app asks every ban list that is on. A server on a panel host, with no RustSC app, asks Steam only, with the workspace's own Steam key, and only for the players named; with no key it answers 409 with the reason needs_steam_key, and a removed server or one with no host answers 409 with no_host_service. Nothing is asked until this route is called. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body CheckBanFactsBody
steamIds(list of string, required): 1 to 50 Steam IDs.
Success: 202 BanFactsAskedResponse. Errors use Problem.
Response statuses: 202, 401, 403, 404, 409, 422, default.
Read the ban lists of a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/ban-lists
getBanLists
The workspace's ban list choices as this server holds them: Steam and each community list, enforced or not. A list is asked about every joining player and the answer is shown; an enforced list also removes a listed player a few seconds after joining. Steam is asked only while the workspace holds its own Steam key (steamKeySet). A list that gives no answer never removes anyone. health says when each list last answered this server. supported is false on a server without a host service. Nothing is changed here: the choices are the workspace's (saveBanSettings). Needs players.read.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BanListsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read whether a rented server refuses listed players when they joinGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/ban-lists/join-check
getRentedJoinCheck
For a rented server (available true): whether the member switched the join check on (enabled), what RustSC found (state: off, on, not_confirmed, other_service or not_set), whether the workspace enforces any ban list (enforced), the sentence to show (words) and when RustSC last confirmed it (checkedAt). Any other server answers available false. Nothing is asked of the server. Needs players.read.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RentedJoinCheckResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Refuse listed players when they join a rented server, or stopPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/ban-lists/join-check
setRentedJoinCheck
On, a player refused by a ban list the workspace enforces is turned away when they join, with that list's words. A server that already uses its own ban service is left alone (state other_service). Off, RustSC undoes only its own change and puts back what the server had before. A server that is not rented is 409 state_conflict (not_rented); on where the host cannot take it is 409 state_conflict (not_offered); on while the workspace enforces no ban list is 409 state_conflict (nothing_enforced); enabled is required (422 at /enabled). Needs players.admit.
Workspace permission: players.admit
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body RentedJoinCheckBody
enabled(boolean): True to refuse listed players when they join, false to stop.
Success: 200 RentedJoinCheckResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the bans of a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/bans
listBans
The game's own ban list: Steam ID, the name and reason stored with each ban, when a ban ends (never for bans made through RustSC) and, for bans made through RustSC, who banned the player and when. Each ban has a scope: server (the server's own ban, or one made outside RustSC), global (the workspace ban list bans the player here and the server does not on its own) or both; globalApplies and globalBans say whether and how many global bans apply here, so a screen can show server bans alone. Newest first, at most 500 with the total the game lists. The host reads the game for this request, so it can take a few seconds; while the host is offline or the game does not answer, state is unavailable with a reason, never an empty list. Needs players.read.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BansResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Download the ban listGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/bans/export
exportBans
The server's ban list as a file, from the ban list RustSC last read: format csv (the default; steam_id,name,reason,expires_at, the end time as an ISO 8601 UTC time and empty for a ban that never ends) or cfg (the game's own banid lines). At most the newest 500 bans; the X-Total-Bans header says how many the game lists. Names and reasons are made console-safe and a cell that starts with = + - or @ gets a leading quote. No address is ever included. Answers 409 while the list cannot be read. The download is recorded in the audit log. Needs players.read.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- format (query)
- See the downloadable contract for the field schema.
Success: 200. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Get saved inventory change resultsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/inventory-batch-results/{operationId}
getPlayerInventoryBatchResult
The exact result of each client change ID in one saved list of inventory changes. Needs players.inventory.manage; generic operation views hide the private changes.
Workspace permission: players.inventory.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- operationId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PlayerInventoryBatchResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Get the inventory a read foundGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/inventory-reads/{operationId}
getPlayerInventory
Reads the inventory from a completed read operation. State is running, read or unavailable. The reply lists items by slot in main, belt and wear and includes the revision needed for removal. Read again before acting. This request needs players.inventory.read on the server.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- operationId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PlayerInventoryResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Get the game's items from a readGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/item-catalogue-reads/{operationId}
getPlayerItemCatalogue
Gets one page of the running game's item definitions with a revision and next cursor. Needs players.inventory.read on this server.
Workspace permission: players.inventory.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- operationId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PlayerItemCatalogueResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List the item sets of a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/item-sets
listItemSets
The item sets saved for this server, by name, at most 100. A set is only a list: nothing in the game changes until it is given. Needs players.inventory.manage.
Workspace permission: players.inventory.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ItemSetsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save an item setPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/item-sets
createItemSet
Saves a named list of one to 20 items for this server. Saving gives nobody anything. The name must differ from the server's other sets. The answer is the set, with its revision as the ETag. Needs players.inventory.manage.
Workspace permission: players.inventory.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body SaveItemSetRequestBody
lines(list of ItemSetLineBody, required): One to 20 lines, given in this order.name(string, required): The name members, 1 to 60 characters, different from the server's other sets.
Success: 201 ItemSetResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Delete an item setDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/item-sets/{setId}
deleteItemSet
Deletes the saved list. Items already given stay with the players. Needs the revision you read in If-Match. Needs players.inventory.manage.
Workspace permission: players.inventory.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- setId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 412, 422, 428, default.
Change an item setPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/item-sets/{setId}
editItemSet
Replaces the name and items of the set. Changes nothing in any game and nothing about a grant already made. Needs the revision you read in If-Match; a set someone else changed since is 412 revision_conflict. Needs players.inventory.manage.
Workspace permission: players.inventory.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- setId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body SaveItemSetRequestBody
lines(list of ItemSetLineBody, required): One to 20 lines, given in this order.name(string, required): The name members, 1 to 60 characters, different from the server's other sets.
Success: 200 ItemSetResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Give an item set to a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/item-sets/{setId}/give
giveItemSet
Gives every item of the set to the connected player with this Steam ID through the RustSC plugin, one counted give per item, in order. Returns the operation, whose stage result lists each line: outcome applied, partial (some did not fit and was not dropped) or not_applied with the plugin's reason, or skipped when an earlier line showed the player was gone, plus the overall outcome. The lines are the set as read when the request runs and its revision is kept with the operation. If revision is sent and the set has changed, nothing is given (412 revision_conflict). Items given are never taken back, and an answer lost in the middle ends the operation as outcome unknown with no item sent again. Needs players.inventory.manage.
Workspace permission: players.inventory.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- setId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body GiveItemSetRequestBody
name(string): The name the portal shows for the player, only to word the operation's summary; optional.revision(integer): The set's revision the member looked at.steamId(string, required): The Steam ID of the connected player, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
List the join checks of a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/join-checks
listJoinChecks
What the join rules decided for players who joined, newest first, 50 to a page: the result, the rule that decided, every rule's turn with the value it used, and whether the player was removed. identity is what Steam's Web API said (profile visibility, account creation time, VAC and game ban counts, days since the last ban) with the time it answered, or the reason it did not. Steam facts and countries need players.read.sensitive and are left out (masked) otherwise. steamId narrows to one player; refusedOnly lists removals. Needs players.read.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- steamId (query)
- See the downloadable contract for the field schema.
- refusedOnly (query)
- See the downloadable contract for the field schema.
- cursor (query)
- See the downloadable contract for the field schema.
Success: 200 JoinChecksResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Read the join rules of a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/join-rules
getJoinRules
The rules that decide who may stay on the server after joining: a list of allowed Steam IDs, blocked countries, private Steam profiles and young Steam accounts. Every rule is off until switched on. The ban lists (Steam bans and community lists) have their own routes. A player who breaks a rule is removed shortly after joining with the rule's message; owners and moderators of the game are never removed. steamProblem says why Steam last gave no answer. supported is false on a server without a host service. Blocked countries, the public profile rule and the account age are the workspace's setting unless the server holds its own value: the values here are the ones the server uses, sources says for each whether that is the workspace or the server, and workspace holds the workspace's default. Needs players.read.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 JoinRulesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save the join rules of a serverPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/join-rules
saveJoinRules
Saves the rules as the next revision and sends them to the host, which keeps applying them even when the cloud is unreachable. A save that changes nothing keeps the revision. A rule never touches a player who is already in the game. Every Steam rule says what to do when Steam gives no answer. A server without a host service answers 409. The allowed players and the latency rule are the server's. countries, steam.privateProfile and steam.accountAge, when given, become the server's own value for that rule (on or off); left out, the rule keeps following the workspace or keeps the server's own value (useWorkspaceJoinRule goes back to the workspace). Needs players.admit.
Workspace permission: players.admit
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body SaveJoinRulesBody
allowlist(AllowlistRuleBody, required)countries(CountryRuleBody)latency(LatencyRuleBody)steam(ServerSteamRulesBody)
Success: 200 JoinRulesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Use the workspace's setting for a join ruleDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/join-rules/{rule}
useWorkspaceJoinRule
Makes the server follow the workspace setting for country (blocked countries), private_profile (public Steam profiles) or account_age (minimum Steam account age). An unknown rule returns 404. A server without a host service returns 409. Needs players.admit.
Workspace permission: players.admit
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- rule (path, required)
- See the downloadable contract for the field schema.
Success: 200 JoinRulesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the player history of a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/player-history
listPlayerHistory
Who joined and left the server, the gaps in which RustSC could not see it, and the kicks, bans and unbans made through RustSC, newest first, 50 to a page. A session is one connection of one Steam ID: joinedAt began it and leftAt ended it; ended says how that is known (left, unseen: RustSC lost sight and leftAt is the last sighting, server_stopped). search is a Steam ID typed exactly or text inside any name the player used (case ignored); it follows the matching players through every name, includes their kicks, bans and unbans and leaves out gaps. range is day, week (the default), month or all; all is what is kept (18 months, 100,000 sessions). No IP address is stored or returned. Needs players.read.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- search (query)
- See the downloadable contract for the field schema.
- range (query)
- See the downloadable contract for the field schema.
- cursor (query)
- See the downloadable contract for the field schema.
Success: 200 PlayerHistoryResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Take a label off a playerDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/player-labels
removePlayerLabel
Removes the label named in the query (label, with steamId) from the player. A label the player does not have is not an error. Adding it again undoes a removal. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- steamId (query)
- See the downloadable contract for the field schema.
- label (query)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
List the labels on a server's playersGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/player-labels
listPlayerLabels
The private labels members keep against this server's players, by player then label, at most 1000. Narrow it to one player with steamId or to one label with label (compared ignoring case). Labels are never sent to a game, Discord, a public page or an export. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- steamId (query)
- See the downloadable contract for the field schema.
- label (query)
- See the downloadable contract for the field schema.
Success: 200 PlayerLabelsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Put a label on a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/player-labels
addPlayerLabel
Adds a label of 1 to 30 characters to the player with this Steam ID on this server, at most 10 labels for one player. A label the player already has (ignoring case) is left as is and returned. Changes nothing in any game. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body AddPlayerLabelRequestBody
label(string, required): The label: 1 to 30 characters, at most 10 for one player.steamId(string, required): The player's Steam ID, 17 digits.
Success: 200 PlayerLabelResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the private notes of a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/player-notes
listPlayerNotes
The private notes members wrote about players of this server, newest change first, 50 to a page. steamId keeps the notes about one player; search keeps the notes whose text or player name contains it (case ignored) or whose player is that Steam ID. A note of another server is never listed, even for the same Steam ID. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- steamId (query)
- See the downloadable contract for the field schema.
- search (query)
- See the downloadable contract for the field schema.
- cursor (query)
- See the downloadable contract for the field schema.
Success: 200 PlayerNotesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Write a private note about a playerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/player-notes
createPlayerNote
Keeps a private note about the Steam ID on this server, with who wrote it and when. The player does not have to be connected. At most 50 notes per player. The answer is the note, with its revision as the ETag. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body CreatePlayerNoteRequestBody
body(string, required): The note: 1 to 2000 characters.name(string): The name the portal shows for the player, kept with the note so the list reads when the player is away; optional, up to 64 characters.steamId(string, required): The Steam ID of the player the note is about, 17 digits.
Success: 201 PlayerNoteResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Remove a private noteDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/player-notes/{noteId}
removePlayerNote
Deletes the note and every text it had; this cannot be undone. The audit log keeps who removed it and when, never the text. Needs the revision you read in If-Match. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- noteId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 412, 422, 428, default.
Change a private notePUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/player-notes/{noteId}
editPlayerNote
Replaces the text of the note and keeps the text it had in the note's history (the newest 50, ). Needs the revision you read in If-Match; a note someone else changed since is 412 revision_conflict and keeps its text. Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- noteId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body EditPlayerNoteRequestBody
body(string, required): The new text, as for a new note.name(string): The name the portal shows for the player now; optional.
Success: 200 PlayerNoteResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
List the texts a note has hadGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/player-notes/{noteId}/history
listPlayerNoteHistory
Every text the note has had, newest first, with who wrote it and when (the newest 50, ). Needs players.moderate.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- noteId (path, required)
- See the downloadable contract for the field schema.
Success: 200. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Apply changes to a server's groups and permissions at oncePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/player-permissions/actions/apply
applyServerPlayerPermissions
Choose route files for a stopped server or console for a running one. If the server changed state, retry with the matching route. For a graceful restart, send changes in restartServer instead. Use preview to check each change or putBack to undo the last change if the permissions are still current. A staff.set change also needs players.gameroles.manage. The result reports each change. Needs players.permissions.manage on a ready server.
Workspace permission: players.permissions.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ApplyPlayerPermissionsBody
admission(AdmissionBody)framework(string)operations(list of PlayerPermissionOperationBody): The changes, in the order the member made them (at most 500).preview(boolean)putBack(boolean): True to put back the originals of the last change instead of applying anything.route(string): True to see what each change would do and write nothing.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read a server's groups, players' permissions and in-game staffPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/player-permissions/actions/read
readServerPlayerPermissions
Reads player grants, groups and game staff. Select framework oxide or carbon. Use query and offset to search players. A full Steam ID also returns that player's effective permissions. Set registered to true to list only registered permissions. Needs players.read.sensitive on a ready server.
Workspace permission: players.read.sensitive
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ReadPlayerPermissionsBody
admission(AdmissionBody)framework(string): `oxide` or `carbon`, the framework the portal saw; the host checks it against the server's files.group(string): A group's name: the answer then lists every member of that group (at most 1,500, with truncated set when it was cut) and leaves out the page of players.offset(integer): How many matching players to skip (the page is 50).query(string): A Steam ID or part of a last seen name to look for among the players.registered(boolean): True to ask for the permissions the loaded plugins registered (the answer is then only `registered`: its `state` (`listed`, `server_stopped` or `unavailable`), the names in orde...
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read the players seen on a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/player-records
listServerPlayerRecords
The players RustSC saw on this server while its Players list was open, newest last seen first (at most 200), offline players included: the newest name, first and last time seen, the total time connected, the number of sessions and whether the player is online now. Repeat steamId (up to 50) to read only those players; a player RustSC never saw is left out. A server whose host keeps its own player history answers an empty list. Reads only; nothing is sent to a game. Needs players.read.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- steamId (query)
- See the downloadable contract for the field schema.
Success: 200 ServerPlayerRecordsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read what RustSC knows about some playersGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/player-summaries
listPlayerSummaries
For up to 50 Steam IDs (repeat steamId in the query) answers, in the order asked, what RustSC stored on this server: the names seen (newest first), first and last time seen, whether connected now, seconds in sessions that ended (what RustSC observed, not play time), the Steam facts of the newest join check (account creation, visibility, VAC and game bans) and, for players.moderate, the private labels, the number of notes and the Discord name of the player's link (discordName, so a moderator can contact the player; absent when the player has not linked). A Steam ID never seen has seen=false and no other facts; an unknown value is absent, never zero. Steam facts need players.read.sensitive (steamHidden says they were left out) and labels and notes need players.moderate (detailsHidden). The address is never in it. Reads only; nothing is sent to a game or to Steam. Needs players.read.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- steamId (query)
- See the downloadable contract for the field schema.
Success: 200 PlayerSummariesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List connected playersGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/players
listConnectedPlayers
The players connected to the server now, by name A to Z, with the counts the game reports (players, joining, waiting) and when and how they were read. The host reads the game for this request, so it can take a few seconds; while the host is offline or the game does not answer, state is unavailable with a reason, never an empty list. IP addresses need players.read.sensitive and are masked otherwise. Needs players.read.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PlayersResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Check whether a player can also be banned from DiscordGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/players/{steamId}/discord-ban
getDiscordBanOption
Says whether the choice Also ban from Discord is offered for this player: offered is true when the workspace has a connected Discord server, the player has linked a Discord account in this workspace and the RustSC bot may ban members there. When it is false, problem is needs_permission if the bot lacks Ban Members, and absent when there is no connected server or the player has no link (the choice is then not shown at all). Changes nothing. Needs players.moderate on the server.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- steamId (path, required)
- See the downloadable contract for the field schema.
Success: 200 DiscordBanOptionResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read a player's cupboards and upkeep trail on a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/players/{steamId}/upkeep
getPlayerUpkeep
Whether the server tracks upkeep, whether the player's own alerts are on, the player's cupboards with the minutes left and a colour state (ok, low, last_hours, ran_out), and the trail since the last wipe. Needs worlds.read, because a cupboard's position is world information.
Workspace permission: worlds.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- steamId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PlayerUpkeepResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Lift a server's own ban where a global ban also appliesDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/server-bans/{steamId}
liftServerBan
For a ban whose scope is both (the server bans the player on its own and the workspace ban list bans the player there too): forgets the server's own ban. Nothing is sent to the game, because the global ban keeps the player banned on this server; when the global ban is lifted later, this server is unbanned with the others. A Steam ID this server does not ban on its own is 404; one the global list does not ban here is 409 state_conflict (not_global), and unbanPlayer lifts it. Needs players.moderate on the server.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- steamId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ServerBanLiftedResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the owners and moderators of a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/staff
listStaff
The game's own owners and moderators as the game saved them: Steam ID, role, the name stored with it and, for roles given through RustSC, who gave the role and when. Owners first, then moderators, at most 200 with the total the game lists. The host reads the game's saved list for this request, so it can take a few seconds; while the host is offline or the file cannot be read, state is unavailable with a reason, never an empty list. Needs players.read.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 StaffResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Remove the workspace's own Steam keyDELETE /api/v1/workspaces/{workspaceId}/steam-key
disconnectSteamKey
Deletes the stored key and orders every host to forget it, so lookups return to RustSC's own. Nothing happens when no key was saved. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Read the workspace's own Steam key stateGET /api/v1/workspaces/{workspaceId}/steam-key
getSteamKey
Whether the workspace saved its own Steam Web API key, when, and how many of its hosts hold it, wait for it or refused it. The key is never returned. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 SteamKeyResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save the workspace's own Steam keyPUT /api/v1/workspaces/{workspaceId}/steam-key
saveSteamKey
Sending a key again replaces the saved one; leaving key out keeps it. A text that is not a key is refused with 422 at /key (invalid_steam_key). Works while hosts are offline: they receive it when they connect. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body SteamKeyBody
key(string): The key from steamcommunity.com/dev/apikey: 32 hexadecimal characters.
Success: 200 SteamKeyResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Bulk plans
List recent bulk plansGET /api/v1/workspaces/{workspaceId}/bulk-plans
listBulkPlans
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BulkPlanListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Preview an action on many serversPOST /api/v1/workspaces/{workspaceId}/bulk-plans
createBulkPlan
Chooses servers and groups (at most 50 servers) and an action, and returns what would happen on each server without sending anything: will_run, skipped (nothing to do) or blocked with a reason (no_permission, host_offline, restricted_host, server_removed). Servers the caller may read but not act on show as blocked. A caller who may act on none gets 403. Optional rollout chooses how the servers start: together (default), one_at_a_time or in_groups (groupSize 2 to 50, default 5), with pilot (the first server alone first) and stopOnFailure (default true). A schedule action makes an ordinary schedule per server.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body BulkPlanBody
groupIds(list of string): Groups chosen (`grp_...`); every member the caller can read.kind(string): `player.ban`, `player.unban`, `server.broadcast` or `profile.apply`.parameters(JsonElement): `player.ban`: `steamId`, optional `name`, `reason` and `expiresInSeconds`.rollout(BulkRolloutBody)serverIds(list of string): Servers chosen one by one (`srv_...`).
Success: 201 BulkPlanResponse. Errors use Problem.
Response statuses: 201, 400, 401, 403, 404, 409, 422, default.
Read a bulk planGET /api/v1/workspaces/{workspaceId}/bulk-plans/{planId}
getBulkPlan
outcome is succeeded only when every server succeeded or had nothing to do; partly done is partial.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- planId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BulkPlanResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Apply a bulk planPOST /api/v1/workspaces/{workspaceId}/bulk-plans/{planId}/actions/apply
applyBulkPlan
The one confirmation.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- planId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Success: 202 BulkPlanResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Cancel a bulk planPOST /api/v1/workspaces/{workspaceId}/bulk-plans/{planId}/actions/cancel
cancelBulkPlan
Servers the caller may not act on are left as they are.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- planId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BulkPlanResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Retry the servers that failedPOST /api/v1/workspaces/{workspaceId}/bulk-plans/{planId}/actions/retry-failed
retryBulkPlan
Servers that succeeded, had nothing to do or whose outcome is unknown are never touched. 409 nothing_to_retry when none qualifies.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- planId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body BulkRetryBody
serverIds(list of string)
Success: 202 BulkPlanResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Plugins
Remove the workspace's Codefling keyDELETE /api/v1/workspaces/{workspaceId}/codefling
removeCodeflingConnection
Deletes the stored key at once. Codefling plugins then show as links again. Nothing happens when no key was saved. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Read the workspace's Codefling connectionGET /api/v1/workspaces/{workspaceId}/codefling
getCodeflingConnection
Whether RustSC offers the Codefling connection (available), whether the workspace saved its own Codefling key and when. The key is never returned. Needs integrations.read.
Workspace permission: integrations.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 CodeflingConnectionResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save the workspace's Codefling keyPUT /api/v1/workspaces/{workspaceId}/codefling
saveCodeflingConnection
Stores the access token of an Account API app from Codefling's Apps page as a protected secret, replacing any saved key, then asks Codefling once whether it works and answers with check. A key Codefling does not accept is still saved, so check says what to do. Text with spaces or longer than 512 characters is refused with 422 at /key (invalid_codefling_key). The key is used only by RustSC's cloud, only with codefling.com, and never reaches a server's host. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body CodeflingKeyBody
key(string): The access token of an Account API app from Codefling's Apps page (codefling.com/settings/apps).
Success: 200 CodeflingConnectionResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Check the workspace's Codefling keyPOST /api/v1/workspaces/{workspaceId}/codefling/actions/check
checkCodeflingConnection
Asks Codefling whether the saved key works and, where the key may read it, the account's name. Changes nothing. check is null when no key is saved. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 CodeflingConnectionResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the RustSC plugin's player commands on every serverGET /api/v1/workspaces/{workspaceId}/companion-commands
listCompanionCommands
Lists each server's RustSC chat commands and when they were last observed. State is on, clash, off or unknown. For a clash, rename the command so players can use it. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 CompanionCommandsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Get a found plugin's pictureGET /api/v1/workspaces/{workspaceId}/plugins/images/{source}
getFoundPluginImage
A marketplace's logo or thumbnail for a found plugin, as RustSC's own copy: the member's browser never contacts the marketplace and the marketplace never learns the member's address. source is the marketplace's code and u the picture's address as the search result gave it (only an address on that marketplace's own site is served). Answers a small PNG, JPEG, WebP or GIF picture, kept for a day; 404 when pictures are not shown for the marketplace, the address is not its own, or the picture is not a small picture. Needs a signed-in account.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- source (path, required)
- See the downloadable contract for the field schema.
Success: 200. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List the plugin marketplacesGET /api/v1/workspaces/{workspaceId}/plugins/websites
listPluginWebsites
Every plugin marketplace the Plugins tab lists, in the order shown: its name, whether Find plugins searches it (searched) or the member opens the website to look, the page to open (site) and, where the website's own search address is known, a search address with {q} where the words go. The list is fixed in RustSC's settings; nothing is asked of a website. The list is the same for every workspace and holds nothing private, so it needs a signed-in account only.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PluginWebsitesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Remove the workspace's RustHQ keyDELETE /api/v1/workspaces/{workspaceId}/rusthq
removeRustHqConnection
Deletes the stored key at once and orders every host that holds it to forget it (a host that is offline is told when it returns). RustHQ plugins then show as links again. Nothing happens when no key was saved. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Read the workspace's RustHQ connectionGET /api/v1/workspaces/{workspaceId}/rusthq
getRustHqConnection
Whether RustSC offers the RustHQ connection (available), whether the workspace saved its own RustHQ key and when, and the workspace's hosts with whether each holds the key. The key is never returned. Needs integrations.read.
Workspace permission: integrations.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RustHqConnectionResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save the workspace's RustHQ keyPUT /api/v1/workspaces/{workspaceId}/rusthq
saveRustHqConnection
Save the API key from RustHQ account settings. Use check in the response to see the next step. The key must start with rhq_, have no spaces and be at most 256 characters. If RustHQ asks for approval, enter the supplied code in that account. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body RustHqKeyBody
key(string): The account API key from RustHQ's account settings (rusthq.com, Settings, API).
Success: 200 RustHqConnectionResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Check the workspace's RustHQ keyPOST /api/v1/workspaces/{workspaceId}/rusthq/actions/check
checkRustHqConnection
Asks RustHQ whether the saved key works from each host that holds it, and answers with RustHQ's answer for each host (works, wrong_key, not_approved with the code to enter on rusthq.com, not_allowed or unreachable). When no host holds the key yet it is sent to the preferred host and check.state is key_sent. Changes nothing else. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RustHqConnectionResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Delete, rename, move, copy or create files and folders in a server's Oxide or Carbon folderPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/files/actions/change
changeServerFiles
Send 1 to 100 items, each delete, discard, rename, move, copy, new_file or new_folder. They run in order and the operation reports a result for each item. Paths are below the framework's folder and follow the rules of upload: only plugins, config (configs for Carbon), data and lang, never the framework's own files, the companion plugin, RustSC records or the server's own files (422 on /items/{n}/path or /items/{n}/to). area `rustsc` works in RustSC's folder of the server instead: only delete, new_file and new_folder, only where the member may change it (422 on /items/{n}/path otherwise); it needs a host that runs RustSC. To undo a delete that returned keptAs, rename that copy back. discard permanently deletes a file or folder. rename stays in its folder, move and copy name the whole destination; ifExists says what a taken name does (keep_both is the default). Undo is the opposite change made from the rows (a delete is undone by renaming keptAs back). For rented servers, the folder result lists available actions in host_limits. An unavailable action returns not_available, and a server with no connection returns 409 capability_unavailable. Returns the operation. Needs servers.files.write on a ready server.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ChangeServerFilesBody
admission(AdmissionBody)area(string): Leave out for the Oxide or Carbon folder.framework(string): `oxide` or `carbon`.ifExists(string): What happens when a copy, move or rename lands on a name that is taken: `keep_both` (default; a free name such as `Kits-2.cs`) or `replace` (the earlier file is kept beside it).items(list of ChangeServerFilesItemBody): One to 100 changes, done in order.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Save a file in a server's Oxide or Carbon folderPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/files/actions/edit
editServerFile
Save replacement text in the framework folder. Send the file's baseSha256 from readServerFiles. Keep JSON the same kind as the original and XML well-formed. Set reload to reload the related plugin. If it fails to load, the earlier file is restored (applied rolled_back). A file no plugin reads by its place is saved and not reloaded (applied not_applicable). area `rustsc` saves a file in RustSC's folder of the server instead, only where the member may change it (422 on /path otherwise); it needs a host that runs RustSC. For rented servers, the folder result lists available actions in host_limits. An unavailable action returns not_available, and a server with no connection returns 409 capability_unavailable. Returns the operation. Needs servers.files.write on a ready server.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body EditServerFileBody
admission(AdmissionBody)area(string): Leave out for the Oxide or Carbon folder.baseSha256(string): The `sha256` the read of the file returned: the revision this edit started from.content(string): The whole new text, saved exactly as sent.framework(string): `oxide` or `carbon`.path(string): The file, as the folder listing named it.reload(boolean): True to reload the plugin the file belongs to after saving.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Look at the files in a server's Oxide or Carbon folderPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/files/actions/read
readServerFiles
topic folder lists the entries of path (the framework's folder when left out), folders first and then by name, one page of 500 from offset, with each entry's kind, size, change time and whether it can be edited here; the answer says how many the folder holds. topic search lists names below path that hold query, to a bounded depth and number of entries, and says when a bound stopped it. topic tree lists a folder and every folder below it in one answer (breadth first, whole folders, about 40 KiB a page, offset is the folder number the page starts at, next in the result is where the following page starts) so a client can keep the listings and open folders without asking; a host only, a panel host refuses it. topic treez is the same walk made once and packed: offset is a chunk number, each chunk holds whole folders as a JSON array of the tree answer's folders, gzipped and written as base64 in packed, and the result says how many chunks there are (chunks) and which walk they belong to (generation), so a client can ask for all the chunks at once and join only chunks of one generation; offset 0 always walks the folders again; folders named logs, backup and backups are left out and read when opened; a host that does not know it fails with input_invalid, and the client asks for topic tree instead. topic game_files lists the server's own files and logs outside the framework's folder that can be read (its cfg files, the game's log, the framework's logs and, with hosts.read, the host's own log files) as entries with a name, size and time, and topic game_file reads one by a name from that list (path): the text, or for a log its last 48 KiB, with secrets and IP addresses removed on the host. Never any other file; a host that runs RustSC only (a panel host refuses it), and a host older than 0.2.47 fails it as input_invalid. topic backup_files lists the files of one stored backup (path is the backup's ID; query is `state=all|included|left_out|failed;` and part of a path; offset starts the page, 500 entries a page, total is the number that match): each entry's name is the path, kind is `included`, `left_out:<reason>` or `failed:<reason>`, and the entry has its size when known; counts gives the number per state. Framework is ignored but must be oxide or carbon; a host that runs RustSC only, and a host older than the release that adds it fails it as input_invalid. Without servers.files.read the names, sizes and times in the result are not shown to a reader of the operation. area `rustsc` looks in RustSC's folder of the server instead (paths start with `rustsc`; topics folder, open and search; a host that runs RustSC only). topic open reads one file: its text exactly as stored, its format (json, xml or text), its sha256 (the revision a save must start from) and, when a plugin reads it by where it sits, that plugin's name. A file over 48 KiB opens as its first 48 KiB to read, never to edit; a file that is not text, or is a binary kind, is described by its size only. Nothing outside the framework's folder is reachable. For rented servers, the folder result lists available actions in host_limits. An unavailable action returns not_available, and a server with no connection returns 409 capability_unavailable. Returns the operation. Needs servers.files.read on a ready server.
Workspace permission: servers.files.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ReadServerFilesBody
admission(AdmissionBody)area(string): Leave out for the Oxide or Carbon folder.framework(string): `oxide` or `carbon`: whose folder to look in.offset(integer): Where the next page of a folder starts (a multiple of the page size the last answer gave); 0 for the first.path(string): A path below the framework's folder, for example `oxide/config`; for `folder` and `search` the framework's folder itself when left out.query(string): The part of a name to look for, for `search`.topic(string): `folder` (the entries of `path`, one page), `tree` (the entries of `path` and of every folder below it, a page of folders from folder number `offset`), `search` (names that hold...
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read the last listing kept for a server's Oxide or Carbon folderGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/files/listing
getServerFileListing
Reads the most recently saved listing for framework oxide or carbon. The reply includes file and folder names, sizes and update times. Check found and ageSeconds before relying on the listing. Needs servers.files.read.
Workspace permission: servers.files.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- framework (query)
- See the downloadable contract for the field schema.
Success: 200 FileListingResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Keep the listing the Files area has just readPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/files/listing
saveServerFileListing
Replaces the saved listing for the selected framework. Send up to 3,000 folders and 1 MiB. The server's files are unaffected. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body SaveFileListingBody
folders(list of FileListingFolderWire): Every folder, at most 3,000 and 1 MiB of listing in all.framework(string): `oxide` or `carbon`.
Success: 200 SavedFileListingResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List a server's pluginsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins
listServerPlugins
Every plugin file in the plugin folders of the frameworks installed on the server, from the newest report the host sent. load is what the game's own plugin list said (loaded, unloaded or failed) and is unknown, with a reason, whenever it did not say or the report is not current; Each plugin lists its marketplaces in the offered order (uMod, Codefling, Lone.Design, ChaosCode, then alphabetically), each with its own listing and version, never merged. marketplace is the one the update verdict follows: the member's choice, else the first in that order that has the plugin. update compares the installed version with the version of that marketplace only; a newer version on another marketplace is shown in candidates and never makes update_available. Versions compare only when both are dotted numbers; otherwise unknown, reason not_comparable. Needs plugins.read.
Workspace permission: plugins.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ServerPluginsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Check a server's plugins for updates nowPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/actions/check
checkServerPlugins
The answers come shortly after, not in this request; the list shows each marketplace as checking until its answer is newer. A workspace may ask a limited number of times (429 rate_limited with retryAfterSeconds). Returns requestedAt and how many plugin file names were made due (asked). Needs plugins.manage.
Workspace permission: plugins.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PluginCheckResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, 429, default.
Check a plugin file at a web addressPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/actions/check-address
checkPluginAddress
Checks an HTTPS link to a plugin .cs file before installation. Use a direct file address without credentials. The operation result's address has found true with the plugin name, version, file name, size and sha256, or found false with a reason to correct. Install it with installServerPlugin (marketplace address, source the address, sha256 from this result). framework is needed only when both Oxide and Carbon are installed. Needs plugins.manage and servers.files.write on a ready server.
Workspace permission: plugins.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body CheckPluginAddressBody
address(string): The https address of the plugin file.admission(AdmissionBody)framework(string): `oxide` or `carbon`; needed only when both are installed.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Install a plugin from a marketplacePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/actions/install
installServerPlugin
Send the marketplace and a plugin name or listing address. For Codefling, use the listing ID or page from the account connected to the workspace. For marketplace address, send the HTTPS address of the .cs file and the sha256 returned by checkPluginAddress. Choose framework if both Oxide and Carbon are installed. Install required dependencies separately. If the plugin is already installed (409 already_installed), use Update. If a plugin fails to load, it is removed. Returns an operation. Needs plugins.manage on a ready server; marketplace address also needs servers.files.write there.
Workspace permission: plugins.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body InstallPluginRequestBody
admission(AdmissionBody)framework(string): `oxide` or `carbon`; needed only when both are installed.marketplace(string): The marketplace code: `umod`, or `codefling` for a plugin the workspace's own Codefling account owns (when RustSC offers the Codefling connection and the workspace saved its key).sha256(string): Marketplace `address` only: the fingerprint (64 lower case hexadecimal characters) `checkPluginAddress` reported for the file at `source`.source(string): The plugin's name as the marketplace writes it, or the address of its page there.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Find plugins on the marketplacesGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/find
findServerPlugins
One search across the marketplaces RustSC is set up for (uMod, Codefling and RustHQ), for a server so each result can say whether the plugin is already there and whether it fits the server's framework. Results are the marketplaces' own public listings, read once for every customer and kept for a few minutes to an hour; nothing from the member, the workspace or the server is sent to a marketplace and the words are not logged. A marketplace that could not be asked is named in sources with state unavailable (or stale, with the age of the data shown): its results are missing, never empty. A free uMod plugin is installed with installServerPlugin (marketplace umod, source = installSource); so is a Codefling plugin the workspace's own Codefling account owns (owned true, marketplace codefling, source = installSource, the listing id), when the workspace connected its account. Every other result is a link (link, with affiliate true when buying through it earns RustSC a commission). Needs plugins.read.
Workspace permission: plugins.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- q (query)
- The words to look for, at most 80 characters; empty browses.
- price (query)
- See the downloadable contract for the field schema.
- sort (query)
- See the downloadable contract for the field schema.
- category (query)
- admin, building, economy, events, loot, pve, pvp, tools or ui.
- source (query)
- One marketplace's code (umod, codefling or chaoscode); every marketplace when left out.
- compatible (query)
- true keeps plugins the marketplace itself lists for the server's framework.
- recent (query)
- true keeps plugins whose latest release is recent.
- page (query)
- From 1; each page asks every marketplace for its next listings.
Success: 200 FindPluginsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Recognise a pasted plugin addressPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/find/address
recognisePluginAddress
Says what an address the member pasted under Add a plugin by its address is, by fixed rules and without fetching it: a plugin's page on a marketplace Find plugins searches is that listing (kind listing, plugin, as a search result with its install state); a page of another plugin marketplace RustSC knows is kind marketplace with the website and the page to open (also a searched marketplace's page that is not a plugin's page, reason not_listed when it does not have the plugin, unavailable when it could not be asked); an https address of a .cs file on any other public site is kind file with the file name (check it with checkPluginAddress before installing); an archive is kind archive; anything else is kind unreadable with reason not_an_address, not_https, private_address or not_a_plugin. Only the site of the address is repeated (site); the address is not logged or stored. Needs plugins.read.
Workspace permission: plugins.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body RecognisePluginAddressBody
address(string): The address the member pasted, at most 2000 characters.
Success: 200 PluginAddressResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Open a found pluginGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/find/{source}/{id}
getFoundPlugin
source is the marketplace's code and id the listing's id from a search result. Text comes from the marketplace and is always plain text. 404 when the marketplace does not have the listing or is not searched; 409 capability_unavailable marketplace_unreachable when it could not be asked and nothing earlier is held. Needs plugins.read.
Workspace permission: plugins.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- source (path, required)
- See the downloadable contract for the field schema.
- id (path, required)
- See the downloadable contract for the field schema.
Success: 200 FoundPluginDetailResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read whether a rented server can take the RustSC plugin and whether it has itGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/rented-rustsc
getRentedRustscPlugin
Shows whether a connected rented server has the RustSC plugin and whether it is current. A server without a connection returns connected false. If reason is framework_missing and frameworkSwitch is available, use that setting to enable a framework. A recent answer may be given again; readAt says when it was read, and refresh=true reads it now. To install the plugin, call installServerPlugin with marketplace `rustsc`, source `RustscCompanion` and the reported framework. Needs plugins.read.
Workspace permission: plugins.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- refresh (query)
- See the downloadable contract for the field schema.
Success: 200 RentedPluginResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Remove the RustSC plugin from a rented serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/rented-rustsc/actions/remove
removeRentedRustscPlugin
Removes the RustSC plugin file from a connected rented server's plugin folder for the framework named here (oxide or carbon, as getRentedRustscPlugin reported) and checks that it is gone; the framework unloads it. Game events, the chat relay and mute through the plugin stop working until it is installed again with installServerPlugin (marketplace `rustsc`). Nothing else changes and nothing is kept. A plugin already gone succeeds with unchanged true. 422 /framework framework_unclear without a framework; 409 capability_unavailable when the server has no such file connection. The Files area still refuses this file. Returns the operation. Needs plugins.manage.
Workspace permission: plugins.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RemoveRentedPluginBody
admission(AdmissionBody)framework(string): `oxide` or `carbon`, as `getRentedRustscPlugin` read it.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Which plugin updates can be rolled backGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/rollbacks
listServerPluginRollbacks
The plugin files whose last update finished recently, newest first: direction back (the update can be rolled back) or forward (a roll back can be rolled forward again), when the last change finished and when the offer ends. No host is asked and nothing changes. A plugin file not listed has nothing to roll. Needs plugins.read.
Workspace permission: plugins.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PluginRollbacksResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Which plugin updates RustSC can makeGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/update-access
getServerPluginUpdateAccess
For each plugin that has a newer version on Codefling or RustHQ (the marketplaces whose download needs the workspace's own account), whether RustSC can make the update: ready, not_owned, needs_setup or link_only, with a reason. The plugin list shows every update; this says which of them the Update action works for. It asks only the accounts the workspace connected, and only when such an update exists. The owned list is kept in memory and the answer of a connected account is not asked again for a few minutes. A lookup that gets no answer (the marketplace is slow, asked to wait, or the host is offline) says ready: it never hides an update. Nothing is installed, updated or removed. Needs plugins.read.
Workspace permission: plugins.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PluginUpdateAccessResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Enable, disable, reload, remove or update a pluginPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/{pluginId}/actions/change
changeServerPlugin
Changes one plugin while the game keeps running. disable stays in effect after a restart. remove keeps the plugin's settings and data. If an update fails to load, the prior version is restored and the result reports rolledBack. On a rented server, check and put_back follow an update the game did not load. Use getServerPluginUpdateAccess to see available updates. For Codefling or RustHQ, connect the account that owns the plugin. A 422 result names the action to correct. If the marketplace cannot be reached, retry later. Needs plugins.manage on a ready server.
Workspace permission: plugins.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- pluginId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ChangePluginRequestBody
action(string): `enable`, `disable`, `reload`, `remove` or `update`.admission(AdmissionBody)replaceEdited(boolean): Ignored since 8 November 2026: an update always replaces the file (the Keep mine / Replace / Skip question is gone).
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Check one plugin for updates nowPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/{pluginId}/actions/check
checkServerPlugin
The same as checking the whole server, for one plugin file. Needs plugins.manage.
Workspace permission: plugins.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- pluginId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PluginCheckResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, 429, default.
Grant or revoke a permission, or change a groupPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/{pluginId}/actions/permission
changeServerPluginPermission
Use grant or revoke for a player (Steam ID) or a group, group_add or group_remove for a group, and member_add or member_remove to change group membership. Revoking removes only that grant: access through a group stays and the result names the groups. These are the framework's permissions, not RustSC roles. Returns the operation. Needs plugins.manage on a ready server.
Workspace permission: plugins.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- pluginId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ChangePluginPermissionBody
action(string): `grant`, `revoke`, `group_add`, `group_remove`, `member_add` or `member_remove`.admission(AdmissionBody)group(string): The group, for group_add, group_remove, member_add and member_remove.permission(string): The permission, for grant and revoke.subject(string): A Steam ID (user), or a group name, for grant and revoke; the Steam ID for member_add and member_remove.subjectKind(string): `user` or `group`, for grant and revoke.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read the names of a plugin's files, its permissions or its commandsPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/{pluginId}/actions/read
readServerPluginSettings
Set topic to files for configuration, data and language files, permissions for grants and group members, or commands for the plugin's console commands. Use readServerFiles with topic open to read a file and editServerFile to change it. Read the result on the returned operation. Needs servers.files.read for files and plugins.permissions.read for permissions and commands, on a ready server.
Workspace permission: servers.files.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- pluginId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ReadPluginSettingsBody
admission(AdmissionBody)topic(string): `files` (the names of its configuration, data and language files), `permissions` or `commands`.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Roll a plugin update back or forwardPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/{pluginId}/actions/roll
rollServerPlugin
Use listServerPluginRollbacks to check which direction is available. Set direction to back to restore the previous version or forward to reapply the update. The game keeps running and the plugin reloads. A 409 result reports rollback_file_changed or rollback_expired. Needs plugins.manage on a ready server.
Workspace permission: plugins.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- pluginId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RollPluginRequestBody
admission(AdmissionBody)direction(string): `back` puts the file the update replaced back; `forward` applies the update again after a roll back.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Mark a plugin as CustomPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/{pluginId}/custom
setServerPluginCustom
Marks one plugin file on this server as Custom (the member's own or a modified plugin that they maintain), or clears the mark. A Custom plugin is never updated automatically or by Update all, has an unknown update verdict with reason custom even when a marketplace lists it (the match stays in candidates), and cannot be kept up to date; marking it turns keepUpToDate off. It changes nothing on the server. Returns the plugin. Needs plugins.manage.
Workspace permission: plugins.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- pluginId (path, required)
- See the downloadable contract for the field schema.
Request body SetPluginCustomBody
custom(boolean)
Success: 200 ServerPluginResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Keep a plugin up to datePUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/{pluginId}/keep-up-to-date
setServerPluginKeepUpToDate
Switches the rule "Keep this plugin up to date" for one plugin file on this server, for any plugin (loaded, disabled, stored or used by a schedule). It is off until a member switches it on, and it changes nothing on the server: it records the choice beside the plugin's marketplace choice. Refused (422, marketplace_not_available) when no marketplace lists the plugin or update checks are off for it; switching it off is never refused. Returns the plugin. Needs plugins.manage.
Workspace permission: plugins.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- pluginId (path, required)
- See the downloadable contract for the field schema.
Request body SetPluginKeepUpToDateBody
keepUpToDate(boolean)
Success: 200 ServerPluginResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Choose the marketplace of a pluginPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/{pluginId}/marketplace
chooseServerPluginMarketplace
Saves the marketplace the update verdict of this plugin file follows on this server. The choice is remembered for the file, replaces an earlier choice or default, and is refused (422, marketplace_not_available) unless that marketplace lists the plugin (found). The value none turns update checks off for the plugin (an exclusion: its verdict is unknown with reason excluded and autoUpdate.possible is false); choosing a marketplace again turns them back on. Nothing is installed, updated or removed. Returns the plugin. Needs plugins.manage.
Workspace permission: plugins.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- pluginId (path, required)
- See the downloadable contract for the field schema.
Request body ChoosePluginMarketplaceBody
marketplace(string): A marketplace code from the server's `marketplaces` that lists the plugin (`found`).
Success: 200 ServerPluginResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Give the marketplace page of a pluginPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugins/{pluginId}/page
setServerPluginPage
Saves the marketplace listing to use for this plugin. Send a Codefling, uMod, RustHQ or Lone.Design page. If /address is refused, check the listing and try again. Saving leaves the installed plugin as it is. Needs plugins.manage.
Workspace permission: plugins.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- pluginId (path, required)
- See the downloadable contract for the field schema.
Request body SetPluginPageBody
address(string): The https address of the plugin's page on its marketplace (Codefling, uMod, RustHQ or Lone.Design).
Success: 200 ServerPluginResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Dashboard
Get the workspace dashboardGET /api/v1/workspaces/{workspaceId}/dashboard
getDashboard
Counts and current player coverage include all authorized resources. Players sum fresh raw observations; stale or absent observations are excluded. History sums server player bucket averages and averages server FPS; series and points carry their own reporting coverage. Missing buckets stay absent. range defaults to day. This read starts no host work.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- range (query)
- See the downloadable contract for the field schema.
Success: 200 DashboardResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
List dashboard hosts or serversGET /api/v1/workspaces/{workspaceId}/dashboard/items
listDashboardItems
kind is hosts or servers. Current observations retain their source times and freshness. Counts are independent of these pages.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- kind (query, required)
- See the downloadable contract for the field schema.
- cursor (query)
- See the downloadable contract for the field schema.
- limit (query)
- See the downloadable contract for the field schema.
Success: 200 DashboardItemsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Discord link
Disconnect DiscordDELETE /api/v1/workspaces/{workspaceId}/discord-link
disconnectDiscordLink
Removes the connection. Linked players stay linked; the channel is left as it is. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Read the Discord link setupGET /api/v1/workspaces/{workspaceId}/discord-link
getDiscordLink
The connected Discord server, the link channel, the invite link and the number of linked players. status is none, connected, ready, channel_gone or needs_permission; available is false where this deployment has no Discord bot. Needs integrations.read.
Workspace permission: integrations.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 DiscordLinkResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Create the link channelPOST /api/v1/workspaces/{workspaceId}/discord-link/channel
createDiscordLinkChannel
The bot creates #rust-link (text, read only for members) and posts and pins the instruction message. 409 state_conflict with reason missing_permission when the bot lacks Manage Channels (state names it). Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 DiscordLinkResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Choose the link channelPUT /api/v1/workspaces/{workspaceId}/discord-link/channel
chooseDiscordLinkChannel
Checks the channel again against Discord (it exists in the connected server, is a text channel, and the bot can view it, send messages, read the history and manage messages there), then the bot posts and pins the instruction message. 409 state_conflict with reason missing_permission (state names the channel and what is missing), channel_gone or discord_unavailable; 422 on /channelId (channel_not_found, channel_not_text). Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body ChooseLinkChannelBody
channelId(string, required)
Success: 200 DiscordLinkResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the text channels to choose the link channel fromGET /api/v1/workspaces/{workspaceId}/discord-link/channels
listDiscordLinkChannels
Reads the connected Discord server's text channels from Discord when asked (grouped by category, with readAt). There is no stored list: a very recent read is reused, and refresh=true reuses only an even more recent one. 409 state_conflict with reason not_connected, bot_not_in_server or discord_unavailable. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- refresh (query)
- See the downloadable contract for the field schema.
Success: 200 LinkChannelListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Connect the Discord server the bot was added toPOST /api/v1/workspaces/{workspaceId}/discord-link/connect
connectDiscordLink
Connects the Discord server Discord returned. The state must be the one this member was given in the last 30 minutes. The bot must really be in the server and no other workspace may hold it: 409 state_conflict with reason state_invalid, bot_not_in_server, guild_in_use or discord_unavailable. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body ConnectDiscordBody
guildId(string, required): The Discord server ID Discord returned.state(string, required): The state Discord returned.
Success: 200 DiscordLinkResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Choose who can search links in DiscordPUT /api/v1/workspaces/{workspaceId}/discord-link/find-roles
setDiscordLinkFindRoles
Sets which Discord roles (role IDs, at most 20) may use /link search and its Unlink button in the connected Discord server, besides people with Manage Server, who always can. An empty list puts the original rule back (Manage Server only), which is also what a workspace has until it saves a choice. Every use is checked against the member's roles in Discord's own signed request, so a role taken away stops working at the next press. While roles are chosen the command is listed to every member of the Discord server and anyone not allowed gets a private refusal. 422 too_many_roles or invalid_role on /roles; 409 state_conflict with reason not_connected. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body SetFindRolesBody
roles(list of string)
Success: 200 DiscordLinkResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Get the address that adds the bot to DiscordPOST /api/v1/workspaces/{workspaceId}/discord-link/install
startDiscordLinkInstall
Returns the address of Discord's own page that adds the bot to a server the member manages. Discord returns the browser to RustSC with the server and the signed state; post both to connect. Needs integrations.manage; answers 409 state_conflict (discord_not_configured) where the deployment has no bot.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 DiscordInstallResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Save the Discord invite linkPUT /api/v1/workspaces/{workspaceId}/discord-link/invite
setDiscordLinkInvite
Saves the invite link the game shows next to a player's code; null or empty clears it. Only https://discord.gg/<code> and https://discord.com/invite/<code> are accepted (422 on /invite, invalid_discord_invite); it is stored as https://discord.gg/<code>. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body SetInviteLinkBody
invite(string): A Discord invite link (`https://discord.gg/code` or `https://discord.com/invite/code`); null or empty clears it.
Success: 200 DiscordLinkResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the uploaded link filesGET /api/v1/workspaces/{workspaceId}/discord-link/link-uploads
listLinkUploads
The latest files this workspace uploaded to move its links from another link service, newest first, each with its state (ready, unrecognised, imported or removed) and counts. Never the file. Needs links.manage.
Workspace permission: links.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 LinkUploadsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Upload the data of the old link servicePOST /api/v1/workspaces/{workspaceId}/discord-link/link-uploads
uploadLinkData
Reads the file (base64 in content, at most 4 MiB) and keeps it. When a reader recognises the format and finds both the Steam ID and the Discord user ID of its players, the answer is state ready with the counts of the same check the staff import makes (nothing is changed yet); confirm it to make the links. When it cannot be sure, the answer is state unrecognised: the file is kept for support, a support request is open and nothing is imported. A ready file is deleted after 24 hours and an unrecognised one after 30 days unless it is confirmed or removed first. 422 at /content: file_empty, file_too_large or too_many_rows. 409 state_conflict with reason no_discord_server (connect Discord first) or too_many_uploads (remove one). Needs links.manage.
Workspace permission: links.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body UploadLinkDataBody
content(string): The file, base64 encoded.
Success: 200 LinkUploadResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Throw an uploaded file awayDELETE /api/v1/workspaces/{workspaceId}/discord-link/link-uploads/{uploadId}
removeLinkUpload
Deletes the file now. A finished import keeps only its counts. Needs links.manage.
Workspace permission: links.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- uploadId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Make the links from an uploaded filePOST /api/v1/workspaces/{workspaceId}/discord-link/link-uploads/{uploadId}/confirm
confirmLinkUpload
Makes the links of a ready file with the staff import's rules: an active link is never changed, a pair already linked is left alone, nobody is contacted, and the first membership check removes anyone who is not in the Discord server. The file is deleted. Repeating it changes nothing. 409 state_conflict upload_ended when the file expired or was removed. Needs links.manage.
Workspace permission: links.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- uploadId (path, required)
- See the downloadable contract for the field schema.
Success: 200 LinkUploadResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Turn the nickname sync on or offPUT /api/v1/workspaces/{workspaceId}/discord-link/nicknames
setDiscordLinkNicknames
Sets whether linked players' Discord nickname follows their Steam name (off by default). Turning it on covers every linked player who has not chosen to keep their Discord name; the bot changes a few at a time. 409 state_conflict with reason not_connected. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body SetNicknameSyncBody
enabled(boolean, required)
Success: 200 DiscordLinkResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Try the players who could not be renamed againPOST /api/v1/workspaces/{workspaceId}/discord-link/nicknames/retry
retryDiscordLinkNicknames
Tries once more for every linked player whose nickname could not be changed (use it after moving the bot's role above theirs). Nothing retries by itself. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 DiscordLinkResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the channels to post alerts and status inGET /api/v1/workspaces/{workspaceId}/discord-link/post-channels
listDiscordPostChannels
Lists text and announcement channels for alerts, status messages and rule posts. Each channel reports if the bot can post and which permissions it needs. For not_connected or bot_not_in_server, reconnect Discord before retrying. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- refresh (query)
- See the downloadable contract for the field schema.
Success: 200 PostChannelsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save the words players see for the linkPUT /api/v1/workspaces/{workspaceId}/discord-link/wording
setDiscordLinkWording
Saves the title of the pinned link message (at most 80 characters, one line), a welcome line above its steps (at most 300) and a line under "Linked to ..." in the private reply after a player linked (at most 200). Empty or null puts RustSC's words back. Line breaks are kept where the text can hold them, tabs become spaces and other control characters are dropped. The pinned message is edited in place within seconds. 422 too_long on /title, /welcome or /linkedReply; 409 state_conflict with reason not_connected. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body SetLinkWordingBody
linkedReply(string)title(string)welcome(string)
Success: 200 DiscordLinkResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Search the linked playersGET /api/v1/workspaces/{workspaceId}/player-links
searchPlayerLinks
The active links of this workspace, newest first, optionally filtered by query: digits match a Steam ID prefix or a Discord user ID, other text matches the Discord or Steam name (any part, any case). Repeat steamId (up to 50) to ask only about those exact Steam IDs, as the Players list does for the players on screen. At most limit (1 to 100, default 25). Never public and never another workspace's. Needs links.manage.
Workspace permission: links.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- query (query)
- See the downloadable contract for the field schema.
- limit (query)
- See the downloadable contract for the field schema.
- steamId (query)
- See the downloadable contract for the field schema.
Success: 200 PlayerLinksResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Sync the links nowPOST /api/v1/workspaces/{workspaceId}/player-links/sync
syncPlayerLinks
Checks every link of this workspace against Discord again now instead of waiting for the next regular check: a player who left the Discord server is unlinked, a link that shows only a Discord ID asks for its name, and, when the nickname sync is on, nicknames are updated. All servers of the workspace share the same links, so there is nothing to copy between them. Answers at once with the number of links; the bot works through them a few at a time. Running it again is harmless. 409 state_conflict with reason not_connected. Needs links.manage.
Workspace permission: links.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 SyncPlayerLinksResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
End a player's linkPOST /api/v1/workspaces/{workspaceId}/player-links/{linkId}/revoke
revokePlayerLink
Ends the link at once and deletes it with everything kept for it (the player can link again). The audit record says a link was ended and holds no player data. The body is optional and ignored (erase is no longer needed: every unlink deletes). Needs links.manage.
Workspace permission: links.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- linkId (path, required)
- See the downloadable contract for the field schema.
Request body RevokePlayerLinkBody
erase(boolean): Accepted and ignored.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
List the roles linked players getGET /api/v1/workspaces/{workspaceId}/role-benefits
listRoleBenefits
The rules that give linked players a Discord role, each with how many players it gave the role to, how many already had it and how many had it taken away by staff. problem says why a role cannot be given right now. available is false while no Discord server is connected. Needs integrations.read.
Workspace permission: integrations.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RoleBenefitsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Give linked players a Discord rolePOST /api/v1/workspaces/{workspaceId}/role-benefits
addRoleBenefit
Adds a rule: source linked gives the role to every linked player in the Discord server, source boosting only to those who boost it. The role is checked against Discord first; 409 state_conflict with the reason role_powerful, role_above, role_unavailable, role_missing, no_permission, benefit_exists, too_many_benefits or not_connected otherwise. RustSC gives the roles a few at a time; a role a player already has is theirs and is never taken back. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body AddRoleBenefitBody
graceHours(integer): Hours between finding eligibility lost and taking the role back, 0 to 168; default 24.roleId(string, required): The Discord role to give.source(string, required): `linked` or `boosting`.
Success: 200 RoleBenefitsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the Discord roles a rule can giveGET /api/v1/workspaces/{workspaceId}/role-benefits/roles
listRoleBenefitRoles
Reads the connected Discord server's roles from Discord when asked, strongest first, with the reason (problem) for each role that cannot be given: it is @everyone or belongs to an integration (role_unavailable), carries a powerful permission (role_powerful), is not below the bot's role (role_above), or the bot lacks Manage Roles (no_permission). Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BenefitRolesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List the Rust groups linked players can be added toGET /api/v1/workspaces/{workspaceId}/role-benefits/rust-groups
listLinkedGroupChoices
The workspace's servers and, with serverId, that server's Rust groups. A group marked staff holds game authority and cannot be chosen. Asks the game when asked; changes nothing. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (query)
- See the downloadable contract for the field schema.
Success: 200 LinkedGroupChoicesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Stop giving a Discord roleDELETE /api/v1/workspaces/{workspaceId}/role-benefits/{benefitId}
removeRoleBenefit
Removes a rule. By default (takeBack true) RustSC first takes back the roles RustSC gave under it and then the rule goes; takeBack=false leaves every role as it is. A role a player already had is never taken back. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- benefitId (path, required)
- See the downloadable contract for the field schema.
- takeBack (query)
- See the downloadable contract for the field schema.
Success: 200 RoleBenefitsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Give the roles staff took away againPOST /api/v1/workspaces/{workspaceId}/role-benefits/{benefitId}/reapply
reapplyRoleBenefit
Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- benefitId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RoleBenefitsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Stop adding linked players to a Rust groupDELETE /api/v1/workspaces/{workspaceId}/role-benefits/{benefitId}/rust-groups/{serverId}
removeLinkedGroup
By default (takeBack true) RustSC first takes out the players RustSC added, then the choice goes; takeBack=false leaves everyone in the group. A player who was in the group already is never taken out. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- benefitId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- takeBack (query)
- See the downloadable contract for the field schema.
Success: 200 RoleBenefitsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Also add linked players to a Rust groupPUT /api/v1/workspaces/{workspaceId}/role-benefits/{benefitId}/rust-groups/{serverId}
setLinkedGroup
Chooses the Rust group a linked-players rule also adds players to on one server. Only players who link from now on are added (shortly after they link); players who linked before are added only by add-linked. Saving changes nothing in the game. 409 state_conflict with the reason group_missing, group_is_staff, rust_unavailable, server_not_found, group_exists, managed_by_sync (a role sync already puts players in that group), invalid_group or benefit_not_found otherwise. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- benefitId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body SetLinkedGroupBody
group(string, required): The Rust group, by name; it must exist on the server and must not be a staff group.
Success: 200 RoleBenefitsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Add the players who already linked to the Rust groupPOST /api/v1/workspaces/{workspaceId}/role-benefits/{benefitId}/rust-groups/{serverId}/add-linked
addLinkedPlayersToGroup
Adds every player who linked before the group was chosen (and tries again the players the server refused). It is done a few at a time; the counts on the group show how far it is. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- benefitId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RoleBenefitsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the Discord role and Rust group syncsGET /api/v1/workspaces/{workspaceId}/role-syncs
listRoleSyncs
The syncs, each with its direction, what happens when a player loses the role or the group, how many players are the same on both sides, and why it cannot work now (problem) or that a side cannot be confirmed. rustConnected is false while this deployment cannot read or change a server's groups. Needs integrations.read.
Workspace permission: integrations.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RoleSyncsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Keep a Discord role and a Rust group in stepPOST /api/v1/workspaces/{workspaceId}/role-syncs
addRoleSync
Adds a sync of one Discord role and one Rust group. direction is discord_to_rust, rust_to_discord or both (both needs one server). Only linked players are touched. A role that cannot be given (role_powerful, role_above, role_unavailable, role_missing, no_permission) and a group that does not exist (group_missing) or cannot be read (rust_unavailable) are refused with 409 state_conflict. A staff group (group_is_staff: the admin or moderator group, or any group holding a dangerous permission) is refused unless an Owner sends allowStaff with confirmGroup the group's name (owner_only, confirmation_needed otherwise); that is always audited. Needs roles.sync.manage.
Workspace permission: roles.sync.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body AddRoleSyncBody
allowStaff(boolean): Only an Owner: allow writing to a staff group, with `confirmGroup` the group's name typed.confirmGroup(string)direction(string, required)graceHours(integer)group(string, required)removeWhenLost(boolean): Default true.roleId(string, required)serverId(string): The one server, or null for every server (one-way only; both ways needs one server).takeOver(boolean): Default false: players who held the group or the role before are left alone.
Success: 200 RoleSyncsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List what a sync can be made fromGET /api/v1/workspaces/{workspaceId}/role-syncs/choices
listRoleSyncChoices
Reads the connected Discord server's roles from Discord, the workspace's servers and, with serverId, that server's groups, each with the reason it cannot be used (problem on a role, staff on a group). Asks Discord and the game; changes nothing. Needs roles.sync.manage.
Workspace permission: roles.sync.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (query)
- See the downloadable contract for the field schema.
Success: 200 RoleSyncChoicesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Stop a syncDELETE /api/v1/workspaces/{workspaceId}/role-syncs/{syncId}
removeRoleSync
Removes a sync. By default (takeBack true) RustSC first takes away what the sync added, then the sync goes; takeBack=false leaves everything as it is. Players who held the group or role before the sync are never touched unless the sync took over. Needs roles.sync.manage.
Workspace permission: roles.sync.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- syncId (path, required)
- See the downloadable contract for the field schema.
- takeBack (query)
- See the downloadable contract for the field schema.
Success: 200 RoleSyncsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Give again what staff took awayPOST /api/v1/workspaces/{workspaceId}/role-syncs/{syncId}/reapply
reapplyRoleSync
Needs roles.sync.manage.
Workspace permission: roles.sync.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- syncId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RoleSyncsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Compare one sync's players again nowPOST /api/v1/workspaces/{workspaceId}/role-syncs/{syncId}/sync-now
syncRoleSyncNow
Changes nothing itself. Needs roles.sync.manage.
Workspace permission: roles.sync.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- syncId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RoleSyncsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Discord
Get a saved Discord look pictureGET /api/v1/workspaces/{workspaceId}/discord/pictures
getSavedDiscordPicture
A logo or banner saved for a server's Discord look, as RustSC's own copy, so a member's browser never contacts the picture's website. u is the saved address exactly as the Discord settings show it. Answers a small PNG, JPEG, WebP or GIF picture, kept for a day; 404 when the address is not saved in this workspace or the picture cannot be shown. Needs integrations.read.
Workspace permission: integrations.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Disconnect a server from DiscordDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/discord
disconnectDiscordBoard
Forgets the channel (a link saved before the bot became the only way to post is deleted too) and the board's state, and stops the posts. The messages already in the channel stay; delete them in Discord. Nothing happens when nothing was saved. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Read a server's Discord settingsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/discord
getDiscordBoard
The settings of a server's Discord posts and how they are working: the Discord channel (channelId, channelName; needsReconnect when the board has no channel yet and posts nothing until one is picked), the three switches (status message, player list, change posts), the columns beside the player's name and the sort order of the list (columns is null while no choice was made, which shows the standard columns; effectiveColumns says which those are), whether the status message shows the server FPS (showFps is null while no choice was made, which is off; fpsShown says what the message does now), whether it shows the map and the wipe time (showMap, showWiped), the server's own look, the join address, the last problem as a stable code, when Discord last took a post and whether the status message exists. While nothing was saved this is the defaults with revision 0. Needs integrations.read.
Workspace permission: integrations.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 DiscordBoardResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a server's Discord settingsPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/discord
saveDiscordBoard
Stores the settings as the next revision and starts the posts. The first save needs channelId, a channel from listDiscordPostChannels (checked again against the workspace's own connected Discord server); a later save may leave it out to keep the saved channel, and a different channel starts the status message fresh in it. A value that cannot be used is refused with 422 at its field: required, channel_not_found or channel_not_text at /channelId, too_long, name_not_allowed, invalid_url, not_https, invalid_color, invalid_address; for the player columns (fields columns/second and columns/third) invalid_column, duplicate_column and not_available, and for playerSort invalid_sort; 409 state_conflict with reason not_connected, bot_not_in_server, missing_permission (state names the channel and what is missing) or discord_unavailable. Saving again after Discord said the channel was deleted asks for another try. Works while the server or its host is offline. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body DiscordBoardBody
changeChannelId(string): A separate channel for the change posts, from the same list.changePosts(boolean): Post a short new message when the server changes state.channelId(string): The channel's Discord ID, from the list of `listDiscordPostChannels`.columns(DiscordColumnsBody)joinAddress(string): The address players type to join, for example `play.example.com:28015`; absent shows none.look(DiscordLookBody)mapName(string): Ignored.playerList(boolean): Show the names of the players online in that message.playerSort(string): How the list is sorted: `name` (A to Z, the default) or `time` (longest connected this session first).refreshMinutes(integer): Deprecated and ignored.showFps(boolean): Whether the status message shows the server's frame rate as a number (for example `62 FPS`), as of the last time a player joined or left or the status changed.showMap(boolean): Whether the status message shows the server's map name.showWiped(boolean): Whether the status message shows when the server was last wiped.statusBoard(boolean): Keep one live status message in the channel, edited in place.
Success: 200 DiscordBoardResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Turn off and forget a server's chat relayDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/discord/chat
disconnectDiscordChatRelay
Deletes the saved relay and every chat line still waiting for it. Messages already in the channel stay; delete them in Discord. Nothing happens when nothing was saved. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Read a server's chat relayGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/discord/chat
getDiscordChatRelay
The chat relay of a server: the Discord channel (channelId, channelName), the kill switch (enabled), the two directions (gameToDiscord, discordToGame), who may talk from Discord (whoSpeaks: anyone or linked), the muted Steam IDs, the last problem as a stable code and when Discord last took a post. While nothing was saved (saved is false) this is what the form is pre-filled with, revision 0, and nothing is relayed. Needs integrations.read.
Workspace permission: integrations.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ChatRelayResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a server's chat relayPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/discord/chat
saveDiscordChatRelay
Stores the choices as the next revision. Saving is what switches the relay on. The first save needs channelId, a channel from listDiscordPostChannels (checked again against the workspace's own connected Discord server); a later save may leave it out to keep the saved channel. A value that cannot be used is refused with 422 at its field: required or channel_not_found at /channelId, invalid at /whoSpeaks, invalid_steam_id or too_many at /mutedSteamIds, and at the members of /format: invalid at /format/game, /format/nameSource and /format/emoji, required, too_long or invalid (a template needs {message} and only {name}, {message}, {prefix}, {steamid}) at /format/template, too_long or invalid at /format/prefix, invalid_color at /format/prefixColor and /format/nameColor; 409 state_conflict with reason not_connected, bot_not_in_server, missing_permission or discord_unavailable; 409 capability_unavailable for a server that has no chat to relay. Saving again after Discord said the channel was deleted asks for another try. Works while the server or its host is offline. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body ChatRelayBody
channelId(string): The channel's Discord ID, from the list of `listDiscordPostChannels`.discordToGame(boolean): Say the channel's messages in the game.enabled(boolean): The kill switch: false stops both directions and keeps the rest.format(ChatRelayFormatBody)gameToDiscord(boolean): Post the server's global chat in the channel.mutedSteamIds(list of string): Steam IDs (17 digits) whose chat is not relayed in either direction; at most 100.whoSpeaks(string): `anyone` (everyone in the channel except bots) or `linked` (only Discord members linked to a Steam account).
Success: 200 ChatRelayResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Send a chat relay test linePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/discord/chat/test
testDiscordChatRelay
Posts one short line in the channel channelId, or in the saved channel when it is left out, so a member can see the bot can post there. A picked channel is checked against the workspace's own connected Discord server first and a permission the bot lacks is named in missing. Changes no setting. The answer says sent, or a stable problem code. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body DiscordTestBody
channelId(string): The channel to test, for example one just picked and not yet saved.
Success: 200 DiscordTestResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Send a Discord test messagePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/discord/test
testDiscordBoard
Posts one short message in the channel channelId, or in the saved channel when it is left out, so a member can see the bot can post there. A picked channel is checked against the workspace's own connected Discord server first and a permission the bot lacks is named in missing. Changes no setting. The answer says sent, or a stable problem code. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body DiscordTestBody
channelId(string): The channel to test, for example one just picked and not yet saved.
Success: 200 DiscordTestResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Hosts
List pending enrollment tokensGET /api/v1/workspaces/{workspaceId}/enrollment-tokens
listEnrollmentTokens
Tokens that can still be used, newest first, and the address of the host install script. Never the token text. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 EnrollmentTokenListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Create an enrollment tokenPOST /api/v1/workspaces/{workspaceId}/enrollment-tokens
createEnrollmentToken
Creates a single-use token that enrolls a host into this workspace, and returns its text once. Send an Idempotency-Key to repeat safely: a repeat returns the same token without its text. Needs hosts.enroll.
Workspace permission: hosts.enroll
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key, for example a UUID, per creation; repeat it only to repeat the same request after a lost response.
Request body IssueEnrollmentTokenRequestBody
hostId(string): A full host of this workspace to enroll a replacement installation on, for example `host_01jb8z3k4q7v9w2x5y6z8a0b1c`.sendHostLog(boolean): True when the Add host form was saved with "Send this host's log to the portal" ticked (the form pre-fills it ticked).
Success: 201 IssuedEnrollmentTokenResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, 503, default.
Read an enrollment tokenGET /api/v1/workspaces/{workspaceId}/enrollment-tokens/{tokenId}
getEnrollmentToken
One token in its current state, with the installation it created once used. Never its text. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- tokenId (path, required)
- See the downloadable contract for the field schema.
Success: 200 EnrollmentTokenResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Revoke an enrollment tokenPOST /api/v1/workspaces/{workspaceId}/enrollment-tokens/{tokenId}/revoke
revokeEnrollmentToken
Stops an unused token from working. Repeating it changes nothing. A used or expired token cannot be revoked. Needs hosts.enroll.
Workspace permission: hosts.enroll
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- tokenId (path, required)
- See the downloadable contract for the field schema.
Success: 200 EnrollmentTokenResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, default.
List hostsGET /api/v1/workspaces/{workspaceId}/hosts
listHosts
The workspace's hosts by name, each with its current installation, a pending replacement and whether each is connected. Needs hosts.read. A member who was given only some hosts sees only those, in the list and in the count.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 HostListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Read a hostGET /api/v1/workspaces/{workspaceId}/hosts/{hostId}
getHost
One host of the workspace, as the host list shows it: its name, system and host software version, its current installation with whether it is connected and when it last made contact, the software update and restart-needed state, and a pending replacement. Never a key. A host of another workspace, or one the member was not given, is 404 not_found. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Success: 200 HostResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Check what an update of the host would doPOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/actions/check-update
checkHostUpdate
Asks the host to read its signed update channel and answer, in the result of the returned operation: state (available, up_to_date, needs_earlier_update, nothing_for_this_computer, refused, unavailable, not_set_up, no_updater or running), installedVersion, availableVersion, the update channel and mode, approvalNeeded (a preview build must be approved on the host itself: the portal never approves one), a reason code when nothing can be offered, and busy: the kinds of the other operations running on the host. Nothing is downloaded or installed. The operations list does not show it. A host that is offline is refused (capability_unavailable, host_offline); a host that is too old to answer is refused (host_update_needed, or no_executor on arrival). Needs hosts.update.
Workspace permission: hosts.update
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body CheckHostUpdateRequestBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Request operating system updatesPOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/actions/run-os-updates
runHostOsUpdatesOperation
The operation succeeds when the host durably accepts the request. Installation and restart progress are reported separately. Needs hosts.reboot.
Workspace permission: hosts.reboot
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body CheckHostUpdateRequestBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Choose when the host gets updatesPOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/actions/set-update-channel
setHostUpdateChannel
Set channel to beta for early releases or production for proven releases. This choice applies to future update offers. If it returns updated_by_package, use the host's package settings. Needs hosts.update.
Workspace permission: hosts.update
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body SetHostUpdateChannelRequestBody
admission(AdmissionBody)channel(string): `beta` gets updates early; `production` gets them when they are proven.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Turn the host's automatic updates on or offPOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/actions/set-update-policy
setHostUpdatePolicy
Set mode to manual or automatic. Automatic requires the Production channel. When the host is offline, retry after it reconnects. Follow the operation to see the applied policy. Needs hosts.update.
Workspace permission: hosts.update
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body SetHostUpdatePolicyRequestBody
admission(AdmissionBody)mode(string): `automatic` installs new versions of RustSC on the host by itself; `manual` only when someone presses Update host or runs the update on the host.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Update the hostPOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/actions/update
updateHost
Update RustSC on the host to availableVersion from its update check. The games keep running. Set whileBusy to allow the update to interrupt other RustSC work on the host. If the result is not_offered, check again. On rolled_back, the previous version is still running. Follow the returned operation for the result. Needs hosts.update.
Workspace permission: hosts.update
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body UpdateHostRequestBody
admission(AdmissionBody)version(string): The version the member confirmed, from the check's `availableVersion`, for example `0.2.7`.whileBusy(boolean): True when the member confirmed that the update may interrupt other work running on the host; absent means false.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read a folder on a hostPOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/folders/browse
readHostFolder
Lists the sub-folders of a folder on the host, for choosing where a server is installed, and answers in one response without an operation: the same listing the result of browseHostFolder holds, in camelCase, with the size of the volume (totalBytes) as well as the free bytes. Directory names only (never file names or contents), sorted, at most 200 with a count of the rest (more). A folder that does not exist is answered with its nearest existing parent (exists false). A folder the host cannot open or a host that cannot browse is a 200 with failure (no_access, input_invalid, unsupported, broker_unavailable) and no listing. A host that is offline is capability_unavailable (host_offline); a host that does not answer in time or answers in part is dependency_unavailable (dependency host, reason timed_out or incomplete); a host that is reading as many folders as it may is dependency_unavailable with reason busy. A host whose software is older than this request is capability_unavailable (not_reported): use browseHostFolder instead. With find true the host also looks for Rust servers in the folder and the folders directly under it (names only, nothing changed) and the listing carries found: at most 8, each with its name, path and the names of its settings folders; a host whose software is older leaves found out. Nothing is written, admitted, stored or audited. Needs servers.create, or backups.manage on the server named in serverId (a server on this host, for choosing its backup folder).
Workspace permission: servers.create
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Request body ReadFolderRequestBody
find(boolean): True to also have the host look for Rust servers in the folder and the folders directly under it (names only, nothing changed); the listing then carries `found`.path(string): The folder to list, an absolute path on the host, for example `/srv/rust` or `C:\RustSC\Servers`.serverId(string): The server on this host whose backup folder is being chosen (`srv_...`).
Success: 200 ReadFolderResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, 503, default.
List a host's log linesGET /api/v1/workspaces/{workspaceId}/hosts/{hostId}/log-lines
listHostLogLines
The host's own log lines, newest first, with a level filter (level information, warning or error; error includes critical) and a text search over the event name and the line (q). Older than 14 days are not shown; each line says in source which part of the host wrote it; the lines are redacted by the host and never hold the game's console. limit is 1 to 200 (default 100); read the next page with before set to the time of the last line. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- level (query)
- See the downloadable contract for the field schema.
- q (query)
- See the downloadable contract for the field schema.
- before (query)
- See the downloadable contract for the field schema.
- limit (query)
- See the downloadable contract for the field schema.
Success: 200 HostLogLineListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Rename a host in RustSCPUT /api/v1/workspaces/{workspaceId}/hosts/{hostId}/name
renameHost
Changes the name RustSC shows for the host, everywhere. It never changes the host's own name or anything on it. 1 to 100 characters after trimming, no control characters. Needs hosts.manage.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Request body RenameBody
name(string, required): 1 to 100 characters after trimming, no control characters.
Success: 200 RenamedResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read a host's update settingsGET /api/v1/workspaces/{workspaceId}/hosts/{hostId}/os-updates
getHostOsUpdates
The saved choice for installing operating system updates (off until the form is saved) and where the run stands. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Success: 200 HostOsUpdatesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a host's update settingsPUT /api/v1/workspaces/{workspaceId}/hosts/{hostId}/os-updates
saveHostOsUpdates
Save when to install host updates. Saving a separate update schedule removes it from any restart schedule. Needs hosts.reboot, which only an Owner holds.
Workspace permission: hosts.reboot
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Request body SaveHostOsUpdatesBody
aheadOfRestart(boolean): Install ahead of the servers' restart and restart the host at that restart.days(list of integer): ISO weekdays, 1 Monday to 7 Sunday; empty or absent is every day.delayDays(integer): after_available only: whole days to wait after the updates first appear, 0 to 30; 3 by default.include(string): `important` (security and important updates; the standard), `important_and_optional` or `everything` (drivers included).leadMinutes(integer): Minutes before the restart the install starts, 60 to 240; 120 by default.mode(string): `off` (the standard), `schedule` (install at a day and time, then restart if needed) or `after_available` (install a number of days after updates appear).restartWindowHours(integer): How far after the chosen time a server restart still counts, in hours, 1 to 72; 24 by default.takeOverWindowsRestarts(boolean): Let RustSC stop Windows restarting by itself so it can pick the time; the previous settings are saved and put back when this or the mode is turned off.time(string): Local time of day, `HH:mm`; 04:00 by default.timeZone(string): An IANA time zone name for the day and time; absent or null is the host's own.
Success: 200 HostOsUpdatesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Run the host's updates nowPOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/os-updates/run
runHostOsUpdates
Does what the saved choice says now: installs, and restarts only if the updates need it. Needs hosts.reboot, which only an Owner holds.
Workspace permission: hosts.reboot
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Success: 200 HostOsUpdatesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Reconnect a hostPOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/reconnect
reconnectHost
Creates a single-use token that connects this host again, and returns its text once with the address to give the install command. Running the command on that host replaces the host's connection to RustSC and keeps its servers. Send an Idempotency-Key to repeat safely: a repeat returns the same token without its text. Needs hosts.enroll on the host.
Workspace permission: hosts.enroll
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key, for example a UUID, per press of Reconnect; repeat it only to repeat the same request after a lost response.
Success: 201 IssuedEnrollmentTokenResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 503, default.
List host restart schedulesGET /api/v1/workspaces/{workspaceId}/hosts/{hostId}/restart-schedules
listHostRestartSchedules
The host's restart schedules with their current revision, oldest first. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Success: 200 HostRestartScheduleListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Schedule a host restartPOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/restart-schedules
createHostRestartSchedule
Saves and approves a restart of the host's operating system at revision 1, once or on a calendar. The host runs the schedule itself and keeps running it while the cloud is unreachable; hostDelivery shows when the host stored it. At each occurrence the host warns players for the timing's leadMinutes, saves and stops every server, restarts the host and checks that the servers return, exactly as the restart now action does, and raises no alert for the planned outage. With onlyWhileRebootPending an occurrence runs only while the operating system reports that it needs a restart; otherwise it is skipped with condition_not_met. With pauseServerRestarts the host skips the scheduled restarts of the servers on any day this schedule restarts the host (computer_restarts_today), so no server restarts twice. An occurrence that finds the host busy or too late is skipped with its reason, never run late or held. A restricted host cannot be restarted (capability_unavailable, restricted_host). Needs hosts.reboot, which only an Owner holds.
Workspace permission: hosts.reboot
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body HostRestartScheduleRequestBody
enabled(boolean)installUpdates(InstallUpdatesBody)onlyWhileRebootPending(boolean): True runs an occurrence only while the host reports that its operating system needs a restart; otherwise the occurrence is skipped with `condition_not_met`.pauseServerRestarts(boolean): True: on a day this schedule restarts the host (it ran, or will run because it always restarts or the host needs a restart now), the host skips the scheduled restarts of the ser...timing(ScheduleTimingBody)
Success: 201 HostRestartScheduleResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Read a host restart scheduleGET /api/v1/workspaces/{workspaceId}/hosts/{hostId}/restart-schedules/{scheduleId}
getHostRestartSchedule
The schedule at its current revision with its next occurrence; the ETag carries the revision. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- scheduleId (path, required)
- See the downloadable contract for the field schema.
Success: 200 HostRestartScheduleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change a host restart schedulePUT /api/v1/workspaces/{workspaceId}/hosts/{hostId}/restart-schedules/{scheduleId}
updateHostRestartSchedule
Saves and approves the next revision. Requires If-Match with the revision you read. Needs hosts.reboot.
Workspace permission: hosts.reboot
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- scheduleId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body HostRestartScheduleRequestBody
enabled(boolean)installUpdates(InstallUpdatesBody)onlyWhileRebootPending(boolean): True runs an occurrence only while the host reports that its operating system needs a restart; otherwise the occurrence is skipped with `condition_not_met`.pauseServerRestarts(boolean): True: on a day this schedule restarts the host (it ran, or will run because it always restarts or the host needs a restart now), the host skips the scheduled restarts of the ser...timing(ScheduleTimingBody)
Success: 200 HostRestartScheduleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
List occurrencesGET /api/v1/workspaces/{workspaceId}/hosts/{hostId}/restart-schedules/{scheduleId}/occurrences
listHostRestartScheduleOccurrences
Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- scheduleId (path, required)
- See the downloadable contract for the field schema.
Success: 200 OccurrenceListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Remove a host restart schedulePOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/restart-schedules/{scheduleId}/revoke
revokeHostRestartSchedule
Ends the schedule with a final revision at the revision in If-Match. Its occurrences stay as history. Needs hosts.reboot.
Workspace permission: hosts.reboot
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- scheduleId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Success: 200 HostRestartScheduleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Read a host's restart with the server restart choiceGET /api/v1/workspaces/{workspaceId}/hosts/{hostId}/restart-with-server-restart
getHostRestartWithServerRestart
Whether the host restarts with the next scheduled server restart when the operating system says it needs a restart. Off until the choice is saved; saved is false until then. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Success: 200 HostRestartSettingResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a host's restart with the server restart choicePUT /api/v1/workspaces/{workspaceId}/hosts/{hostId}/restart-with-server-restart
saveHostRestartWithServerRestart
When enabled, a pending host restart can take the place of the first scheduled server restart with enough time for the player warning. Other scheduled server restarts on that host are skipped that day (computer_restarts_today). Needs hosts.reboot, which only an Owner holds.
Workspace permission: hosts.reboot
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Request body SaveHostRestartSettingBody
restartWithServerRestart(boolean, required): True: when the host says it needs a restart, the next scheduled server restart restarts the host.
Success: 200 HostRestartSettingResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List what a host did and how it endedGET /api/v1/workspaces/{workspaceId}/hosts/{hostId}/steps
listHostSteps
The steps of the host's own work, newest first: what it installed, updated, backed up, restored, wiped or decided, how each ended, a short reason when it did not go well and the cleaned end of its output. The host sends them on its own; older than 14 days are not shown. limit is 1 to 200 (default 50); read the next page with before set to the end time of the last step. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- before (query)
- See the downloadable contract for the field schema.
- limit (query)
- See the downloadable contract for the field schema.
Success: 200 HostStepListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Evidence
Download the events of the servers you can exportGET /api/v1/workspaces/{workspaceId}/evidence/export
exportEvidenceSearch
The events a search finds (the same filters as searchEvidence: serverId, category, q, player, from, until) as one file: format json (the default; a summary with the scope, who asked and when, the servers covered, the retention and the field classes left out, then the events with their servers) or csv (one row per event with its server). It covers the servers where the caller holds both evidence.export and evidence.read, and a server without both is left out and never counted; private chat is included only on servers where the caller also holds evidence.read.private. The file is written as the pages are read and nothing is kept on RustSC's side; once downloaded it is outside RustSC and cannot be recalled. Each export is audited (evidence.export) with the format and the filters, never an event's text. Needs evidence.export on at least one server.
Workspace permission: evidence.export
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- format (query)
- See the downloadable contract for the field schema.
- serverId (query)
- See the downloadable contract for the field schema.
- category (query)
- See the downloadable contract for the field schema.
- q (query)
- See the downloadable contract for the field schema.
- player (query)
- See the downloadable contract for the field schema.
- from (query)
- See the downloadable contract for the field schema.
- until (query)
- See the downloadable contract for the field schema.
Success: 200. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Search the events of the servers you can readGET /api/v1/workspaces/{workspaceId}/evidence/search
searchEvidence
One page of recorded events across every server the caller may read evidence on, newest first. serverId narrows it to some servers, category to categories, q to events whose text contains the words (a plain, case-insensitive substring of at most 100 characters), player to events that name that Steam ID as actor or subject, from and until to a time range, and before continues after a page. limit is 1 to 200 (default 50). The first page also carries counts by category for the whole search. A server the caller may not read is left out and never counted; private chat appears only for a caller who holds evidence.read.private on that server. Evidence older than the retention is not searched, and a quiet result is not proof that nothing happened: gaps are shown on each server's Events tab. Needs an active membership and evidence.read on the servers searched.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (query)
- See the downloadable contract for the field schema.
- category (query)
- See the downloadable contract for the field schema.
- q (query)
- See the downloadable contract for the field schema.
- player (query)
- See the downloadable contract for the field schema.
- from (query)
- See the downloadable contract for the field schema.
- until (query)
- See the downloadable contract for the field schema.
- before (query)
- See the downloadable contract for the field schema.
- limit (query)
- See the downloadable contract for the field schema.
Success: 200 EvidenceSearchResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Delete what a server capturedDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/evidence
eraseEvidence
Removes the events captured to date from lists, searches and exports. Send category to remove only selected categories. Future events continue to appear. Reports in the inbox are separate (delete a report, or every report about a player), the audit trail names the server and the categories only, and downloaded copies cannot be recalled. Repeating it is harmless. An unknown category is 422 at /category. Needs evidence.delete on the server (Owner and Administrator).
Workspace permission: evidence.delete
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- category (query)
- See the downloadable contract for the field schema.
Success: 200 ErasedEvidenceResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read the events a server recordedGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/evidence
listEvidence
One page of the server's recorded events, newest first, with the gaps that overlap the page. category narrows it to one or more categories, q to events whose text contains the words, limit is 1 to 200 (default 50) and before continues after a page (pass the next value of the previous page): a page is stable while new events arrive. A category that is off or aged out is absent: a gap says that time was not covered. Private chat records appear only for a caller who also holds evidence.read.private. F7 reports are read through the report inbox. Needs evidence.read.
Workspace permission: evidence.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- category (query)
- See the downloadable contract for the field schema.
- q (query)
- See the downloadable contract for the field schema.
- before (query)
- See the downloadable contract for the field schema.
- limit (query)
- See the downloadable contract for the field schema.
Success: 200 EvidencePageResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Read what a server records of its historyGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/evidence-capture
getEvidenceCapture
The switches that decide what the server records: which are on, whether the RustSC plugin is in the server's plugin list (F7 reports and the system facts need it) and whether the caller may change them. Until someone changes them every offered switch is on (revision 0). Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 EvidenceCaptureResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Choose what a server records of its historyPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/evidence-capture
saveEvidenceCapture
Stores the switches that are on as the next revision and gives them to the server's host (an offline host gets them when it returns). From the moment of the save cloud intake also drops events of a switch that was off when they happened, however late they arrive; events already recorded age out normally. A switch that cannot be turned on yet is refused with 422 at /enabled as not_available, an unknown name as unknown_value. A save that changes nothing keeps the revision. A rented server records no history, so its save is refused (409 capability_unavailable, restricted_host). Needs servers.config.write.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body EvidenceCaptureBody
enabled(list of string): The names of the switches that are on.
Success: 200 EvidenceCaptureResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Download the events a server recordedGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/evidence/export
exportEvidence
The same events as listEvidence as one file: format json (the default; a summary with the scope, who asked and when, the capture switches, the retention, the field classes left out and the gaps, then the events) or csv (one row per event). category and q narrow it as they do the list. A file holds only what the caller may read, only events still within retention, and nothing is reconstructed for an older range. The file is written as the pages are read and nothing is kept on RustSC's side; once downloaded it is outside RustSC and cannot be recalled. Each export is audited (evidence.export) with the format and filters. Needs evidence.export and evidence.read.
Workspace permission: evidence.export
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- format (query)
- See the downloadable contract for the field schema.
- category (query)
- See the downloadable contract for the field schema.
- q (query)
- See the downloadable contract for the field schema.
Success: 200. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Read one recorded event with the events around itGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/evidence/{evidenceId}
getEvidence
One event and up to 20 events recorded just before and just after it on the same server (around, default 5). An event that does not exist, aged out or is private chat the caller may not read is 404. Needs evidence.read.
Workspace permission: evidence.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- evidenceId (path, required)
- See the downloadable contract for the field schema.
- around (query)
- See the downloadable contract for the field schema.
Success: 200 EvidenceDetailResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Performance
Get the combined performance of the servers or of one groupGET /api/v1/workspaces/{workspaceId}/fleet-performance
getFleetPerformance
Players and frame rate of the servers the caller may read (the whole workspace, or the group in groupId), from the same stored buckets as each server's own history, for the combined dashboards. range is hour, day (the default), week or month. history.series holds server.players (per bucket the sum of the servers' averages; lowest and highest are the sums of the servers' lowest and highest, which bound the total) and server.fps (the mean of the servers' averages; lowest and highest are the lowest and highest on any server). servers lists each server the caller may read with its newest figures, its peak players, its lowest frame rate and observedAt, so a stale figure is seen as stale. A server the caller cannot see is not listed, counted or in any figure. At most 50 servers are covered; truncated says there were more. available is false when this cloud keeps no history. Needs a workspace membership; each server needs servers.read to be included.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- range (query)
- See the downloadable contract for the field schema.
- groupId (query)
- See the downloadable contract for the field schema.
Success: 200 FleetPerformanceResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Get the latest host measurementsGET /api/v1/workspaces/{workspaceId}/hosts/{hostId}/measurements
getHostMeasurements
Current host observations and reported volumes. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Success: 200 HostMeasurementsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Get the performance history of a hostGET /api/v1/workspaces/{workspaceId}/hosts/{hostId}/performance
getHostPerformance
The measurements RustSC keeps of the whole host, for the host's Performance page, and beside them each game server's own. history.series holds the host's own figures as the operating system measures them, including everything running on it: host.cpu_percent, host.memory_used_bytes, host.network.received_bytes_per_second, host.network.sent_bytes_per_second, host.disk_used_bytes and host.disk_total_bytes (the drives that hold game folders, each once) and host.uptime_seconds. servers lists each server on the host the caller may read, with only that server's own server.cpu_percent, server.memory_bytes and server.players; the two sets are separate and are not meant to add up (the host's include the system and every other program). range is hour (1 minute buckets), day (5 minutes), week (30 minutes) or month (2 hours); the default is day. Each series lists the buckets that hold a sample, oldest first, with the count, average, lowest and highest value: nothing is smoothed or filled; a missing bucket means nothing was reported then. At most 6 servers; truncated says there were more. history.markers is always empty. available is false when this cloud keeps no history. Needs hosts.read; a server needs servers.read to be listed.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- range (query)
- See the downloadable contract for the field schema.
Success: 200 HostPerformanceResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Get the latest server measurementsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/measurements
getServerMeasurements
Latest raw observations, with their source times. Needs servers.read. Missing observations are not zero.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ServerMeasurementsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Get the performance history of a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/performance
getServerPerformance
The measurements RustSC keeps of the server itself, for charts: the game's frame rate, players, entities, and the game process's processor use and memory. Nothing about the host is here; see the host's performance. range is hour (1 minute buckets), day (5 minutes), week (30 minutes) or month (30 days, 2 hours); the default is day. Each series lists the buckets that hold a sample, oldest first, with the count, average, lowest and highest value: nothing is smoothed or filled; a missing bucket means nothing was reported then. At most 360 points a series. markers lists the restarts and wipes RustSC did in the range, oldest first; one done outside RustSC has no marker. available is false when this cloud keeps no history. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- range (query)
- See the downloadable contract for the field schema.
Success: 200 PerformanceHistoryResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Schedules
Read the next force wipe daysGET /api/v1/workspaces/{workspaceId}/force-wipes
getForceWipeDates
The next force wipe days after now: the moment of each (the first Thursday of the month at 19:00 in Europe/London, unless the platform owner published another moment for that month, which fromException shows) and, when you give a clock time (time, HH:mm in timeZone, the wipe is at that time on the local date of the moment) or minutes after the moment (offsetMinutes, 0 to 1440), the wipe time of each day. defaultTime is the clock time a new schedule starts at (one hour after the next moment). With a time, refusal names the first day in the next 24 months on which that time is before the moment, which saving a schedule would refuse (before_force_wipe). count is 1 to 12 days (default 3). Needs workspace membership.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- timeZone (query, required)
- The member's IANA time zone, for example Europe/London.
- time (query)
- A clock time HH:mm in timeZone: the wipe is at that time on the local date of the force wipe moment.
- offsetMinutes (query)
- Minutes after the force wipe moment, 0 to 1440, instead of time.
- count (query)
- How many days, 1 to 12 (default 3).
Success: 200 ForceWipeDatesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Work out the next runs of a schedulePOST /api/v1/workspaces/{workspaceId}/schedules/preview
previewSchedule
The next 5 runs of a schedule being written, in each of the given IANA zones (1 to 20), worked out by the same calculator that runs schedules, with a note on a run that daylight saving or the month's length moves. The timing is the one createSchedule takes; its timeZone is ignored. Reads and stores nothing; any member may ask. Timing errors are those createSchedule gives, at the same pointers; a zone the calculator does not know is unknown_time_zone at /timeZones/{index}.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body SchedulePreviewRequestBody
timeZones(list of string): The IANA zones to work the runs out in, 1 to 20: typically the zone of each chosen server, or the one zone used for all of them.timing(ScheduleTimingBody)
Success: 200 SchedulePreviewResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List past schedule runsGET /api/v1/workspaces/{workspaceId}/schedules/runs
listScheduleRuns
What every schedule the caller may read did, newest first: each decided run with its kind, the server or host by name, the intended time and the time zone it ran in, and its outcome (done, skipped, failed, cancelled, running or unconfirmed) with the skip reason or the operation's error code and the operation to open. A server's runs need servers.setup.read on it, a host's need hosts.read. Runs of removed schedules stay. Optional filters: placeId, scheduleId, kind and outcome (repeat for several), since (inclusive) and until (exclusive). Under an outcome filter one read looks through at most 1000 runs, so a page can hold fewer items and still have a nextCursor.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- placeId (query)
- Only this server or host, for example srv_01jb8z3k4q7v9w2x5y6z8a0b1c.
- scheduleId (query)
- Only this schedule, for example sch_01jb8z3k4q7v9w2x5y6z8a0b1c.
- kind (query)
- Only these kinds: restart, wipe, backup, update, check, message, command, post or hostRestart; repeat for several.
- outcome (query)
- Only these outcomes: done, skipped, failed, cancelled, running or unconfirmed; repeat for several.
- since (query)
- Runs intended at or after this time (RFC 3339).
- until (query)
- Runs intended before this time (RFC 3339).
- limit (query)
- Page size.
- cursor (query)
- The nextCursor of the previous page, with the same filters.
Success: 200 ScheduleRunListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
List upcoming schedulesGET /api/v1/workspaces/{workspaceId}/schedules/upcoming
listUpcomingSchedules
At most 500 rows. Each source is read with its own permission (servers.read for a server's rows, hosts.read for a host's, alerts.read for quiet times); a source the caller may not read adds nothing. incomplete is true when a source could not be read.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 UpcomingScheduleListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read RustSC's default Discord announcementGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/announcements/{ownerKind}
getScheduleAnnouncementDefaults
RustSC's own announcement for a kind of owner (schedule or timed_change): every moment off, its own post for each moment (the editor pre-fills it and Reset to defaults puts it back), no channel and nobody mentioned. Changes nothing. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- ownerKind (path, required)
- See the downloadable contract for the field schema.
Success: 200 ScheduleAnnouncementResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read the Discord announcement of a schedule or temporary changeGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/announcements/{ownerKind}/{ownerId}
getScheduleAnnouncement
The saved announcement of a schedule (sch_) or temporary change (tch_), or RustSC's defaults (saved false, every moment off) when none was saved. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- ownerKind (path, required)
- See the downloadable contract for the field schema.
- ownerId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ScheduleAnnouncementResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save the Discord announcement of a schedule or temporary changePUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/announcements/{ownerKind}/{ownerId}
saveScheduleAnnouncement
Sets which moments post in Discord (warning for a restart, wipe or game update, start and end for a temporary change), where (channel, rte_) and which Discord roles are mentioned. Nothing posts until a moment is on and saved. At most 10 roles; special everyone or here pings only when the bot may mention everyone. A value that cannot be used is refused with 422 at its field (required, too_many, too_long, invalid, unknown_variable, unsupported_variable, unsupported_format, malformed_placeholder, unsafe_mention). The host never sees it. Needs schedules.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- ownerKind (path, required)
- See the downloadable contract for the field schema.
- ownerId (path, required)
- See the downloadable contract for the field schema.
Request body ScheduleAnnouncementBody
channel(string): The Discord channel to post in (`rte_`); required while a moment is on.moments(object, required): The moments by name: `warning` for a schedule, `start` and `end` for a temporary change.roles(list of ScheduleAnnouncementRoleWire): Up to 10 Discord roles to mention, by ID; the name is shown on the screen only.special(string): `everyone` or `here`; left out for neither.
Success: 200 ScheduleAnnouncementResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List schedulesGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/schedules
listSchedules
The server's schedules with their current revision, oldest first. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ScheduleListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Create a schedulePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/schedules
createSchedule
Saves and approves a recurring restart, saved command, saved broadcast, game update, game update check, local backup, wipe or Discord post of this server at revision 1. The host runs it, also while the cloud is unreachable; hostDelivery shows when the host stored the revision. A discord.post is the exception: the cloud posts it in the channels named (no host needed, no hostDelivery), only while the cloud is reachable, and an occurrence more than 5 minutes late is skipped as missed; leadMinutes must be 0. For server.command and server.broadcast, definition names the saved definition at the revision you read; an occurrence the game cannot be reached for is skipped. A server.update_game occurrence does nothing when there is no newer build; leadMinutes is its player warning. A server.backup takes leadMinutes 0 and no definition or output preference. A world.reset is the simple wipe unless wipe says otherwise: player warning for leadMinutes, protective backup first; a missed, stopped or busy occurrence is skipped with its reason, never run late. Needs schedules.manage and the scheduled action's permission: servers.lifecycle, servers.console.execute, automation.manage, backups.create, servers.software.manage (an update also servers.lifecycle) or worlds.reset (a wipe also servers.lifecycle).
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body ScheduleRequestBody
channels(list of string): Required for `discord.post`, not allowed otherwise: the workspace's Discord channels (`rte_` IDs) the post goes to, 1 to 10.definition(ScheduleDefinitionBody)enabled(boolean)keepOutput(boolean): Required for `server.command`, not allowed otherwise: whether each occurrence keeps the game's reply text (redacted).kind(string): What each occurrence does: `server.restart`, `server.command` (a saved command), `server.broadcast` (a saved broadcast), `server.update_game` (updates only when a newer build ex...pauseUsualRestarts(boolean): For `world.reset`: true pauses the server's usual restarts and game updates from the start of the wipe day until the wipe has finished, so an update cannot wipe the server early.post(DiscordPostWire)timing(ScheduleTimingBody)warningMessage(string): For `server.restart`, optional: what the countdown says in game chat before each restart, instead of the server's restart message.wipe(WipeOptionsBody)
Success: 201 ScheduleResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Read a scheduleGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/schedules/{scheduleId}
getSchedule
The schedule at its current revision with its next occurrence and host delivery; the ETag carries the revision. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- scheduleId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ScheduleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change a schedulePUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/schedules/{scheduleId}
updateSchedule
Saves and approves the next revision. Requires If-Match with the revision you read. An offline host keeps running the revision it holds until it receives this one. The kind cannot change. Needs schedules.manage and the scheduled action's permission.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- scheduleId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body ScheduleRequestBody
channels(list of string): Required for `discord.post`, not allowed otherwise: the workspace's Discord channels (`rte_` IDs) the post goes to, 1 to 10.definition(ScheduleDefinitionBody)enabled(boolean)keepOutput(boolean): Required for `server.command`, not allowed otherwise: whether each occurrence keeps the game's reply text (redacted).kind(string): What each occurrence does: `server.restart`, `server.command` (a saved command), `server.broadcast` (a saved broadcast), `server.update_game` (updates only when a newer build ex...pauseUsualRestarts(boolean): For `world.reset`: true pauses the server's usual restarts and game updates from the start of the wipe day until the wipe has finished, so an update cannot wipe the server early.post(DiscordPostWire)timing(ScheduleTimingBody)warningMessage(string): For `server.restart`, optional: what the countdown says in game chat before each restart, instead of the server's restart message.wipe(WipeOptionsBody)
Success: 200 ScheduleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
List occurrencesGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/schedules/{scheduleId}/occurrences
listScheduleOccurrences
Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- scheduleId (path, required)
- See the downloadable contract for the field schema.
Success: 200 OccurrenceListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Revoke a schedulePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/schedules/{scheduleId}/revoke
revokeSchedule
Ends the schedule with a final revision at the revision in If-Match. Its occurrences stay as history. An offline host keeps running the revision it holds until it receives the revocation. Needs schedules.manage and the scheduled action's permission.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- scheduleId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Success: 200 ScheduleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Read the workspace's time zoneGET /api/v1/workspaces/{workspaceId}/time-zone
getWorkspaceTimeZone
The time zone used for the schedules of a server whose host has not said its own zone and that has no zone chosen for it; null when none was saved. Any member may read it.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WorkspaceTimeZoneResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save the workspace's time zonePUT /api/v1/workspaces/{workspaceId}/time-zone
setWorkspaceTimeZone
Saves the time zone used for the schedules of a server whose host has not said its own zone and that has no zone chosen for it, an IANA id, or null to clear it. Schedules already saved keep their zone. Needs workspace.manage. An unknown zone is 422 unknown_time_zone.
Workspace permission: workspace.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body WorkspaceTimeZoneRequestBody
timeZone(string): An IANA zone id such as `Europe/Berlin`, or null to clear it.
Success: 200 WorkspaceTimeZoneResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Server software
List the Steam branches of the Rust serverGET /api/v1/workspaces/{workspaceId}/game-branches
listGameBranches
Lists the available branches, public first then by name, with each branch's build number and last change. RustSC cannot install a password-protected branch. retrievedAt shows when the list was last updated. If no list is available, branches is empty and retrievedAt is absent. You can still enter a branch name when adding a server. Needs workspace membership.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 GameBranchesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Install, update or remove a supporting extensionPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/change-extension
changeExtension
Warns players for warningMinutes (default 5) and restarts the game to change RustEdit. Its configuration and data are kept. install and update are the same change: the latest release is made the installed one. When the file already is that release, or a removal finds nothing to remove, nothing is stopped and the operation ends at once with noChange. Install requires Oxide or Carbon (framework_required). If a release cannot be used, the error is release_unavailable or release_unverifiable. Returns the extension change operation. Needs servers.software.manage and servers.lifecycle on a ready server. On a rented server, install and update put the latest release in place through the server's files and nothing is restarted: the game loads it at its next restart. remove is not offered there. Needs servers.software.manage.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ChangeExtensionRequestBody
action(string, required): `install`, `update` (replace the installed file with the latest release) or `remove`.admission(AdmissionBody)extension(string, required): The extension: `rustedit`.warningMinutes(integer): Minutes of player warning before the server stops, from 0 to the longest warning (60); players see a countdown in chat.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Install, upgrade, switch or uninstall Oxide or CarbonPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/change-framework
changeFramework
Warns players for warningMinutes (default 5) and restarts the game to apply the framework change. Plugins, configuration and data are kept. With updateGame true this also updates the game in the same restart. Uninstall refuses that option (422 on /updateGame). Only one framework can be installed. Uninstall requires an installed framework (no_framework). If a release cannot be used, the error is release_unavailable or release_unverifiable. Returns the framework change operation. Needs servers.software.manage and servers.lifecycle on a ready server.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ChangeFrameworkRequestBody
action(string, required): `remove_old_files` removes, after a switch, the copies of plugins, settings and data left in the old framework's folders that have identical copies in the new framework's folders.admission(AdmissionBody)backup(boolean): True takes an ordinary backup after the server stops, before anything changes; false takes none.bringBack(boolean): The answer to "Bring back your plugins, settings and data?" on an `install` (422 on `/bringBack` for another action).changeChannel(boolean): True moves the framework to the channel chosen with `selectReleaseChannel` (for example Carbon `edge`) when it differs from the installed one.framework(string): `oxide` or `carbon`: the framework to install, upgrade, reinstall or switch to; for `remove_old_files` the old framework whose copies go (not the one installed).installRustscPlugin(boolean): The install form's pre-ticked "Install the RustSC plugin" option (`install` only; 422 on `/installRustscPlugin` for another action).updateGame(boolean): Not for `uninstall` (422 on `/updateGame`).warningMinutes(integer): Minutes of player warning before the server stops, from 0 to the longest warning (60); players see a countdown in chat.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Change the Steam branch of the gamePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/change-game-branch
changeGameBranch
Warns players for warningMinutes (default 5), saves and stops the game, takes a backup, switches to the chosen branch and starts the game. It can be cancelled until the save starts. Later Update game runs and the version view use the new branch. A framework (Oxide, Carbon) is not reinstalled: the result says it needs reinstalling. A failure leaves the server stopped, with the stage and reason in the operation and the backup as the way back. Refused before the server stops with 422 on /branch: required, invalid, same_branch, password_required or not_listed. Returns the update operation with input.changeBranch set to true. Needs servers.software.manage and servers.lifecycle on a ready server.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ChangeGameBranchRequestBody
admission(AdmissionBody)branch(string): The Steam branch to move to, for example `staging` or `public`: letters, digits, `.`, `_` and `-`, starting with a letter or digit, at most 64 characters.warningMinutes(integer): Minutes of player warning, as for Update game; absent means the normal 5 minutes, 0 stops at once.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Check for a game updatePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/check-game-update
checkGameUpdate
Checks for a newer game version. fresh means the result is current. For requested, pending or waiting, check the versions again later. unavailable means the check could not run. Needs servers.software.manage.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 GameBuildCheckResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Inspect a server's game filesPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/inspect
inspectServerFiles
Checks the installed game files on the host against what the host recorded after the last completed install or repair. Writes nothing to the server's folder and does not stop the game. Worlds, configuration, framework data and the install records are not checked, and the comparison is with the host's own record, not with Valve's files. Returns the operation; its result states clean, anomaly_count, the count per kind in anomaly_counts (missing, changed, extra, kind_changed, owner, mode, unreadable) and the first anomalies in anomalies (the host lists at most 200; anomalies_truncated says when more exist). Needs servers.software.manage on a ready server.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ServerSoftwareRequestBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Repair a server's game filesPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/repair
repairServerFiles
Worlds, configuration and framework data under server/, oxide/ and carbon/ are left as they are, and the repair fails if they changed. It stops nothing: the host refuses it while the game runs (stage error game_running), so stop the server first. Returns the operation. Needs servers.software.manage on a ready server.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ServerSoftwareRequestBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Switch Oxide, Carbon or no framework on a rented serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/switch-rented-framework
switchRentedFramework
For a server with no RustSC host that is connected through its host's panel, and only where frameworkChoices on the rented software read lists the framework: sets the host's own startup choice (the framework and its folder in one change, read back) so the host installs it the next time the server starts. state is applies_at_restart (nothing was started or restarted; it happens when the member restarts the server), not_offered (this server has no route, nothing was sent), refused (the host said no) or not_confirmed (the read back did not show the change; sending again is safe). Needs servers.software.manage.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body SwitchRentedFrameworkRequestBody
framework(string, required): `oxide`, `carbon` or `none` (no framework).
Success: 200 RentedFrameworkSwitchResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Update the gamePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/update-game
updateGame
Warns players for warningMinutes (default 5), saves and stops the game, updates the installed branch and starts the game. It can be cancelled until the save starts. The new build is reported when the server is ready. A server with Oxide or Carbon is updated with it in the same restart. The optional game, framework and extensions choices (all three on by default for the game and framework) pick what is updated: framework false updates the game alone, game false updates only the framework, extensions true or false decides whether RustEdit and the RustSC plugin ride the restart (absent follows the saved automatic update ticks; needs game); nothing chosen is 422 on /game. Refused for a channel outside the enabled set (channel_not_enabled) and when the chosen channel differs from the installed branch (target_change). Returns the update operation. Needs servers.software.manage and servers.lifecycle on a ready server.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body UpdateGameRequestBody
admission(AdmissionBody)backup(boolean): True takes an ordinary backup after the server stops, before anything changes; false takes none.extensions(boolean): True also updates RustEdit and the RustSC plugin in the same restart when they are behind, false leaves them; absent follows the server's saved automatic update ticks.framework(boolean): False leaves Oxide or Carbon alone (only the game is updated).game(boolean): False leaves the game alone (only Oxide or Carbon is updated).warningMinutes(integer): Minutes of player warning before the server stops, from 0 to the longest warning (60); players see a countdown in chat.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Update Oxide or Carbon on a rented serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/update-rented-framework
updateRentedFramework
For a server with no RustSC host that is connected through its host, and only where the host has a route for it (frameworkUpdatable on the rented software read): asks the host to fetch the newest release of the installed framework the next time the server starts. state is applies_at_restart (nothing was started or restarted; the update happens when the member restarts the server), not_offered (this server has no route, nothing was sent), refused (the host said no) or not_confirmed (the host may or may not have taken it; sending again is safe). Needs servers.software.manage.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RentedFrameworkUpdateResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read the start settings saved for a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/launch-inputs
getLaunchInputs
The save folder name, game port, query port and console port a member saved for a server that another tool runs. They are pending: the host uses them when RustSC starts the server and changes nothing before. A setting with no saved value is null. delivery is the operation that gave the saved settings to the host. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 LaunchInputsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save the start settings of a serverPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/launch-inputs
saveLaunchInputs
Saves the supplied settings for the server's next start. Use clear to remove saved values by name. Give distinct game and query ports from 1024 to 65535. saveFolderName accepts 1 to 64 letters, digits, underscores or hyphens and cannot start with a hyphen. If the host is offline, retry after it reconnects. Needs servers.config.write.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body LaunchInputsBody
clear(list of string): The settings whose saved value is removed, by name: `saveFolderName`, `gamePort`, `queryPort`, `consolePort`.consolePort(string): The console port (TCP, this host only): a whole number 1024 to 65535.gamePort(string): The game port (UDP): a whole number 1024 to 65535, different from the query port.queryPort(string): The server query port (UDP): a whole number 1024 to 65535, different from the game port.saveFolderName(string): The folder under `server/` that holds the world and the player data: 1 to 64 letters, digits, `_` or `-`, not starting with `-`.
Success: 200 LaunchInputsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read the game and framework versions of a rented serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/rented-software
getRentedSoftware
Reads the game and framework versions for a connected rented server. A recent answer may be given again; readAt says when it was read, and refresh=true reads it now. connected is false for a server without such a connection. A value that could not be read is absent. frameworkComparison is current, update_available or unknown. reason is empty when the files were read, framework_missing when neither framework is installed (frameworkSwitch then names the host's startup setting that turns one on, for example OXIDE) or the file route's reason. The host updates the game on a rented server. rustEdit says whether RustEdit is on the server, its build and the newest listed build (absent when the files could not say); its installable is true only when RustEdit can be installed or updated there (changeExtension). frameworkUpdatable is true only when a newer framework release is listed and the host can update it (updateRentedFramework). Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- refresh (query)
- See the downloadable contract for the field schema.
Success: 200 RentedSoftwareResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Remove a server's RustEdit map keyDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/rustedit-key
removeRustEditMapKey
Removes the map key for the server's next start. Needs servers.software.manage.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RustEditMapKeyResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read whether a server has a RustEdit map keyGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/rustedit-key
getRustEditMapKey
Whether a map key is stored for the server and when it was set. The key itself is never returned by any call. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RustEditMapKeyResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Set a server's RustEdit 2 map keyPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/rustedit-key
setRustEditMapKey
Sets the map key for the server's next start. The key is never returned. Send 1 to 256 characters without quote marks (422 on /key: invalid). Needs servers.software.manage.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body RustEditMapKeyBody
key(string, required): The key the map was exported with: 1 to 256 characters, no quote marks.
Success: 200 RustEditMapKeyResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read a server's automatic update settingsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/update-preferences
getUpdatePreferences
Two switches, both off until a member turns them on. onRestart: a restart applies a pending game update in the same stop and start. onDetection: a check that finds a newer build starts Update game with the normal player warning. items: the things (rustedit, rustsc_plugin) ticked for Update automatically at server restarts, empty until a member ticks one. delivery is the operation that gave the saved settings to the host. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 UpdatePreferencesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a server's automatic update settingsPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/update-preferences
saveUpdatePreferences
Saves both automatic update settings. Use onRestart to include a pending game update in a restart or onDetection to start an update when one is available. Use items to choose supporting extensions that update at restart. waitMinutes applies to onDetection and accepts 0, 60, 120, 180 or 360. Omit items or waitMinutes to keep that choice. If the host is offline, try after it reconnects. Needs servers.software.manage and servers.lifecycle.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body UpdatePreferencesBody
items(list of string): The things RustSC keeps up to date at server restarts, ticked one by one: `rustedit` and `rustsc_plugin` (a future one is one more id).onDetection(boolean): Restart when an update is found: a check that finds a newer build starts Update game with the normal player warning.onRestart(boolean): Update on restart: a restart applies a pending game update in the same stop and start.waitMinutes(integer): How long after an update appears RustSC waits before restarting for it, in whole minutes: 60, 120, 180, 360, or 0 for no wait.
Success: 200 UpdatePreferencesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List a server's installed and latest versionsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/versions
listServerVersions
Shows installed and available versions for the game, framework and extensions. Check currentUntil before relying on the game comparison. An unavailable comparison is unknown. For extensions, requires names the framework needed to use the extension. updatesEnabled says whether updates act on the channel: only production builds (Rust public, Oxide public, Carbon production) are enabled. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ServerVersionsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Workspace bans
Read where the global ban list stands on each serverGET /api/v1/workspaces/{workspaceId}/global-ban-list
getGlobalBanList
The global ban list is one list for the workspace that every host keeps a copy of and answers the game's join check from. version is the cloud's version, 0 when the workspace never had a global ban. Needs players.read for the whole workspace.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 GlobalBanListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Check the global ban list againPOST /api/v1/workspaces/{workspaceId}/global-ban-list/check
checkGlobalBanList
Asks every connected host which version of the global ban list it holds; the answers update getGlobalBanList in a moment. Changes nothing on any server and is safe to press again (a repeat inside ten seconds is the same request). asked is how many hosts were asked. Needs players.moderate for the whole workspace.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 GlobalBanListCheckResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the workspace bansGET /api/v1/workspaces/{workspaceId}/player-bans
listWorkspaceBans
The bans made on all servers that are in force, newest first, 50 to a page (cursor for the next). search is a Steam ID typed exactly or text inside the name (case ignored). Each ban says on how many of the workspace's servers the game holds it now (counts only: appliedOnServers of serverCount); servers added later and servers that were offline receive it from the workspace's own pass. canManage says whether the caller may add and lift. Needs players.read for the whole workspace.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- search (query)
- See the downloadable contract for the field schema.
- cursor (query)
- See the downloadable contract for the field schema.
Success: 200 WorkspaceBansResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Ban a player on all servers, now and laterPOST /api/v1/workspaces/{workspaceId}/player-bans
addWorkspaceBan
A global ban reaches every server of the workspace, those added later too (owner decision, 1 November 2026): servers whose host is offline, that are still installing, or that are added later receive the ban when they are connected and ready. A ban made on one server with banPlayer never enters this list. Adding a Steam ID already on the list refreshes its details and sends it again to servers that do not hold it. Without expiresInSeconds the ban never ends; with it (60 to 31536000) the end time is absolute, so a server added later gets only the time that remains. A server whose host holds the global ban list and has said how it reaches that server (getGlobalBanList) is not written to: its host refuses the player at the door and removes them after joining. At most 20000 bans are in force; one more is 422 too_many_workspace_bans on /steamId. Needs players.moderate for the whole workspace.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body WorkspaceBanBody
expiresInSeconds(integer): How long the ban lasts from now, 60 to 31536000 seconds; leave it out for a ban that never ends.name(string): The name stored with the ban when the player is not connected; optional.reason(string): The reason the game keeps and shows; optional.steamId(string): The player's 17 digit Steam ID, as a string.
Success: 200 WorkspaceBanChangeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Unban a player on all serversDELETE /api/v1/workspaces/{workspaceId}/player-bans/{steamId}
removeWorkspaceBan
The ban leaves the list once no server still has to be told. The unban also reaches a ban of the same player made on a server outside RustSC (the game's console, an import, before RustSC), except on a server whose host holds the global ban list (getGlobalBanList): there it reaches only a ban RustSC wrote into the game's own list earlier. Only a server that bans the player on its own through RustSC (banPlayer) keeps the game's ban, and it is named in keptOnServers. A Steam ID that is not on the list is 404. A single-server unban (unbanPlayer) of a player the workspace bans is 409 workspace_ban: use this route, because the workspace ban wins until it is removed. Needs players.moderate for the whole workspace.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- steamId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WorkspaceBanChangeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read where a hosting panel server's global bans standGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-global-bans
getPanelGlobalBans
For a server connected through its host's panel (available true): whether the workspace's global bans are applied to it (enabled), where that stands (state: off, current, applying, waiting_for_server, host_refused, host_busy or unreachable), how many lines are still to add or take out (remaining), the sentence to show (words) and when RustSC last looked (checkedAt). available is true only where the host's own control panel can send a ban to the server, or where the choice was already saved on. Any other server answers available false. Needs players.read.
Workspace permission: players.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelGlobalBansResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Apply the global bans to a hosting panel server, or stopPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/panel-global-bans
setPanelGlobalBans
Saves the choice for this server; nothing is sent inside the request. On, RustSC adds the workspace's global bans to the server's own ban list within a minute or two, marked as global, and keeps them in step with the list. Off, it takes out only the bans it added. A server that is not connected through its host's panel is 409 state_conflict (not_panel); turning it on where the host's panel cannot send a ban is 409 state_conflict (not_offered); enabled is required (422 at /enabled). Needs players.moderate for the whole workspace.
Workspace permission: players.moderate
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body PanelGlobalBansBody
enabled(boolean): True to apply the workspace's global bans to this server, false to take them off.
Success: 200 PanelGlobalBansResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Server adoption and removal
Browse folders on a hostPOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/actions/browse-folder
browseHostFolder
Lists the sub-folders of a folder on the host, for choosing where a server is installed. The result of the returned operation holds directory names only (never file names or contents), sorted, at most 200 with a count of the rest (more), the free bytes of the folder's volume, the bytes an install needs (required_bytes) and check: whether a server can be installed in the requested folder (allowed, reason, holds, and opens: the parent folders RustSC will be allowed to open so the server can run there, for a folder inside a home folder). Reasons: system_folder, home_folder, top_level, rustsc_folder, other_server, not_available, other_account, hidden_folder, parents_closed, drive_unsupported, not_a_folder, holds_server, not_empty, owned_by_other, name_not_allowed. A link is listed with the place it leads to. A folder that does not exist is answered with its nearest existing parent (exists false). Nothing is written. The operations list does not show it; each admission is audited. A host that is offline is refused (capability_unavailable, host_offline). Needs servers.create, or backups.manage on the server named in serverId (a server on this host, for choosing its backup folder).
Workspace permission: servers.create
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body BrowseFolderRequestBody
admission(AdmissionBody)path(string): The folder to list, an absolute path on the host, for example `/srv/rust`.serverId(string): The server on this host whose backup folder is being chosen (`srv_...`).showHidden(boolean): Ignored: hidden folders are never listed.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Create a folder on a hostPOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/actions/create-folder
createHostFolder
Creates one new, empty folder inside an existing folder on the host, through the same route that creates server folders, so the install that follows can use it. The name takes letters, digits, '.', '_' and '-' (up to 64 characters); a place a server cannot be installed is refused with the check's reason (stage error folder_refused:<reason>). Creating a folder that already exists and is empty answers the same. The result of the returned operation is the new folder's listing (created true when this request made it). Needs servers.create, or backups.manage on the server named in serverId (a server on this host, for choosing its backup folder).
Workspace permission: servers.create
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body CreateFolderRequestBody
admission(AdmissionBody)name(string): The new folder's name, up to 64 characters.parent(string): The existing folder to create it in, an absolute path on the host.serverId(string): The server on this host whose backup folder is being chosen (`srv_...`).
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Preview adopting a server folderPOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/actions/inspect-root
previewServerAdoption
Reads an existing Rust server folder on a full host and reports what adopting it would record: whether the server executable is there, the build and branch the game reports, the game file count, framework markers (oxide/, carbon/), each identity folder under server/ with its server.cfg imported (the RCON password line is refused, never read), and game processes outside this host's own runners that run from the folder (match cwd or exe) or that the host cannot attribute (match unverified). adoptable and blocking_reason say whether it can be adopted (not_a_server_root, root_in_use, supervised_elsewhere, process_check_unavailable). Nothing is registered and nothing in the folder is written. With serverId, the folder of that server in adopt_failed is checked again and is not refused as taken (adoptServerAgain). Returns the operation; its result is the report. Needs servers.create.
Workspace permission: servers.create
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body InspectRootRequestBody
admission(AdmissionBody)root(string): The existing server folder on the host, an absolute path, for example `/srv/rust/example-server`.serverId(string): A server in `adopt_failed` whose own folder is checked again ("Use what is there now"), for example `srv_01jb8z3k4q7v9w2x5y6z8a0b1c`: its folder is not refused as taken.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Remove a host from RustSCPOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/actions/remove
removeHost
Removes a host from RustSC, whether it is online, off or gone. Games stay running and files remain. Set servers to remove (default) to remove its server records, or keep to move or remove the servers later. On a connected host, set uninstall to also remove RustSC and follow the returned operation. A hosting company's host is removed the same way: its rented servers leave RustSC and their connections end as with disconnectPanelConnection, and nothing is sent to the hosting company; keep or uninstall is refused for it (state_conflict). Needs hosts.remove, which only an Owner holds.
Workspace permission: hosts.remove
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Request body RemoveHostRequestBody
servers(string): `remove` (the default: the servers leave RustSC too; their files, backups and history are kept) or `keep` (they stay listed as Host removed).stopServers(boolean): Ignored.uninstall(boolean): Also uninstall RustSC from the host first.
Success: 200 HostRemovalResponse, 202 HostRemovalResponse. Errors use Problem.
Response statuses: 200, 202, 401, 403, 404, 409, 422, default.
Restart a hostPOST /api/v1/workspaces/{workspaceId}/hosts/{hostId}/actions/restart
restartHost
Restarts the host's operating system now: players on every server of the host are warned for warningMinutes (0 to 60, default 5), every server is saved and stopped, the host restarts, and the servers that should run start again after the restart. Cancel it with the operation's cancel until the servers start stopping. It is refused (operation_conflict) or waits while other work runs on the host's servers. A restricted host cannot be restarted (capability_unavailable, restricted_host). Needs hosts.reboot, which only an Owner holds.
Workspace permission: hosts.reboot
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RestartHostRequestBody
admission(AdmissionBody)warningMinutes(integer): Minutes of player warning before the servers stop, 0 to 60; absent means the default of 5.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Remove an installationPOST /api/v1/workspaces/{workspaceId}/installations/{installationId}/remove
removeInstallation
Removes the installation: its key is refused from now on and its live connection closes, and every server it routes becomes detached. Nothing is sent to the host: its games keep running under local control and no file changes. Refused with operation_conflict while an operation on the host or one of its servers is waiting or running. Removing it again changes nothing. Needs hosts.manage.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- installationId (path, required)
- See the downloadable contract for the field schema.
Success: 200 InstallationRemovalResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Adopt a server folderPOST /api/v1/workspaces/{workspaceId}/servers/adopt
adoptServer
Use a successful preview for the same host and folder. Send the selected identity, ports and existing world settings. If the server settings changed after preview, use adoptServerAgain. The operation targets the new server and reports ready or adopt_failed. Existing game files stay as they are. Needs servers.create.
Workspace permission: servers.create
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body AdoptServerRequestBody
acknowledgeUnverifiedProcesses(boolean): Ignored; accepted so older clients keep working.admission(AdmissionBody)crashRecovery(boolean): The form's pre-ticked "Restart it if it crashes" switch.hostId(string): The full host the folder is on, the host of the preview.identity(string): The Rust identity folder under `server/` whose `server.cfg` is imported.importSettings(boolean): The form's pre-ticked "Import the server's existing settings and configs as they are" choice.name(string): Display name, a label for lists and operation summaries.nameFromGame(boolean): True when `name` is the name the game itself carries (the form's starting name, which the member did not change).playerLink(boolean): The form's pre-ticked "Let players link in the game" switch.ports(ServerPortsBody)previewOperationId(string): The operation ID from the adoption preview you reviewed.rustscPlugin(boolean): The form's pre-ticked "Install the RustSC plugin" option.seed(integer): The seed the existing world was made with, with the same rules as `worldSize`.worldSize(integer): The world size in metres the existing world was made with.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Adopt a server again with what is there nowPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/adopt-again
adoptServerAgain
Retries an adoption refused with preview_changed. Run previewServerAdoption for the same server and folder. Send the successful preview and the last failed adoption's operation ID. The values you entered previously are reused. If it reports preview_stale, make a new preview. Needs servers.create.
Workspace permission: servers.create
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body AdoptAgainRequestBody
admission(AdmissionBody)adoptionOperationId(string): The most recent failed adoption operation, with reason `preview_changed`.previewOperationId(string): The successful preview for the same server and folder, requested after the adoption failed.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Remove a serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/remove
removeServer
Stops managing the server and keeps its files and history. Stop a running server first or set stopFirst to stop it as part of removal (also needs servers.lifecycle). A connected server returns an operation. A detached server returns the removed server. A rented server is removed at once and its hosting company connection ends as with disconnectPanelConnection; nothing is sent to the hosting company. Needs servers.delete.
Workspace permission: servers.delete
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RemoveServerRequestBody
admission(AdmissionBody)stopFirst(boolean): Stop the game gracefully first (needs `servers.lifecycle`).
Success: 200 RemovedServerResponse, 202 OperationResponse. Errors use Problem.
Response statuses: 200, 202, 400, 401, 403, 404, 409, 422, default.
Server capabilities
List what you can ask of a host nowGET /api/v1/workspaces/{workspaceId}/hosts/{hostId}/available-actions
listHostAvailableActions
The same authority and routing checks made when host work is admitted. Needs hosts.read; work checks again on submission.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Success: 200 AvailableActionsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List what you can ask of a server nowGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/available-actions
listAvailableActions
allowed is true only when every check passes. A server you cannot read is 404. It is a hint: the request itself is evaluated again. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 AvailableActionsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Integrations
List the workspace's integrationsGET /api/v1/workspaces/{workspaceId}/integrations
listIntegrations
The state of the workspace's accounts and keys: the Steam key, the Codefling account, Discord, alert channels and webhooks, each with a status code, whether it works from RustSC or from a host, and a count or name the words use. Reads stored state only and never asks an outside service. hasHosts is false while the workspace has no host. Needs integrations.read.
Workspace permission: integrations.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 IntegrationListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List the hosts that hold an integration's keyGET /api/v1/workspaces/{workspaceId}/integrations/{integration}/hosts
listIntegrationHosts
Lists hosts with key status has_key, waiting or refused for steam, codefling or rusthq. An empty result means no host has the key. Needs integrations.read.
Workspace permission: integrations.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- integration (path, required)
- See the downloadable contract for the field schema.
Success: 200 IntegrationHostsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Remove an integration's key from one hostDELETE /api/v1/workspaces/{workspaceId}/integrations/{integration}/hosts/{hostId}
removeIntegrationKeyFromHost
Orders one host to forget the key of one integration (steam, codefling or rusthq) at once; an offline host is told when it returns. The workspace's saved key and every other host are untouched, and nothing sends the key back to that host until a member installs from the integration on a server there. hostId is the host's ID from listIntegrationHosts. 204 when the order was given; 404 when the host does not hold that key. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- integration (path, required)
- See the downloadable contract for the field schema.
- hostId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Send a test with the workspace's Steam keyPOST /api/v1/workspaces/{workspaceId}/steam-key/test
testSteamKey
Checks whether the saved Steam key works. A result can be works, refused, no_answer, asked or no_host. For asked, read listIntegrations later for the result. If no_key is returned, save a key before checking again. Needs integrations.manage.
Workspace permission: integrations.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 SteamTestResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Maps
Check a custom map linkPOST /api/v1/workspaces/{workspaceId}/maps/actions/check-link
checkMapLink
Looks at the address of a custom map from RustSC and reports what is there: whether a file is served, its size in bytes, and whether the address does not end in .map. The game downloads the map from this address and every joining player's game downloads it again, so it must be public. Only public web addresses are fetched; the map is not downloaded or stored (the first bytes are read). Answers 200 with a result such as unreachable or not_a_file rather than an error. At most 30 looks a minute for one workspace (429). Needs servers.create or worlds.reset (on any server); a member with neither gets 403 and no check, and saving a map never depends on it.
Workspace permission: servers.create or worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body CheckMapLinkRequestBody
url(string): The address of the map file, `http` or `https`.
Success: 200 CheckMapLinkResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, 429, default.
Draw a random map to previewPOST /api/v1/workspaces/{workspaceId}/maps/actions/shuffle
shuffleMap
Draws a random generated map of the size that the map service already has (never one that must first be made) and returns its preview. Seeds in exclude are not drawn again. state none means the service has no map at that size to offer; unavailable means previews cannot be shown right now, and the member can still choose a seed without one. Needs workspace membership.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body ShuffleMapRequestBody
exclude(list of integer): Seeds not to draw again, for example the ones already shown.size(integer): The size in metres, 1000 to 6000.
Success: 200 MapPreviewResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read the newest batch of candidate mapsGET /api/v1/workspaces/{workspaceId}/maps/candidates
getLatestMapCandidates
The workspace's newest batch of candidate maps (kept for a week), or none, so a member who closed the page finds the maps again. Needs workspace membership.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 LatestCandidatesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Find candidate mapsPOST /api/v1/workspaces/{workspaceId}/maps/candidates
createMapCandidates
Find 1 to 20 candidate maps of the requested size. Candidate maps can be used with the returned seed and size even while details are pending. Use resume to finish looking up pending candidates. Needs workspace membership.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body CreateCandidatesRequestBody
count(integer): How many different maps to find, 1 to 20.exclude(list of integer): Seeds not to find again, for example the maps already in the rotation.worldSize(integer): The world size of the candidates in metres, 1000 to 6000.
Success: 200 CandidateBatchResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Remove a batch of candidate mapsDELETE /api/v1/workspaces/{workspaceId}/maps/candidates/{batchId}
discardMapCandidates
Removes the batch and its candidates. Maps already added to a rotation are not affected. Needs workspace membership.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- batchId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Read a batch of candidate mapsGET /api/v1/workspaces/{workspaceId}/maps/candidates/{batchId}
getMapCandidates
A batch of candidate maps with the outcome of each. Needs workspace membership.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- batchId (path, required)
- See the downloadable contract for the field schema.
Success: 200 CandidateBatchResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Look up the pending candidate maps againPOST /api/v1/workspaces/{workspaceId}/maps/candidates/{batchId}/actions/resume
resumeMapCandidates
Asks the map service again about the candidates that are still pending, and only those: a ready candidate is never asked about or replaced, and no new seed is drawn. Returns the batch as it is after the request, at most about twenty seconds later. Needs workspace membership.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- batchId (path, required)
- See the downloadable contract for the field schema.
Success: 200 CandidateBatchResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read the map choicesGET /api/v1/workspaces/{workspaceId}/maps/choices
getMapChoices
The maps the game bundles that RustSC offers, the size range of a generated map and the size Add server starts with, the longest custom map address, and whether map previews are set up and who they come from. Needs workspace membership.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 MapChoicesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Preview a generated mapGET /api/v1/workspaces/{workspaceId}/maps/previews/{size}/{seed}
getMapPreview
What the map service shows for a generated map of this size and seed: a picture and facts such as the share of land and biomes. state is none when the service has no map for that seed yet and unavailable when previews cannot be shown right now; both are normal answers (200), and choosing the map never depends on a preview. fetchedAt says how old the facts are. Needs workspace membership.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- size (path, required)
- See the downloadable contract for the field schema.
- seed (path, required)
- See the downloadable contract for the field schema.
Success: 200 MapPreviewResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read a map preview pictureGET /api/v1/workspaces/{workspaceId}/maps/previews/{size}/{seed}/image
getMapPreviewImage
The picture of a previewed map, served by RustSC from the map service's copy: variant thumbnail (default) or full. 404 when the map or its picture is not available. Needs workspace membership.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- size (path, required)
- See the downloadable contract for the field schema.
- seed (path, required)
- See the downloadable contract for the field schema.
- variant (query)
- See the downloadable contract for the field schema.
Success: 200. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Nexus networks
List the saved Nexus networksGET /api/v1/workspaces/{workspaceId}/nexus-networks
listNexusNetworks
The Nexus networks saved for the workspace, by name A to Z, each with the four values and how many servers use it (usedBy), and the limits a save is checked against. Needs servers.setup.read. The Nexus key is returned as [redacted] unless the caller holds servers.config.write for the whole workspace.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 NexusNetworksResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a Nexus networkPOST /api/v1/workspaces/{workspaceId}/nexus-networks
createNexusNetwork
Saves a network: a name (required, unique in the workspace ignoring case) and the Nexus key (required), with an optional address and island distance and hide full islands. Refused with 422 at the field when it is empty (empty_not_allowed), too long (too_long), a name already used (name_taken), not an http or https address (invalid_url), not a number (kind_mismatch), or when the workspace already holds the most networks (network_limit). Needs servers.config.write for the whole workspace.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body NexusNetworkBody
endpoint(string): The address of the Nexus service (`nexus.endpoint`), an `http` or `https` address.hideFullIslands(boolean): Hide islands that are known to be full (`nexus.hidefullislands`).islandSpawnDistance(string): How far away islands spawn, as a factor of the map size (`nexus.islandspawndistance`), as decimal text such as `1.5`.key(string): The shared secret key of the Nexus (`nexus.secretkey`); every server of one Nexus uses the same key.name(string): What the member calls the network, for example `Main cluster`.
Success: 201 NexusNetworkResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Delete a Nexus networkDELETE /api/v1/workspaces/{workspaceId}/nexus-networks/{networkId}
deleteNexusNetwork
Deletes a network. Refused with 409 state_conflict and reason network_in_use while a server uses it; nothing is changed. Needs servers.config.write for the whole workspace.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- networkId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Change a Nexus networkPUT /api/v1/workspaces/{workspaceId}/nexus-networks/{networkId}
updateNexusNetwork
Replaces the network's name and values, with the same checks as saving one. Every server that uses it gets one new saved configuration revision with the new values; nothing is applied or restarted, so each server picks the change up when its configuration is applied, as for any saved change. Needs servers.config.write for the whole workspace.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- networkId (path, required)
- See the downloadable contract for the field schema.
Request body NexusNetworkBody
endpoint(string): The address of the Nexus service (`nexus.endpoint`), an `http` or `https` address.hideFullIslands(boolean): Hide islands that are known to be full (`nexus.hidefullislands`).islandSpawnDistance(string): How far away islands spawn, as a factor of the map size (`nexus.islandspawndistance`), as decimal text such as `1.5`.key(string): The shared secret key of the Nexus (`nexus.secretkey`); every server of one Nexus uses the same key.name(string): What the member calls the network, for example `Main cluster`.
Success: 200 NexusNetworkResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Operations
Find an earlier submissionGET /api/v1/workspaces/{workspaceId}/operation-submissions
findOperationSubmission
Read the operation admitted under your original workspace, principal, method, path and Idempotency-Key. Never starts or repeats work. Needs current permission to read the operation target. A 404 leaves the outcome unconfirmed: the request may not have arrived, may still be committing, or its record may have expired. Do not automatically repeat the original work request.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- key (query, required)
- Original Idempotency-Key. Query encoding preserves every allowed visible ASCII character.
- method (query, required)
- Original uppercase HTTP method: POST, PUT, PATCH or DELETE.
- path (query, required)
- Original full API path in this workspace, without query or fragment. Never include command text or request bodies.
Success: 200 OperationResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
List operationsGET /api/v1/workspaces/{workspaceId}/operations
listOperations
Operations newest first: of one server or host (targetId, which needs the target's read permission), or of every target you may read when targetId is left out. Optionally only some kinds or states (repeat kind or state). Work a screen started by itself (quiet) is left out whatever its end; asking for its kind by name lists it.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- targetId (query)
- The server or host, for example srv_01jb8z3k4q7v9w2x5y6z8a0b1c. Leave it out for every target you may read.
- parentId (query)
- Only validated children of this operation. Needs permission to read both the parent and each returned target.
- kind (query)
- Only these kinds, for example server.restart; repeat the parameter for several kinds.
- state (query)
- Only these states: `queued`, running, succeeded, failed, cancelled or outcome_unknown; repeat the parameter for several states.
- assistantId (query)
- Only what this AI assistant started: the ID of one of its connections or agent keys.
- limit (query)
- Page size.
- cursor (query)
- The nextCursor of the previous page, with the same filters.
Success: 200 OperationListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Read an operationGET /api/v1/workspaces/{workspaceId}/operations/{operationId}
getOperation
The operation's current record, also after any disconnect. With If-None-Match it answers 304 while the revision is unchanged; Prefer: wait=<seconds> holds the answer until the record changes or is final, up to the wait the response names in Preference-Applied. Needs the read permission of its target.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- operationId (path, required)
- See the downloadable contract for the field schema.
- If-None-Match (header)
- The ETag you hold, for example "r3".
- Prefer (header)
- wait=<seconds>: wait for a change,.
Success: 200 OperationResponse. Errors use Problem.
Response statuses: 200, 304, 401, 403, 404, default.
Stop waiting for an unconfirmed operationPOST /api/v1/workspaces/{workspaceId}/operations/{operationId}/actions/stop-waiting
stopWaitingForOperation
Ends the wait for an operation whose outcome RustSC could not confirm (state outcome_unknown, nothing resolved yet): it is settled as not confirmed, the server's locks are released and a waiting task is granted. Nothing is repeated, cancelled or retried, and no success or failure is claimed; a report that arrives later is kept as later evidence and never changes the state. Repeating it returns the same record. Any other state, including one the host already answered, is 409 state_conflict with reason not_unresolved; a bulk parent is 422 resolve_children. Needs the permission that admitted the operation, as cancel does.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- operationId (path, required)
- See the downloadable contract for the field schema.
Success: 200 OperationResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read a protective backup relationshipGET /api/v1/workspaces/{workspaceId}/operations/{operationId}/backup-association
getBackupAssociation
Pending until exact host parent and policy evidence arrives; linked once validated; rejected with a reason when its authority conflicts. Claimed parent IDs do not become relationships before validation. Needs the operation target's read permission.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- operationId (path, required)
- See the downloadable contract for the field schema.
Success: 200 BackupAssociationResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Cancel an operationPOST /api/v1/workspaces/{workspaceId}/operations/{operationId}/cancel
cancelOperation
Asks the operation to stop at its next safe boundary. Repeating it returns the same record. Work already done stays done; a final operation is 409 state_conflict (terminal). Needs the permission that admitted it.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- operationId (path, required)
- See the downloadable contract for the field schema.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 401, 403, 404, 409, 422, default.
Read a command resultGET /api/v1/workspaces/{workspaceId}/operations/{operationId}/command-result
getCommandResult
Reads exact retained redacted reply text from the host. Needs servers.read for the operation and servers.console.read for text. Delivery is confirmed only by the actual RCON send stage. No command is sent or retried.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- operationId (path, required)
- See the downloadable contract for the field schema.
Success: 200 CommandResultResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Rented servers
List the hosts a rented server can be connected through, and the connected serversGET /api/v1/workspaces/{workspaceId}/panel-hosts
listPanelHosts
The host list in the order RustSC supports them (hosts with no connection option have canConnect false), the workspace's connected rented servers and whether the caller may change them. No key or part of a key is ever returned. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelHostsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Connect a rented serverPOST /api/v1/workspaces/{workspaceId}/panel-hosts
connectPanelHost
Checks the key and, when something works, stores it write-only and saves the connection; when nothing works nothing is saved and connection is null. Connecting the same server on the same host again replaces its key and name. The same form's queryAddress and queryPort are saved with the connection in the same step (422 at /queryAddress with not_ipv4 or not_public, at /queryPort with bad_port; both empty leave a saved address as it is). consoleFromHost reads the console password the host's startup values show and keeps it with the connection like a typed one; it is never returned, and a consoleAddress that is not the host's own needs servers.secrets.write. connectionId names the saved connection to change in place: its server id or panel address, key, name and console are replaced (404 when it is not one of this host's connections, 422 at /serverPage with panel_server_taken when another connection holds that server). Same field problems as the check, and a name already used (panel_name_taken). Shares the check's limit (429 rate_limited). Needs hosts.manage.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body PanelHostBody
connectionId(string): Connect only: the saved connection (`pcn_...`) this Connect changes, so its server id, key, name and console are replaced in place.consoleAddress(string): The game's own console address, `host` or `host:port` (port 28016 when none).consoleFromHost(boolean): Connect only: true to use the console password the host's own startup values show.consolePassword(string): The game's console password that goes with `consoleAddress`.fileLoginAddress(string): An optional file login beside the host's key, for files the host cannot handle itself: its address, `host`, `host:port` or with `sftp://`, `ftps://` or `ftp://`.fileLoginPassword(string): The file login's password.fileLoginPort(integer): The file login's port when the address names none (22 for SFTP, 21 for FTP).fileLoginProtocol(string): A scheme in the address wins.fileLoginUser(string): The file login's user name.hostId(string): The host the member picked, one of the `id` values of the host list.keepHistory(boolean): Connect only: true to start keeping the server's performance history with a new connection (the Connect form's pre-ticked box).key(string): The panel key made for this one server, or the file login's password for a host of kind `file_login`.name(string): What the member calls the server.queryAddress(string): Connect only: the server's public IPv4 address for its status, saved with the connection.queryPort(integer): Connect only: the game's query port, 1024 to 65535.serverPage(string): The address of the server's page in the panel, for example `https://panel.example.com/server/1a7ce997`: it holds both the panel address and the server.user(string): For a host of kind `file_login`: the file login's user name, as the host's page shows it.
Success: 200 PanelConnectResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, 429, default.
Check what a key allows on a hostPOST /api/v1/workspaces/{workspaceId}/panel-hosts/check
checkPanelHost
Asks the host what the pasted key allows and says it in words, without saving anything. Refused with 422 at the field when the input is not usable: hostId unknown or a host with no connection (panel_host_no_connection), serverPage empty or not a secure panel address, key empty or an administrator key (admin_key); for a host of kind file_login, serverPage not a file login address (not_a_file_address; it may start with sftp://, ftps:// or ftp://, and SFTP is the one used when it names none), a port that is not the type's own or 1024 and above (file_port_not_allowed) and user empty; the optional game console (consoleAddress and consolePassword, both or neither) is refused at its field when the address is not a host with an optional port (not_a_console_address) or the port is below 1024 (console_port_not_allowed); it can be given for any host and only the workspace Owner may give it. A line that the server's own console delivers says so in route. For the Owner, a host that cannot send console commands itself and shows where the console is returns consoleFill with those values. When something works, setup fills the rest of the form where the host's own API says: queryAddress and queryPort, and, where a route reaches the game's console, console true with consoleAddress and consolePasswordFromHost (the password itself is never returned). Check, connect and recheck share a limit per workspace: over it the answer is 429 rate_limited with retryAfterSeconds and nothing is sent to the host. Needs hosts.manage.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body PanelHostBody
connectionId(string): Connect only: the saved connection (`pcn_...`) this Connect changes, so its server id, key, name and console are replaced in place.consoleAddress(string): The game's own console address, `host` or `host:port` (port 28016 when none).consoleFromHost(boolean): Connect only: true to use the console password the host's own startup values show.consolePassword(string): The game's console password that goes with `consoleAddress`.fileLoginAddress(string): An optional file login beside the host's key, for files the host cannot handle itself: its address, `host`, `host:port` or with `sftp://`, `ftps://` or `ftp://`.fileLoginPassword(string): The file login's password.fileLoginPort(integer): The file login's port when the address names none (22 for SFTP, 21 for FTP).fileLoginProtocol(string): A scheme in the address wins.fileLoginUser(string): The file login's user name.hostId(string): The host the member picked, one of the `id` values of the host list.keepHistory(boolean): Connect only: true to start keeping the server's performance history with a new connection (the Connect form's pre-ticked box).key(string): The panel key made for this one server, or the file login's password for a host of kind `file_login`.name(string): What the member calls the server.queryAddress(string): Connect only: the server's public IPv4 address for its status, saved with the connection.queryPort(integer): Connect only: the game's query port, 1024 to 65535.serverPage(string): The address of the server's page in the panel, for example `https://panel.example.com/server/1a7ce997`: it holds both the panel address and the server.user(string): For a host of kind `file_login`: the file login's user name, as the host's page shows it.
Success: 200 PanelCheckResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, 429, default.
Disconnect a rented serverDELETE /api/v1/workspaces/{workspaceId}/panel-hosts/{connectionId}
disconnectPanelConnection
Deletes the stored key and removes the connection, and the server leaves the Servers list. The member's server on the host is not touched. The host it was listed under stays in the Hosts list, with no servers, until it is removed with removeHost. Needs hosts.manage.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
List the latest actions of a connected rented serverGET /api/v1/workspaces/{workspaceId}/panel-hosts/{connectionId}/actions
listPanelActions
The newest actions through the panel, newest first, each with its state. A command's text is never returned. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelActionsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Ask a connected rented server to start, stop, restart, kill or run a commandPOST /api/v1/workspaces/{workspaceId}/panel-hosts/{connectionId}/actions
requestPanelAction
Requests one action for a rented server. The operation is accepted (`queued`) or refused. Use listPanelActions to follow it. kill ends the game at once without saving, where available (409 capability_unavailable elsewhere). Start the server again when ready. Needs hosts.manage, and on the connected server servers.console.execute for a command, servers.lifecycle.force for kill or servers.lifecycle for start, stop and restart.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Request body PanelActionBody
command(string): The console command, one line, for `command`.kind(string): `start`, `stop`, `restart`, `kill` (ends the game at once without saving, where the host offers it) or `command`.
Success: 200 PanelActionItemResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Check a connected rented server againPOST /api/v1/workspaces/{workspaceId}/panel-hosts/{connectionId}/check
recheckPanelConnection
Uses the stored key to ask the host again what it allows, and records the sentence it ends with. 409 state_conflict with reason secret_unavailable when the key cannot be read. Shares the check's limit (429 rate_limited). Needs hosts.manage.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelCheckResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, 429, default.
Read the game console saved with a connected rented serverGET /api/v1/workspaces/{workspaceId}/panel-hosts/{connectionId}/console
readPanelConsole
Where the game's console saved with the connection is (address, host:port) and whether a password is kept with it; the password is never returned. hostCanTell says the host's own API can give the console again. Nothing is sent to the host or the game. Needs hosts.manage because it opens the stored secret.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelSavedConsoleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change the game console saved with a connected rented serverPUT /api/v1/workspaces/{workspaceId}/panel-hosts/{connectionId}/console
setPanelConsole
Replaces the console kept with the connection; the key and any file login stay as they are. fromHost reads the console password (and, with no address, the address) from the host's own startup values again: 409 state_conflict with reason host_shows_no_console_password when the host shows none, and nothing changes. Otherwise password replaces the saved one, or, left empty with an address, the saved password is kept (422 at /password with no_console_password when none is saved). An empty address with no password removes the console. A typed password, or the saved one with a new address, needs servers.secrets.write (the workspace Owner); 403 otherwise. 422 at /address with not_a_console_address or console_port_not_allowed. Nothing is sent to the game; check the connection again to see whether the console answers. Needs hosts.manage.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Request body PanelSavedConsoleBody
address(string): The console's address, `host` or `host:port` (port 28016 when none).fromHost(boolean): True to read the console password (and, with no address, the address) from the host's own startup values again.password(string): A new console password.
Success: 200 PanelSavedConsoleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read the recent lines of a connected rented server's log fileGET /api/v1/workspaces/{workspaceId}/panel-hosts/{connectionId}/log
readPanelLog
Reads the newest lines of the game's log file through the host's files, on the member's request only: the first read (no file, offset 0) takes the end of the newest log, the next passes back file and nextOffset from the last answer and gets only what came after. Lines are complete, oldest first, with passwords and keys removed; a log that became a new file or shorter says restarted, and more arriving since the last offset than one answer holds says skipped. reason is empty when lines were read (there may be none), no_log when no log file was found, too_large when the host does not let RustSC read that log, not_reachable when the host did not answer. Nothing is kept. Needs hosts.manage because it uses the key.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
- file (query)
- See the downloadable contract for the field schema.
- offset (query)
- See the downloadable contract for the field schema.
Success: 200 PanelLogResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List the other servers of the same account at the hostGET /api/v1/workspaces/{workspaceId}/panel-hosts/{connectionId}/more-servers
listPanelMoreServers
Asks the host, once and with the stored key of this connection, which servers the key can see, and returns those the workspace has not connected yet with the host's own names. Nothing is saved and nothing at the host changes. offered is false on a host where this is not offered (choices with listsServers absent); nothing is sent then. When the read did not work, result says how in one sentence. Shares the check's limit (429 rate_limited). 409 state_conflict with reason secret_unavailable when the key cannot be read. Needs hosts.manage because it uses the key.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelMoreServersResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 429, default.
Connect more servers from the same accountPOST /api/v1/workspaces/{workspaceId}/panel-hosts/{connectionId}/more-servers
connectPanelMoreServers
Connects each chosen server (servers, their ids from listPanelMoreServers) with the stored key of this connection: the host's list is read again and each chosen server it shows that is not connected yet goes through the same check and Connect as connectPanelHost, saved with its own copy of the key. One item per chosen server, with its connection or, when it was not connected, null and the sentence why. 422 with not_a_server_list at /servers when the list is empty or too long; 409 capability_unavailable on a host where this is not offered. Shares the check's limit (429 rate_limited). Needs hosts.manage.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Request body PanelMoreServersBody
servers(list of string)
Success: 200 PanelMoreServersConnectResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, 429, default.
Remove the plugin key of a connected rented serverDELETE /api/v1/workspaces/{workspaceId}/panel-hosts/{connectionId}/plugin-key
removePanelPluginKey
Removes the key: the plugin can no longer reach RustSC with it. Removing a key that is not there is not an error. Needs hosts.manage.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
See whether a connected rented server has a plugin keyGET /api/v1/workspaces/{workspaceId}/panel-hosts/{connectionId}/plugin-key
getPanelPluginKey
Whether the server's companion plugin has a key, the start of it to recognise it by, when it was made, when it ends and when the plugin last used it. The key itself is never returned. Needs hosts.read.
Workspace permission: hosts.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelPluginKeyResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Make or replace the plugin key of a connected rented serverPOST /api/v1/workspaces/{workspaceId}/panel-hosts/{connectionId}/plugin-key
makePanelPluginKey
Makes a key for the server's companion plugin and returns it once in key; it is not stored and cannot be read again. Making a key again replaces the old one at once, which is how it is rotated. Nothing is changed on the host; the member pastes the key into the plugin. 409 state_conflict with reason no_server when the connection has no server yet. Needs hosts.manage.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelPluginKeyMadeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read a connected server's startup valuesGET /api/v1/workspaces/{workspaceId}/panel-hosts/{connectionId}/startup
readPanelStartup
Reads startup settings for a connected rented server. Check result before using values. A secret value is shown only to the workspace Owner. editable says whether the value can be changed. Needs hosts.manage.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PanelStartupResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change one startup value on the hostPUT /api/v1/workspaces/{workspaceId}/panel-hosts/{connectionId}/startup/{name}
setPanelStartupValue
Changes one startup setting from the next server start. Use the name from the settings list. result is accepted, refused, rejected or unknown. If it is unknown, read the current settings before trying again. Needs hosts.manage. Changes to secrets or console settings also require the workspace Owner.
Workspace permission: hosts.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- connectionId (path, required)
- See the downloadable contract for the field schema.
- name (path, required)
- See the downloadable contract for the field schema.
Request body PanelStartupBody
value(string)
Success: 200 PanelActionResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Reports
Read the report inboxGET /api/v1/workspaces/{workspaceId}/reports
listReports
One page of the F7 reports and feedback players sent, newest activity first. server narrows it to one server, status to one or more of open, investigating, resolved and dismissed, assignee to me or none, unread to unread (true) or read (false) reports and q to reports whose names, Steam IDs or text contain the words. limit is 1 to 100 (default 30) and before continues after a page (pass the next value of the previous page). Reports of servers the caller may not read are absent. openCount and unreadCount cover every readable server, whatever the filter. Needs reports.read on the server, or an active membership without server (the page then holds the servers the caller may read).
Workspace permission: reports.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- server (query)
- See the downloadable contract for the field schema.
- status (query)
- See the downloadable contract for the field schema.
- assignee (query)
- See the downloadable contract for the field schema.
- unread (query)
- See the downloadable contract for the field schema.
- q (query)
- See the downloadable contract for the field schema.
- before (query)
- See the downloadable contract for the field schema.
- limit (query)
- See the downloadable contract for the field schema.
Success: 200 ReportsPageResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Download the report inboxGET /api/v1/workspaces/{workspaceId}/reports/export
exportReports
The F7 reports the caller may read as one file: format json (the default; a summary, then each report with its history) or csv (one row per report). server, status (one or more) and q narrow it as they do the inbox. Only servers on which the caller holds both reports.read and evidence.export are included, and a server the caller may not export is left out and never counted. The file is written as the pages are read and nothing is kept on RustSC's side; once downloaded it is outside RustSC and cannot be recalled. Each export is audited (evidence.export) with the format and filters, never a report's text. Needs evidence.export and reports.read.
Workspace permission: evidence.export
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- server (query)
- See the downloadable contract for the field schema.
- format (query)
- See the downloadable contract for the field schema.
- status (query)
- See the downloadable contract for the field schema.
- q (query)
- See the downloadable contract for the field schema.
Success: 200. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Delete every report about a playerDELETE /api/v1/workspaces/{workspaceId}/reports/player/{steamId}
eraseReportsAboutPlayer
Deletes, for good, every report that names the Steam ID as the reporter or the accused, with its notes and history, on the servers where the caller may delete evidence; reports on other servers stay. Answers how many reports and history rows went (zero when there are none, so a repeat changes nothing). The audit trail counts them and names no player or text. The short-lived event record each report came from ages out on its own, and downloaded copies cannot be recalled. Needs evidence.delete on at least one server (Owner and Administrator).
Workspace permission: evidence.delete
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- steamId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ErasedReportsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Delete a reportDELETE /api/v1/workspaces/{workspaceId}/reports/{reportId}
deleteReport
Deletes the report with its notes and history for good; it is gone from every list at once. The kick or ban a report links to stays in the operation history and the audit trail, and a report's own status changes stay in the audit trail without the report's text. Answers 404 for a report that is already gone. Needs evidence.delete on the report's server (Owner and Administrator).
Workspace permission: evidence.delete
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- reportId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Read a reportGET /api/v1/workspaces/{workspaceId}/reports/{reportId}
getReport
The report with its history, oldest first, at its current revision (the ETag). Needs reports.read on the report's server.
Workspace permission: reports.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- reportId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ReportDetailResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change a reportPATCH /api/v1/workspaces/{workspaceId}/reports/{reportId}
changeReport
Changes the status, the assignment, the read state, adds a note or records a kick or ban the caller already asked for (moderation: the action and the operation kickPlayer or banPlayer returned, on the same server), in one request from the revision in If-Match. A stale revision answers 412 revision_conflict with the current revision and changes nothing. A part that changes nothing adds no history, so a repeated request is harmless. Nothing is sent to the game or to the player. Needs reports.manage on the report's server.
Workspace permission: reports.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- reportId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body ReportChangeBody
assignee(string): `me` assigns the report to the caller, `none` removes the assignment.moderation(ReportModerationBody)note(string): A note for the staff, up to 2000 characters.status(string): `open`, `investigating`, `resolved` or `dismissed`.unread(boolean): True marks the report unread, false marks it read.
Success: 200 ReportDetailResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Read the picture kept with a reportGET /api/v1/workspaces/{workspaceId}/reports/{reportId}/attachment
getReportAttachment
The picture of a report, as the bytes with their type, for a caller who may read the report (reports.read). 404 when the report has no picture and 410 when it had one and its 90 days have passed: an expired or missing picture is never shown as intact. The type comes from the bytes. The answer is private (no-store), carries no script permission (a strict content policy, nosniff and a download-safe disposition) and there is no public or shareable link to it.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- reportId (path, required)
- See the downloadable contract for the field schema.
Success: 200. Errors use Problem.
Response statuses: 200, 401, 403, 404, 410, default.
Read what the server recorded around a reportGET /api/v1/workspaces/{workspaceId}/reports/{reportId}/evidence
getReportEvidence
The events the report's own server recorded from five minutes before the report was sent to five minutes after it, oldest first (at most 50; more says that others fall in the window and Find events lists them), with the stretches of that time that were not recorded. It covers that one server only and the same fields a single read of its events would give: private chat needs evidence.read.private and report text is never here. A caller who may read the report but not the server's events gets readable false and nothing else; kept false says the events of that time are past the days evidence is kept. Reading starts nothing in the game and sends nothing. Needs reports.read, and evidence.read, on the report's server.
Workspace permission: reports.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- reportId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ReportEvidenceResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Rules
Read the rulesGET /api/v1/workspaces/{workspaceId}/rules
listRules
The rules the caller can read (a rule is visible to a caller who can read every server it names), newest first, each with what the caller may do with it and how its newest run ended. server narrows it to rules that listen on one server. Needs an active membership.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- server (query)
- See the downloadable contract for the field schema.
Success: 200 RuleListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a rulePOST /api/v1/workspaces/{workspaceId}/rules
createRule
Saves a rule at revision 1, switched off. The caller needs rules.manage and automation.manage on every server it names. A repeated request with the same Idempotency-Key replays the rule.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body RuleDefinitionWire
actions(list of RuleActionWire)conditions(list of RuleConditionWire)name(string)onActionFailure(string): `stop` or `continue`: whether the actions after a failed one still run.trigger(RuleTriggerWire)
Success: 201 RuleResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Delete a ruleDELETE /api/v1/workspaces/{workspaceId}/rules/{ruleId}
deleteRule
Switches the rule off and removes it from every list; it can no longer be changed or switched on. What it did stays in the history of the operations it admitted, and its run history is kept until run retention ages it. Answers 404 for a rule that is already gone. Needs rules.manage on every server the rule names (Owner and Administrator).
Workspace permission: rules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- ruleId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Read a ruleGET /api/v1/workspaces/{workspaceId}/rules/{ruleId}
getRule
The rule at its current revision (the ETag). Needs servers.read on every server it names.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- ruleId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RuleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change a rulePUT /api/v1/workspaces/{workspaceId}/rules/{ruleId}
changeRule
Saves the next revision from the revision in If-Match; a stale revision is 412 revision_conflict and changes nothing. The new revision is recorded as the caller's and earlier revisions never change. Whether the rule is on is kept. Needs rules.manage on every server it names and the same checks as saving.
Workspace permission: rules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- ruleId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body RuleDefinitionWire
actions(list of RuleActionWire)conditions(list of RuleConditionWire)name(string)onActionFailure(string): `stop` or `continue`: whether the actions after a failed one still run.trigger(RuleTriggerWire)
Success: 200 RuleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Switch a rule on or offPUT /api/v1/workspaces/{workspaceId}/rules/{ruleId}/enabled
setRuleEnabled
Switches the rule without changing it: no revision is written and the rule keeps its author. A rule is switched on only if its saved definition still passes the catalog (409 state_conflict, definition_unsupported). Repeating it changes nothing. Needs rules.enable on every server the rule names, which the Operator preset holds.
Workspace permission: rules.enable
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- ruleId (path, required)
- See the downloadable contract for the field schema.
Request body RuleEnabledBody
enabled(boolean)
Success: 200 RuleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read what a rule didGET /api/v1/workspaces/{workspaceId}/rules/{ruleId}/runs
listRuleRuns
The live events that matched the rule, newest first, each with the outcome of its actions: handed to the server's host, failed, skipped or held back by a bound (30 runs of a rule and 300 of a workspace in an hour). limit is 1 to 50 (default 20); before continues after a page. Needs servers.setup.read on every server the rule names.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- ruleId (path, required)
- See the downloadable contract for the field schema.
- before (query)
- See the downloadable contract for the field schema.
- limit (query)
- See the downloadable contract for the field schema.
Success: 200 RuleRunsPageResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Server groups
List the server groupsGET /api/v1/workspaces/{workspaceId}/server-groups
listServerGroups
The groups of the workspace by name, each with its revision and how many of its servers the caller can read. A group is only a way to choose servers: creating, renaming or changing one starts nothing on any server.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ServerGroupListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Create a server groupPOST /api/v1/workspaces/{workspaceId}/server-groups
createServerGroup
Creates a group with a name and optionally its first servers. Needs groups.manage.
Workspace permission: groups.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ServerGroupBody
name(string): What the member calls the group, for example `PvP servers`.serverIds(list of string): Servers to put in the group (`srv_...`).
Success: 201 ServerGroupResponse. Errors use Problem.
Response statuses: 201, 400, 401, 403, 404, 409, 422, default.
Delete a server groupDELETE /api/v1/workspaces/{workspaceId}/server-groups/{groupId}
deleteServerGroup
Deletes the group and its memberships; the servers are not changed. Needs groups.manage.
Workspace permission: groups.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- groupId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 412, 422, 428, default.
Rename a server groupPATCH /api/v1/workspaces/{workspaceId}/server-groups/{groupId}
renameServerGroup
Changes the group's name. Needs groups.manage.
Workspace permission: groups.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- groupId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body ServerGroupBody
name(string): What the member calls the group, for example `PvP servers`.serverIds(list of string): Servers to put in the group (`srv_...`).
Success: 200 ServerGroupResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Add servers to a groupPOST /api/v1/workspaces/{workspaceId}/server-groups/{groupId}/actions/add-servers
addServersToGroup
Adds servers; those already in the group stay. Needs groups.manage.
Workspace permission: groups.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- groupId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body ServerGroupMembersBody
serverIds(list of string)
Success: 200 ServerGroupResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Take servers out of a groupPOST /api/v1/workspaces/{workspaceId}/server-groups/{groupId}/actions/remove-servers
removeServersFromGroup
Takes servers out; those not in the group are ignored. The servers themselves are not changed. Needs groups.manage.
Workspace permission: groups.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- groupId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body ServerGroupMembersBody
serverIds(list of string)
Success: 200 ServerGroupResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Shell
Read the schedules, versions, latest backup and latest player count and frame rate of several serversGET /api/v1/workspaces/{workspaceId}/servers-summary
getServersSummary
For each serverId given (repeat the parameter, at most 100): the server's schedules, its versions and its newest backup, as their own routes answer them. Name measurements in include to also get the last stored player count and frame rate with the time each was seen; they are not read otherwise. A part the caller may not read, or that cannot be read, is null for that server.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (query)
- A server, for example srv_01jb8z3k4q7v9w2x5y6z8a0b1c; repeat the parameter for several servers.
- include (query)
- Which parts to read: schedules, versions, backups or measurements; repeat the parameter for several. Without it schedules, versions and backups are read. A part that was not asked for is null.
Success: 200 ServersSummaryResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read what a server's page opens withGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/summary
getServerSummary
The server, its newest lifecycle operations, install, inspection or repair and removal, its versions, its latest operations and its newest adoption in one request. Each part needs what its own route needs (servers.read).
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ServerSummaryResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read the counts the menu and top bar showGET /api/v1/workspaces/{workspaceId}/shell-counts
getShellCounts
Operations waiting or in progress, open alerts and reports still to work on, in one request. Each is what its own list would show the caller: operations of targets they may read, alerts of servers they may read and reports of servers they may read. A count the caller may not read is null with the status its own route would have answered.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ShellCountsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Server lifecycle
Read a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}
getServer
The server's name, host, administration state and whether its host is connected now. Whether the game runs is shown by its lifecycle operations. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ServerResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Restart a serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/restart
restartServer
Set warningMinutes to a whole number from 0 to 60 (default 5). The server warns players, saves and restarts. Cancel before the save starts. Set backupFirst to back up before restarting. If it fails, the server stays stopped. A graceful restart can apply changes in permissions (also needs players.permissions.manage). Set force to stop immediately without saving or warning (also needs servers.lifecycle.force). A rented server is restarted by its hosting company; it takes no warning, backup or permission changes, and no force. Needs servers.lifecycle.
Workspace permission: servers.lifecycle
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body StopServerRequestBody
admission(AdmissionBody)backupFirst(boolean): Restart only: true backs the server up on its host after the stop and before the launch; a failed backup leaves it stopped.force(boolean): True ends the game at once without saving (a forced stop or forced restart, permission `servers.lifecycle.force`).permissions(RestartPermissionsBody)warningMinutes(integer): How many whole minutes players are warned before the server saves and stops, from 0 to the longest warning (60).
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Save a serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/save
saveServer
Saves the running world. Follow the returned operation to confirm the save. Needs servers.save.
Workspace permission: servers.save
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body SaveServerRequestBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Start a serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/start
startServer
Starts a stopped server and reports when it is ready. A server already running stays running. Set backupFirst to back up before starting. If the backup fails, the server stays stopped. A rented server is started by its hosting company. Needs servers.lifecycle.
Workspace permission: servers.lifecycle
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body StartServerRequestBody
admission(AdmissionBody)backupFirst(boolean): True backs the stopped server up on its host right before the launch; a failed backup launches nothing.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Stop a serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/stop
stopServer
Set warningMinutes to a whole number from 0 to 60 (default 5). The server warns players, saves and stops. Cancel before the save starts. Set force to stop immediately without saving or warning (also needs servers.lifecycle.force). A rented server is stopped by its hosting company and takes no warning. Needs servers.lifecycle.
Workspace permission: servers.lifecycle
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body StopServerRequestBody
admission(AdmissionBody)backupFirst(boolean): Restart only: true backs the server up on its host after the stop and before the launch; a failed backup leaves it stopped.force(boolean): True ends the game at once without saving (a forced stop or forced restart, permission `servers.lifecycle.force`).permissions(RestartPermissionsBody)warningMinutes(integer): How many whole minutes players are warned before the server saves and stops, from 0 to the longest warning (60).
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read a server's helpersGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/helpers
getServerHelpers
The programs the host starts around this server's start, as the portal defined them. helpers is the list the host applied last; requested is the list of the newest save when the host has not applied it yet or refused it; delivery is that save's operation, whose error reason says why a list was refused (for example executable_missing, with the helper's id in the result). Helpers defined at the host itself are not listed. Needs servers.helpers.read, which only the Owner holds (a key of mode read made by the Owner holds it).
Workspace permission: servers.helpers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 HelpersResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a server's helpersPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/helpers
saveServerHelpers
Replaces the helper list from the server's next start. Up to five helpers may use a full program path, up to 64 separate arguments, an optional folder and a delay from 0 to 3600 seconds. Select startup or readiness and whether it is enabled. A helper stops with the server. A 422 response identifies the field to correct. If the host is offline, try when it reconnects. Needs servers.helpers.manage.
Workspace permission: servers.helpers.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body HelpersBody
helpers(list of HelperBody)
Success: 200 HelpersResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read automatic crash recovery statusGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/recovery-preferences
getServerRecoveryPreferences
The setting last reported by the current installation, separately from remote delivery. Unknown is not the enabled default. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 RecoveryPreferencesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change automatic recoveryPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/recovery-preferences
setServerRecoveryPreferences
Disabling crash recovery cancels pending automatic attempts without stopping a game. A launch already committed may still complete. Enabling preserves intentional stops, holds and maintenance and never starts a game itself. Needs servers.config.write, servers.lifecycle when enabled or startAtBoot is true, and servers.lifecycle.force when restartIfUnresponsive is true, at admission.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body SetRecoveryPreferencesBody
admission(AdmissionBody)enabled(boolean, required)expectedRevision(integer, required): The observed host setting revision, not an operation ETag or cloud counter.restartIfUnresponsive(boolean): Restart the server by force when it stays unresponsive for unresponsiveMinutes.saveRecovery(string): Save recovery: ask_first or automatic, what the host does when the game finds its save damaged.startAtBoot(boolean): Start the server again after the host restarts.unresponsiveMinutes(integer): Whole minutes, 5 to 120.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read the host's automatic recovery settingPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/recovery-preferences/refresh
refreshServerRecoveryPreferences
Observable read from the current installation, including revision zero (everything off, except a server from before the boot switch, which starts after the host restarts) for an unconfigured setting. Does not change the setting or desired run state. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RefreshRecoveryPreferencesBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read whether the next start is the start the game runs with nowGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/same-start
getServerSameStart
Asks the host that runs the server to compare the start RustSC would use at the next restart with the start of the game that runs now, and answers with the state and one plain line: same, different (the line says what would change), not_read, not_running or not_needed (RustSC started the game itself). A host that is not connected, is older or does not answer in a few seconds gives unavailable. It starts, stops and changes nothing, and the answer never stops a restart from being switched on. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 SameStartResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read a server's player warningsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/warning-messages
getServerWarningMessages
The message players read in game chat as a countdown before a restart, a stop, Update game, an Oxide or Carbon change and a map wipe. message is the member's text, or null for the built-in text (defaultMessage). delivery is the operation that gave the saved messages to the host. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WarningMessagesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a server's player warningsPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/warning-messages
saveServerWarningMessages
Saves five warning messages. Leave a message empty for the default or send one line up to 200 characters containing {remaining_time}, for example {remaining_time:words}. A 422 result identifies the field to correct. If the host is offline, try when it reconnects. Needs servers.lifecycle.
Workspace permission: servers.lifecycle
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body WarningMessagesBody
frameworkUpdate(string): Before an Oxide or Carbon change.gameUpdate(string): Before Update game.restart(string): Before a restart.stop(string): Before a stop.wipe(string): Before a map wipe.
Success: 200 WarningMessagesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Preview a player warningPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/warning-messages/preview
previewServerWarningMessage
The lines a countdown would say for one action and warning, in order, built by the same code as the host. Saves nothing and sends nothing, so it may be repeated freely and takes no Idempotency-Key. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body WarningMessagePreviewBody
action(string): One of `restart`, `stop`, `game_update`, `framework_update` and `wipe`.message(string): The message to preview; empty or absent previews the built-in text.warningMinutes(integer): Whole minutes from 0 to 60; absent is the normal warning (5).
Success: 200 WarningMessagePreviewResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Commands and broadcasts
Send a broadcastPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/broadcast
sendBroadcast
Sends this text once as server chat. The text is never run as a command. Returns the operation. Needs automation.manage.
Workspace permission: automation.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body BroadcastRequestBody
admission(AdmissionBody)text(string)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Run a console commandPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/command
runCommand
Runs this console command once on the server, exactly as typed, and returns the operation. The first word is the command name; a line break or control character is refused. A lost answer from the server is outcome_unknown and the command is never sent again. Needs servers.console.execute.
Workspace permission: servers.console.execute
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body CommandRequestBody
admission(AdmissionBody)command(string)keepOutput(boolean)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
List saved broadcastsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/saved-broadcasts
listSavedBroadcasts
The server's active saved broadcasts, oldest first. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 SavedBroadcastListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Save a broadcastPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/saved-broadcasts
createSavedBroadcast
Saves broadcast text at revision 1: a game_chat message template whose placeholders are filled from the game when it is sent. Nothing is sent to the server. Needs automation.manage.
Workspace permission: automation.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body SavedBroadcastRequestBody
name(string)text(string)
Success: 201 SavedBroadcastResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Read a saved broadcastGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/saved-broadcasts/{broadcastId}
getSavedBroadcast
The broadcast at its current revision. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- broadcastId (path, required)
- See the downloadable contract for the field schema.
Success: 200 SavedBroadcastResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change a saved broadcastPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/saved-broadcasts/{broadcastId}
updateSavedBroadcast
Saves the next revision. Requires If-Match with the revision you read. Needs automation.manage.
Workspace permission: automation.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- broadcastId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body SavedBroadcastRequestBody
name(string)text(string)
Success: 200 SavedBroadcastResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Send a saved broadcastPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/saved-broadcasts/{broadcastId}/actions/send
sendSavedBroadcast
Sends the broadcast once at the revision in If-Match as server chat. Returns the operation; without an answer from the server it is outcome_unknown, shown as possibly delivered, and never sent again. Needs automation.manage.
Workspace permission: automation.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- broadcastId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body SendSavedBroadcastRequestBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 412, 422, 428, default.
Archive a saved broadcastPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/saved-broadcasts/{broadcastId}/archive
archiveSavedBroadcast
Stops the broadcast from being changed or sent. Every enabled schedule that sends it is disabled with disabledReason definition_archived. Repeating it changes nothing. Needs automation.manage.
Workspace permission: automation.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- broadcastId (path, required)
- See the downloadable contract for the field schema.
Success: 200 SavedBroadcastResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List saved commandsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/saved-commands
listSavedCommands
The server's active saved commands, oldest first. Needs servers.console.read.
Workspace permission: servers.console.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 SavedCommandListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Save a commandPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/saved-commands
createSavedCommand
Saves a console command with typed placeholders at revision 1. Nothing is sent to the server. Needs servers.console.execute and automation.manage.
Workspace permission: servers.console.execute
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body SavedCommandRequestBody
name(string)parameters(list of CommandParameterBody)template(string)
Success: 201 SavedCommandResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Read a saved commandGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/saved-commands/{commandId}
getSavedCommand
The command at its current revision; the ETag carries the revision. Needs servers.console.read.
Workspace permission: servers.console.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- commandId (path, required)
- See the downloadable contract for the field schema.
Success: 200 SavedCommandResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change a saved commandPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/saved-commands/{commandId}
updateSavedCommand
Saves the next revision. Requires If-Match with the revision you read. Nothing is sent to the server. Needs servers.console.execute and automation.manage.
Workspace permission: servers.console.execute
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- commandId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body SavedCommandRequestBody
name(string)parameters(list of CommandParameterBody)template(string)
Success: 200 SavedCommandResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Run a saved commandPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/saved-commands/{commandId}/actions/run
runSavedCommand
Runs the command once at the revision in If-Match with one value per parameter. Returns the operation. A lost answer from the server is outcome_unknown and the command is never sent again. Needs servers.console.execute.
Workspace permission: servers.console.execute
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- commandId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body RunSavedCommandRequestBody
admission(AdmissionBody)arguments(object)keepOutput(boolean)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 412, 422, 428, default.
Archive a saved commandPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/saved-commands/{commandId}/archive
archiveSavedCommand
Stops the command from being changed or run. Its revisions and the operations that ran it are kept. Every enabled schedule that runs it is disabled with disabledReason definition_archived. Repeating it changes nothing. Needs servers.console.execute and automation.manage.
Workspace permission: servers.console.execute
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- commandId (path, required)
- See the downloadable contract for the field schema.
Success: 200 SavedCommandResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
World
Count what the world holdsPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/count-entities
countWorldEntities
Counts entities by group and lists the most common prefabs. Follow the operation, then read the result with getWorldRead. Needs worlds.read.
Workspace permission: worlds.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body CountEntitiesRequestBody
ownerSteamId(string): Count only what the game says this player owns.quiet(boolean): True for a lookup a screen makes by itself: it is not listed in Activity and not announced when it ends, whatever its end.top(integer): How many of the most common prefabs to list, 1 to 100.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Count what each player ownsPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/count-owned-entities
countOwnedEntities
Counts buildings and deployables by owner, including offline players. Set maxAgeSeconds to 0 for a new reading. Read ownedCounts with getWorldRead. Use the returned world generation for a preview. Needs worlds.read.
Workspace permission: worlds.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body CountOwnedEntitiesRequestBody
max(integer): The most players to list, most entities first: 1 to 1000, 1000 when left out.maxAgeSeconds(integer): A kept count this many seconds old or newer is returned instead of a new pass: 0 to 300, 30 when left out.quiet(boolean): True for a lookup a screen makes by itself: it is not listed in Activity and not announced when it ends, whatever its end.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Find things in the worldPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/find-entities
findWorldEntities
Search by group, prefab text, owner Steam ID and an area given by its centre and radius in metres. The result includes up to 100 rows and the total found. Each row includes its network ID and world generation. Follow the operation and read the result with getWorldRead. Needs worlds.read.
Workspace permission: worlds.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body FindEntitiesRequestBody
group(string): Only this group: players, npcs, cupboards, beds, stashes, containers, loot, defences, vehicles, structures, animals, dropped, resources or other.max(integer): The most rows to return, 1 to 100.ownerSteamId(string): Only entities the game says this player owns: 17 digits.quiet(boolean): True for a lookup a screen makes by itself: it is not listed in Activity and not announced when it ends, whatever its end.radius(integer): Metres around the centre of the area, 1 to 6000.text(string): Only prefabs whose short name contains this text, ignoring case; at most 64 characters.x(integer): East of the map's centre in whole metres, the centre of an area.z(integer): North of the map's centre in whole metres.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Look at one thing in the worldPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/inspect-entity
inspectWorldEntity
Send the entity's network ID and world generation. The result includes its location, health, owner and whether it can be removed, plus cupboard access, upkeep, stacks and lock status where relevant. Read it with getWorldRead. Use the returned revision for a removal. If it returns entity_not_found or generation_changed, search again. Needs worlds.read.
Workspace permission: worlds.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body InspectEntityRequestBody
generation(string, required): The world generation from that row.name(string): The name the portal shows for the thing, only so the activity line says it; optional, up to 64 characters.netId(string, required): The network ID from a find row, as text.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Look inside a containerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/list-container-items
listWorldContainerItems
Read a container's slots, items and amounts. Read container with getWorldRead and use the returned revision for a removal. Needs worlds.read.
Workspace permission: worlds.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body InspectEntityRequestBody
generation(string, required): The world generation from that row.name(string): The name the portal shows for the thing, only so the activity line says it; optional, up to 64 characters.netId(string, required): The network ID from a find row, as text.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Look at everything a player ownsPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/preview-owned-entities
previewOwnedEntities
Previews the entities owned by the supplied Steam ID and returns a revision. Read ownedPreview with getWorldRead. Items owned by other players in the same base are left out. Needs players.entities.remove (Owner and Administrator).
Workspace permission: players.entities.remove
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body PreviewOwnedEntitiesRequestBody
generation(string, required): The world generation from a count, so a wipe in between is noticed.name(string): The name the portal shows for the player, only so the activity line says it; optional, up to 64 characters.steamId(string, required): The owner's Steam ID, 17 digits; online or not.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Look at the building a part belongs toPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/preview-structure
previewWorldStructure
Previews the building that contains the selected part, including how many parts and item stacks it has. Read structure with getWorldRead and send its revision if you remove the building. Needs worlds.read.
Workspace permission: worlds.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body InspectEntityRequestBody
generation(string, required): The world generation from that row.name(string): The name the portal shows for the thing, only so the activity line says it; optional, up to 64 characters.netId(string, required): The network ID from a find row, as text.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Take items out of a containerPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/remove-container-items
removeWorldContainerItems
Permanently removes the items in one slot, or all slots if slot is omitted. Send the generation and revision from the listing. If they changed, list the items again. The result reports how many stacks were removed. Needs players.structures.manage.
Workspace permission: players.structures.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RemoveContainerItemsRequestBody
generation(string, required): The world generation from the listing.name(string): The name the portal shows, only so the activity line says it; optional, up to 64 characters.netId(string, required): The network ID of the container, from the listing.revision(string, required): The revision from the listing: it names exactly the content that was shown.slot(integer): The one slot to empty; absent empties every slot.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Remove one thing from the worldPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/remove-entity
removeWorldEntity
Removes one previously inspected entity and its contents. Send the world generation and revision from the inspection. Players and building blocks or doors are ineligible. If the operation reports entity_not_found, generation_changed or revision_changed, inspect the target again. The removal is permanent. Needs players.structures.manage.
Workspace permission: players.structures.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RemoveEntityRequestBody
generation(string, required): The world generation from the inspect.name(string): The name the portal shows for the thing, only so the activity line says it; optional, up to 64 characters.netId(string, required): The network ID from the inspect, as text.revision(string, required): The revision from the inspect: it names the entity, its prefab and its owner.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Remove everything a player ownsPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/remove-owned-entities
removeOwnedEntities
Permanently removes the previewed items owned by one player. Send the preview's generation and revision. Use hardCap to cap removals and maxDriftPercent to cap how much of the set may have changed since preview. If the result is preview_expired or drifted, preview again. The result counts removals, items already gone, items still there and items that changed owner. Needs players.entities.remove (Owner and Administrator).
Workspace permission: players.entities.remove
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RemoveOwnedEntitiesRequestBody
generation(string, required): The world generation from the preview.hardCap(integer): The most entities one removal may take: 1 to 100000, 5000 when left out.maxDriftPercent(integer): The most of the set, in whole percent, that may have vanished or changed owner since the preview: 0 to 100, 10 when left out.name(string): The name the portal shows for the player, only so the activity line says it; optional, up to 64 characters.revision(string, required): The revision from the preview.steamId(string, required): The owner's Steam ID, 17 digits.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Remove a whole building from the worldPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/remove-structure
removeWorldStructure
Permanently removes the previewed building and its contents. Send the world generation and revision from the preview. If it changed, preview again. The result says how many parts were removed and whether some remain. Needs players.structures.manage.
Workspace permission: players.structures.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RemoveEntityRequestBody
generation(string, required): The world generation from the inspect.name(string): The name the portal shows for the thing, only so the activity line says it; optional, up to 64 characters.netId(string, required): The network ID from the inspect, as text.revision(string, required): The revision from the inspect: it names the entity, its prefab and its owner.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Unlock a hackable cratePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/unlock-crate
unlockWorldCrate
Unlock a locked hackable crate now, or set afterSeconds to a value from 0 to 3600. The result includes its state and time remaining. Needs players.structures.manage.
Workspace permission: players.structures.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body UnlockCrateRequestBody
afterSeconds(integer): Seconds until it unlocks by itself, 0 to 3600; absent or 0 unlocks it now.generation(string, required): The world generation the crate was seen in.name(string): The name the portal shows, only so the activity line says it; optional, up to 64 characters.netId(string, required): The network ID of the crate, as text.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Get what a count, find or inspect foundGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/world-reads/{operationId}
getWorldRead
Read the result of a world count, find or inspect when the operation ends. State is running, read or unavailable. Read again before acting. This request needs worlds.read on the server.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- operationId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WorldReadResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Worlds
Plan a new mapPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/plan-wipe
planWipe
Returns a preview of the wipe: the new map (level or levelUrl when given, else the kind of map the server has), its seed (random unless seed is given) and size (the current one unless worldSize is given) with where each came from, which files would be removed and which kept in the categories map, blueprints, player_data and clans. Send the returned fingerprint with the approved wipe. You can preview a wipe while the server runs. Needs worlds.reset on the server.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body PlanWipeRequestBody
admission(AdmissionBody)blueprints(boolean): True also resets every player's blueprints.clans(boolean): True also resets the clans.keepMap(boolean): True keeps the map and what was built on it, so only the other categories chosen are reset.level(string): The map to wipe to: a bundled map's name (for example `CraggyIsland`) or `Procedural Map` for a generated one (`seed` and `worldSize` apply).levelUrl(string): The address of a custom map file (`http` or `https`) the game downloads and players download from the game.planId(string): Absent for the simple wipe.playerData(boolean): True also resets player data (deaths, identities, states and tokens).rotation(RotationBody)seed(integer): The seed of the new map, 0 to 2147483647.worldSize(integer): The world size of the new map in metres, 1000 to 6000.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Wipe the mapPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/actions/wipe-map
wipeMap
Send the reviewed plan's fingerprint. The wipe warns players for warningMinutes (default 5), saves and stops the server and makes a backup unless backup is false. It removes the planned files and applies the new map settings. Set keepMap to keep the map and what players built on it. Blueprints, player data and clans are removed only if selected. The server starts again unless startAfter is false. Cancel before the server starts saving. Returns the wipe operation. Needs worlds.reset and servers.lifecycle on a ready server.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body WipeMapRequestBody
admission(AdmissionBody)backup(boolean): False skips the backup before the files go; true takes it.blueprints(boolean): True also resets every player's blueprints.clans(boolean): True also resets the clans.fingerprint(string, required): A wipe whose world no longer matches it is refused before anyone is warned (plan_changed): plan again.keepMap(boolean): At least one other category must then be reset.level(string): Absent for a custom map.levelUrl(string)mapName(string): The map's name after the wipe: letters, digits, spaces and .planId(string): A saved wipe (`wpl_...`) to run, as it is now.playerData(boolean): True also resets player data.rotationEntry(string): Absent for a wipe that is not a rotation's.seed(integer, required)startAfter(boolean): False leaves the server stopped afterwards, as a stop does.warningMinutes(integer): Minutes of player warning before the server stops, from 0 to the longest warning (60); players see a countdown in chat.wipeDateName(string): The server name the wipe date is added to once the server is back up (`My Server` becomes `My Server 3 Dec`), 1 to 100 characters.wipeDateZone(string): Only with `wipeDateName`: the time zone, for example `Australia/Brisbane`.worldSize(integer, required)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read a server's map nameGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/map-name
getMapName
The name the server shows in the game's server list (needs the companion plugin) and in Discord, whether it is shown in the server list (true unless switched off), whether the companion plugin is in the server's plugin list, and the operation that gave the latest revision to the host. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 MapNameResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a server's map namePUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/map-name
saveMapName
Saves the map name and whether to show it in the server list. Discord uses the new name. The RustSC companion plugin is required to update the game server list. A 422 response at /name means the name needs changing. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body MapNameBody
name(string): The name shown in the game's server list (with the companion plugin) and in Discord: letters, digits, spaces and .showInList(boolean): False keeps the name out of the game's server list (Discord still uses it).
Success: 200 MapNameResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the extras of a server's wipesGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-extras
listWipeExtras
An extra is a set of files to add, files or folders to remove, a plugin file or a template line to leave out this time. It is only a record of names, sizes and fingerprints; the files are on the server's host. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- planId (query)
- See the downloadable contract for the field schema.
- templateId (query)
- See the downloadable contract for the field schema.
Success: 200 WipeExtraListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Add an extra to a saved wipePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-extras
addWipeExtra
kind add_files and plugin_source list files (path, size, fingerprint) and start uploading; remove_paths and leave_out are ready at once. A target is the framework (oxide or carbon), one of its folders and a path below it; protected paths (the framework's own files, permission data and the companion plugin), names Windows reserves and the root of a folder are refused at the field with the reason. add_files and remove_paths need servers.files.write, plugin_source also plugins.manage. A plugin_source may instead carry the address the member approved after checkWipePluginAddress (with the one file's size and fingerprint the check reported and the plugin's versionLabel): it is ready at once, nothing is uploaded or stored on the host, and the wipe fetches the file and installs it only while it is that file. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body AddWipeExtraBody
address(string): For plugin_source only: the https address the member approved after `checkWipePluginAddress`.files(list of WipeFileBody): The files, for add_files and plugin_source; the bytes follow by upload.kind(string): `add_files`, `remove_paths`, `plugin_source` or `leave_out`.label(string): What the member calls it, 1 to 40 characters.leavesOut(string)planId(string)repeat(string)target(WipeTargetBody)templateId(string): The template (`wtp_...`); a line repeats at every wipe that uses it.uploadId(string): For add_files and a plugin_source the member uploaded: the upload (`upl_...`) the files came from.versionLabel(string): For an address: the plugin version the check read from the file, up to 64 characters, for sentences.
Success: 201 WipeExtraResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Check a plugin at a web addressPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-extras/actions/check-plugin-address
checkWipePluginAddress
Checks a direct HTTPS link to a plugin. Use a file address without credentials. The operation's address result includes found and, when available, the file name, version, size and fingerprint to send with addWipeExtra. Needs worlds.reset, servers.files.write and plugins.manage on a ready server.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body CheckWipePluginAddressBody
address(string): The https address of the plugin file, at most 2000 characters, with no name and password in it.admission(AdmissionBody)framework(string): `oxide` or `carbon`: the framework the plugin is installed under.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Remove an extraDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-extras/{extraId}
removeWipeExtra
Removes the extra's record; the host removes its saved copy. An extra that is in place is 409 extra_in_place: take it out first. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- extraId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Change an extraPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-extras/{extraId}
changeWipeExtra
Saves the next revision of an extra's label, target, repeat or files; every member is saved as given. Requires If-Match with the revision you read. New files start a new upload. An extra that is in place is changed only in its label and repeat (409 extra_in_place). Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- extraId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body ChangeWipeExtraBody
files(list of WipeFileBody): New files start a new upload.label(string)repeat(string)target(WipeTargetBody)uploadId(string): The upload (`upl_...`) the new files came from, as for an added extra; only with `files`.
Success: 200 WipeExtraResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Put an extra in place nowPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-extras/{extraId}/actions/put-in-place
putWipeExtraInPlace
Puts the extra in place while the game keeps running. Unless the plugin is permanent, changes last until the next wipe or until you take them out. Optional files replace the extra's current files. If a plugin fails to load, the earlier files are restored. Use an extra that is ready, used or failed, or in_place with replacement files. If it returns extra_not_ready, wait for the upload. Needs worlds.reset, servers.files.write and plugins.manage.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- extraId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body PutWipeExtraInPlaceBody
admission(AdmissionBody)files(list of WipeFileBody): To replace the extra's files while putting it in place: the new list of files the member uploaded (path, size, fingerprint).
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Save an extra to its plan's templatePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-extras/{extraId}/actions/save-to-template
saveWipeExtraToTemplate
An extra whose files are not on the host yet is 409 extra_not_ready; a line of a template or a leave out is 409 not_saveable. Needs worlds.reset, servers.files.write for files and plugins.manage for a plugin.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- extraId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body SaveWipeExtraToTemplateBody
Success: 201 WipeExtraResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Take an extra out nowPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-extras/{extraId}/actions/take-out
takeWipeExtraOut
Restores the earlier files and removes the files added by the extra. The extra becomes used, or ready if it repeats. A 409 not_in_place means the extra is already out. If the server is offline or busy, try again when ready. Needs worlds.reset and servers.files.write.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- extraId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body TakeWipeExtraOutBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Use an extra againPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-extras/{extraId}/actions/use-again
useWipeExtraAgain
An extra that is not used is 409 not_used. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- extraId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WipeExtraResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List a server's saved wipesGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-plans
listWipePlans
storage is the saved files the server's host holds against the server's limit (2 GiB). Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WipePlanListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a new wipe planPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-plans
createWipePlan
It uses Usual wipe unless templateId names another template, and has its own options, warning and steps only where they differ from the template's. Changing plugins at the wipe needs plugins.manage. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body WipePlanBody
name(string): One to 40 characters, unique on the server.options(WipeOptionsBody)steps(WipeStepsBody)templateId(string): The template (`wtp_...`).warningMinutes(integer): Absent uses the template's.
Success: 201 WipePlanResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Delete a saved wipeDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-plans/{planId}
deleteWipePlan
This is the only way a saved plan is removed. The saved files on the server's host are removed by the host. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- planId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Read a saved wipeGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-plans/{planId}
getWipePlan
Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- planId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WipePlanResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change a saved wipePUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-plans/{planId}
updateWipePlan
Saves the next revision; every member is saved as given. Requires If-Match with the revision you read. A save that changes nothing keeps the revision. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- planId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body WipePlanBody
name(string): One to 40 characters, unique on the server.options(WipeOptionsBody)steps(WipeStepsBody)templateId(string): The template (`wtp_...`).warningMinutes(integer): Absent uses the template's.
Success: 200 WipePlanResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Wipe again or schedule a saved wipePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-plans/{planId}/actions/arm
rearmWipePlan
Requires If-Match with the revision you read. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- planId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body ArmWipePlanBody
scheduleId(string): Needs schedules.manage.useExtrasAgain(boolean): Absent or false leaves them used.
Success: 200 WipePlanResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Switch off a saved wipePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-plans/{planId}/actions/pause
pauseWipePlan
Switches off a saved wipe that no schedule runs (a wipe started by hand): everything stays saved and Start now is refused with 409 state_conflict paused until resumeWipePlan. Repeating it changes nothing. A wipe that a schedule runs is 409 state_conflict scheduled; switch its schedule instead. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- planId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WipePlanResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Switch on a saved wipePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-plans/{planId}/actions/resume
resumeWipePlan
Switches a saved wipe that no schedule runs back on, so it can be started by hand again. Repeating it changes nothing. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- planId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WipePlanResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Copy a saved wipePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-plans/{planId}/duplicate
duplicateWipePlan
The copies point at the same saved files, so a copy costs no space. The name defaults to the original's and ' copy'. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- planId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body DuplicateWipeBody
name(string): The copy's name.
Success: 201 WipePlanResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
See what a saved wipe will doGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-plans/{planId}/preview
previewWipePlan
Delete lines that name a folder or a pattern are listed as lines; the host lists the files when the wipe starts. Changes nothing and sends nothing. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- planId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WipePreviewResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List the runs of a saved wipeGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-plans/{planId}/runs
listWipeRuns
Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- planId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WipeRunListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read a server's wipe settingsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-settings
getWipeSettings
The choices and player warning the Wipe page starts from: the map, what else is reset, whether the server starts again, the protective backup and the warning. While nothing was saved this is the default wipe (a new random map of the kind the server has, nothing else reset, a backup first, a start afterwards, a 5 minute warning) with revision 0. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WipeSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a server's wipe settingsPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-settings
saveWipeSettings
Stores the choices and warning as the next revision. It does not wipe, schedule or change the server, so it works while the server or its host is offline. A choice that cannot be used is refused with 422 at its field under /options (out_of_range, not_applicable, level_unknown, url_invalid and the other map reasons) and a warning outside 0 to 60 at /warningMinutes. A wipe or a scheduled wipe takes a copy of the choices when it is started or saved, so saving later never changes a wipe already scheduled. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body WipeSettingsBody
keepHours(integer): Wipes within this many hours of the last wipe that counted do not take out "This wipe only" files or end temporary changes that end at the wipe, from 0 to 168.options(WipeOptionsBody)warningMinutes(integer): Minutes of player warning before the server stops, from 0 to the longest warning (60).
Success: 200 WipeSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List a server's wipe templatesGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-templates
listWipeTemplates
The server's templates, Usual wipe first. Usual wipe is the template every server has: its options are the server's saved wipe settings, so a member who never opens templates sees no change. A template is a named recipe: the wipe's options and warning, the steps (clean-up, plugins at the wipe, game update) and its lines (files added and removed at every wipe that uses it). Templates belong to one server. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WipeTemplateListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a new wipe templatePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-templates
createWipeTemplate
Saves a template at revision 1. Absent options are the default wipe, an absent warning is the normal 5 minutes and absent steps are the register's defaults (old logs and leftover world files on, plugins left alone). A name is 1 to 40 characters and unique on the server; at most 20 templates. Changing plugins at the wipe needs plugins.manage. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body WipeTemplateBody
name(string): One to 40 characters, unique on the server.options(WipeOptionsBody)steps(WipeStepsBody)warningMinutes(integer): Minutes of player warning, 0 to 60.
Success: 201 WipeTemplateResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Delete a wipe templateDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-templates/{templateId}
deleteWipeTemplate
Deletes the template and its lines. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- templateId (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Read a wipe templateGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-templates/{templateId}
getWipeTemplate
Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- templateId (path, required)
- See the downloadable contract for the field schema.
Success: 200 WipeTemplateResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change a wipe templatePUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-templates/{templateId}
updateWipeTemplate
Saves the next revision; every member is saved as given. Requires If-Match with the revision you read. A save that changes nothing keeps the revision. Usual wipe keeps its name, and its options and warning are saved as the server's wipe settings. Changing plugins at the wipe needs plugins.manage. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- templateId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body WipeTemplateBody
name(string): One to 40 characters, unique on the server.options(WipeOptionsBody)steps(WipeStepsBody)warningMinutes(integer): Minutes of player warning, 0 to 60.
Success: 200 WipeTemplateResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Copy a wipe templatePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/wipe-templates/{templateId}/duplicate
duplicateWipeTemplate
Copies the template with what it resolves to and its lines. The copies of file lines point at the same saved files, so a copy costs no space. The name defaults to the original's and ' copy'. Needs worlds.reset.
Workspace permission: worlds.reset
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- templateId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body DuplicateWipeBody
name(string): The copy's name.
Success: 201 WipeTemplateResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Server files
Keep files for a server until a person has looked at themPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/attachments
stageServerAttachment
Provides files for a person to look at; nothing is put on a server and nothing is run. kind plugin: plugins/Name.cs. kind library: data/plugin-inbox/Name.cs (waits in the plugin library's inbox). kind config: config/** (Oxide) or configs/** (Carbon), .json. kind data: data/**, .json .txt .csv .xml .yaml .yml .png .jpg. kind language: lang/<code>/Name.json. Each file has a path from inside the framework's folder (never oxide/ or carbon/ first) and text or contentBase64 (or uploadSlotId for a file over 1 MiB that was sent to an address from createServerAttachmentUploadAddress). One top folder per call, at most 50 files, 1 MiB each, 4 MiB together, UTF-8 text (or a real PNG or JPEG in data), valid JSON for .json. No archive, program, .., absolute path, drive letter, backslash, Windows-reserved name, trailing dot or space, program extension inside a name, framework file, companion file, RustSC record or server file. A 422 response names the file to correct (/files/{n}/path or /content). The same files give the same attachment back. The answer lists the files and their previews. Send its manifestSha256 with applyServerAttachment. Use the attachment within 24 hours. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body StageAttachmentBody
files(list of AttachmentFileBody)framework(string): `oxide` or `carbon`.kind(string): `plugin`, `library`, `config`, `data` or `language`.label(string): What the person sees ("Kits profiles"): up to 120 characters.
Success: 200 AttachmentResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Get an address to send one large file toPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/attachments/upload-addresses
createServerAttachmentUploadAddress
For a file over 1 MiB (up to 16 MiB). Give framework, kind, the path relative to the framework folder, the exact size in bytes and sha256 (64 hex characters). The answer has url and uploadKey, shown once: send the file with a plain HTTPS PUT of its bytes to url with the header Authorization: Bearer <uploadKey> within 10 minutes. Use the address once for the selected file. If the upload fails or expires, request a new address. Then call stageServerAttachment with that file as {uploadSlotId: id} (path is optional); the file goes through the same rules, preview and approval as any attachment, up to 32 MiB with the others. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body AttachmentUploadAddressBody
bytes(integer): The exact size of the file in bytes: at most 16 MiB.framework(string): `oxide` or `carbon`.kind(string): `plugin`, `library`, `config`, `data` or `language`.path(string): The path from inside the framework's folder; the address carries only a file for this path.sha256(string): The fingerprint of the file as 64 hexadecimal characters.
Success: 200 AttachmentUploadAddressResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Throw a staged attachment awayDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/attachments/{attachmentId}
discardServerAttachment
Discards an attachment. An attachment already being applied finishes. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- attachmentId (path, required)
- See the downloadable contract for the field schema.
Success: 200 AttachmentResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read a staged attachmentGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/attachments/{attachmentId}
getServerAttachment
Lists the attachment's files, sizes and available previews. Its state is ready, applying, applied, failed, expired or cancelled. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- attachmentId (path, required)
- See the downloadable contract for the field schema.
Success: 200 AttachmentResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Put a staged attachment on the serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/attachments/{attachmentId}/actions/apply
applyServerAttachment
Puts the staged files in the selected folder. Some files may succeed even if another file is refused. keep_both: the new file takes a free name. A plugin is loaded or reloaded and the game's answer is reported. Send ifExists and the attachment's manifestSha256. A 409 response means attachment_changed or attachment_ended. Returns an operation. An assistant's call waits for approval by default. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- attachmentId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ApplyAttachmentBody
admission(AdmissionBody)ifExists(string)manifestSha256(string): The `manifestSha256` the attachment answered: the person approves exactly these files.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Start uploading files to a server's hostPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/uploads
startServerUpload
Starts an upload of a dropped group of files and folders (one tar stream) and returns a ticket and the address to send the chunks to. The same member dropping the same items on the same server (the same signature) gets the unfinished upload back with its offset and a new ticket, which is how an upload resumes after a closed page; the earlier ticket stops working. The figures are checked against the limits: 1 to 5000 entries, at most 2 GiB of files, a stream length that fits a tar of those entries (422 on the field, for example /contentBytes server_full when the server already has uploads in transit that would pass 2 GiB), 30 uploads a member an hour and 4 GiB in transit for the workspace (422 too_many_uploads, workspace_busy). The ticket is returned once. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body BeginUploadBody
contentBytes(integer): Bytes of the files themselves (at most 2 GiB).entries(integer): Files and empty folders in the stream (1 to 5000).files(integer): Files among them.name(string): What the member sees ("Halloween pack"): up to 120 characters.signature(string): Lower-case hexadecimal signature of the selected files.totalBytes(integer): Bytes of the tar stream that will be sent: the files plus their headers and padding.
Success: 200 UploadTicketResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Stop an uploadDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/uploads/{uploadId}
cancelServerUpload
Stops an upload that has not ended and removes the bytes RustSC holds for it (within a minute). An upload that already ended answers as it is. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- uploadId (path, required)
- See the downloadable contract for the field schema.
Success: 200 UploadResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read an uploadGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/uploads/{uploadId}
getServerUpload
Shows whether the upload is uploading, complete, waiting, receiving, ready, failed, expired or cancelled. When ready, files lists the names, sizes and values needed to refer to them. For a failure, use the returned reason and path to correct the upload. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- uploadId (path, required)
- See the downloadable contract for the field schema.
Success: 200 UploadResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Send a finished upload to the server's hostPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/uploads/{uploadId}/actions/deliver
deliverServerUpload
Asks the server's host to take a complete upload: waits while the host is offline (then the upload expires and the member is told to upload it again) and, when the host takes it, downloads the file from RustSC, checks it, unpacks it into its own holding area (no link, device, traversal, reserved Windows name or clash of capital letters is accepted) and tells RustSC what it holds. RustSC deletes its copy when the host has confirmed. Nothing is placed in a game folder. An upload that is not complete answers 409 upload_incomplete. Returns the operation. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- uploadId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body DeliverUploadBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Put a finished upload in a folder of the serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/uploads/{uploadId}/actions/place
placeServerUpload
Places the completed upload in the selected Oxide or Carbon folder: plugins, config, data or lang. Choose replace or keep_both for a file name that already exists. The operation reports each file separately. A rented server may return an unconfirmed plugin result. A 422 response at /folder means choose another folder. Needs servers.files.write.
Workspace permission: servers.files.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- uploadId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body PlaceUploadBody
admission(AdmissionBody)folder(string): The folder below the framework's, such as `oxide/plugins`.framework(string): `oxide` or `carbon`.ifExists(string): `replace` (default; the old file is kept beside it) or `keep_both`.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Server configuration
Read a server's configurationGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/configuration
getServerConfiguration
The saved server.cfg settings, the apply state of the saved revision, the latest apply with each setting's outcome, and the settings RustSC manages with their rules. The ETag carries the revision. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ServerConfigurationResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save configuration changesPATCH /api/v1/workspaces/{workspaceId}/servers/{serverId}/configuration
saveServerConfiguration
Saves the changes as the next revision, or changes nothing when every value is already saved. A value sets a setting, null unsets it, and settings not named keep their value. Saving does not change the server: apply the revision to write it to the server. Launch, world and secret settings are refused. Needs servers.config.write.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body ConfigurationPatchBody
values(object, required)
Success: 200 ServerConfigurationResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Apply the saved configurationPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/configuration/actions/apply
applyServerConfiguration
Writes the revision in If-Match to the server's server.cfg and sets the values a running game takes live, then reads them back. It never restarts the game: the operation's result says per setting whether it is in effect now or from the next start (restartRequired). Settings changed in the file outside RustSC stop the apply with config_file_conflict until you apply with acceptFileSha256. Returns the operation. Needs servers.config.write.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body ApplyConfigurationRequestBody
acceptFileSha256(string): The fingerprint (64 lowercase hex characters) of the server's current `server.cfg`, from a failed apply's `write_files` result (`priorSha256`), to overwrite settings someone cha...acceptWorldChange(boolean): True when the member was told that this revision changes the map or the world and saves it anyway: another custom map file name, another bundled level, or another size or seed o...admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 412, 422, 428, default.
Check an image linkPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/configuration/actions/check-image
checkServerImageLink
Looks at a header or logo image link from RustSC and reports what is there: the picture type and pixel size read from the file itself, its size in bytes, and whether it differs from the recommended size or type. The game accepts any address and checks nothing, so the answer informs and never stops a save. Only public web addresses are fetched; the picture is measured and dropped, never stored. Answers 200 with a result such as unreachable or not_an_image rather than an error. Needs servers.config.write.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body CheckImageRequestBody
key(string, required): `server.headerimage` or `server.logoimage`.url(string, required): An absolute `http` or `https` address.
Success: 200 CheckImageResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, 429, default.
Inspect the server configurationPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/configuration/actions/inspect
inspectServerConfiguration
Reads the server's current settings without restarting it. If the response is lost, repeat the original body and Idempotency-Key. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body InspectConfigurationRequestBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read configuration inspection historyGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/configuration/observation
getConfigurationObservation
Historical sanitized file, startup and running comparisons from this server's current installation. Reading sends no command to the host. The latest request and last successful capture are separate; a successful capture may be partial. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ConfigurationObservationResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read server network endpointsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/endpoints
getServerEndpoints
Shows the desired and applied ports and any pending or failed operation. Refresh if the current settings are unknown. Use the returned ETag for endpoint changes. otherServers lists ports reported by other servers on this host. The evidence for a refresh or apply includes running, listenersComplete and listeners, with protocol, address and port for each entry. When available, network has the host's IPv4 and IPv6 addresses. For reachability, use the reachability check. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 EndpointResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save desired server portsPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/endpoints
saveServerEndpoints
Saves all three desired ports without restarting the server. Send expectedScope and expectedRevision from the current endpoint settings and pass their ETag in If-Match. If the settings changed, read them again before retrying. Apply saved ports separately. Needs servers.config.write.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body EndpointBody
admission(AdmissionBody)expectedRevision(integer, required)expectedScope(string, required)ports(EndpointPortsBody, required)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 412, 422, 428, default.
Apply saved server portsPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/endpoints/apply
applyServerEndpoints
Set mode to stopped_only to apply ports while the server stays stopped, or restart_running to apply through a restart (also needs servers.lifecycle). Send the current saved endpoint scope and revision. If the outcome is unknown, inspect the operation before retrying. Needs servers.config.write.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body ApplyEndpointsBody
admission(AdmissionBody)expectedPlanSha256(string, required)expectedRevision(integer, required)expectedScope(string, required)mode(string, required)ports(EndpointPortsBody, required)warningSeconds(integer, required)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 412, 422, 428, default.
Read endpoints from the hostPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/endpoints/refresh
refreshServerEndpoints
Refresh the endpoints for this server. Follow the operation, then read the endpoints again before changing them. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body RefreshEndpointsBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read the Windows Firewall rule of a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/firewall-rule
getServerFirewallRule
state is open when the host added the rule and read it back from Windows; ports, profiles and programScoped say exactly what it opens. Compare ports with the server's ports: when they differ, the rule is for earlier ports (the host removes the rule when the game or query port changes, and a Rust+ port change leaves it until the rule is added again). change is the newest change when it has not finished or did not succeed. Only a Windows host can add the rule; RustSC never changes a Linux firewall. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 FirewallRuleResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Add the Windows Firewall rulePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/firewall-rule/actions/add
addServerFirewallRule
One operation on the server's Windows host. The host reads the server's applied ports and makes its rules match exactly: inbound allow rules for the game and query ports (UDP) and, while Rust+ has a port, that port (TCP), for the private and public network profiles, limited to the game program in the server's folder. RCON is never opened. The rules are named RustSC, the server's name and the port's role, and belong to the group Rust Server Cupboard. Repeating it changes nothing; it also brings a rule for earlier ports up to date. The operation succeeds only when the host read the rules back from Windows with the expected ports. A Linux host fails it with firewall_not_windows. Needs servers.config.write.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body FirewallRuleChangeBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Remove the Windows Firewall rulePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/firewall-rule/actions/remove
removeServerFirewallRule
One operation on the server's Windows host that removes every rule RustSC added for this server and nothing else. A rule that is already gone completes as a no-op. Needs servers.config.write.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body FirewallRuleChangeBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Read whether players can reach the serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/reachability
getServerReachability
The latest answer of the reachability check: reachable (the server's query port answered from the internet), unreachable (the server runs and nothing came back) or not_checked with a reason (server_stopped, server_starting, server_not_running, host_offline, ports_unknown, address_unknown, address_private, address_ipv6, unsupported, probe_failed or not_yet), with the address and ports a check tested. hostAddress is the public IPv4 address RustSC sees for the host's connection; it is not a verdict. It never sends anything: a check runs only when you ask for one with the check route. A stopped server is never reported as unreachable. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ReachabilityResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save the public IPv4 address of the serverPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/reachability/address
setServerPublicAddress
Saves the public IPv4 address the member typed for this server (null removes it); the player access check tests it first, before any address RustSC knows from the host's connection, the host or the game, and says so (addressSource entered). Only a public IPv4 address is accepted: 422 on /address with not_ipv4 (an IPv6 address, a name or other text) or not_public (private, loopback or reserved). Saving sends nothing to the host and does not run a check. Answers as the read does. Needs servers.config.write.
Workspace permission: servers.config.write
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body PublicAddressBody
address(string, required): A public IPv4 address such as `203.0.113.5`; null removes the saved one.
Success: 200 ReachabilityResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Check that players can reach the serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/reachability/check
checkServerReachability
Checks whether the server answers from the internet without changing its settings. If the check is unavailable until later, the response includes nextCheckAt. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ReachabilityResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Console
Search older console linesPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/console/search
searchConsole
Searches the console lines the server's host kept, newest first, with the text, Match case, Pattern and chips of the console and a period (hour, day or all the host kept). Returns up to 1,000 lines and how the search ended: only stopped finished with no lines means there are no matches; scan_limit, time_limit, result_limit and budget say older lines may exist. It waits at most about 20 seconds for the host: offline is capability_unavailable (host_offline); a rented server searches the lines RustSC kept from its console, and none yet is capability_unavailable (console_empty); for a rented server the periods yesterday and week read the game's own log and command history files at that moment (the lines are returned, nothing is kept), and no file to read is capability_unavailable (no_files); no timely or complete answer is dependency_unavailable (host, timed_out or incomplete); nothing is kept. A newer search of the same server replaces this one (state_conflict, search_replaced). A pattern the host cannot run is validation_failed on /pattern. Needs servers.console.read.
Workspace permission: servers.console.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body ConsoleSearchRequestBody
classes(list of string): The chips: `chat`, `warnings`, `errors`, `commands`.matchCase(boolean): <b>Match case</b>.pattern(boolean): <b>Pattern</b>: `text` is a regular expression the host runs in linear time.period(string): `hour`, `day` or `all` the host kept, measured on the host's clock.text(string): The search text; empty or missing for none.
Success: 200 ConsoleSearchResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, 503, default.
Message templates
Preview a message templatePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/message-templates/preview
previewMessageTemplate
Renders a template for one context with sample or supplied values and returns the exact text that context would send. Nothing is saved or delivered. Missing and stale values render as unknown, never as zero. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body MessageTemplatePreviewRequestBody
context(string)template(string)unknownText(string)values(object)
Success: 200 MessageTemplatePreviewResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Mod commands
List mod commandsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/mod-commands
listModCommands
The server's mod commands with their console lines, oldest first. Needs servers.console.read.
Workspace permission: servers.console.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ModCommandListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a mod commandPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/mod-commands
createModCommand
Saves a console command with blanks that moderators can run. Nothing is sent to the server. Needs servers.console.execute and automation.manage.
Workspace permission: servers.console.execute
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body ModCommandRequestBody
description(string)enabled(boolean): Whether moderators may run it; false when left out.fields(list of ModCommandFieldBody)name(string)template(string): The console line; its first word is the command and each blank is a whole word `{name}`.
Success: 201 ModCommandResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Change a mod commandPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/mod-commands/{modCommandId}
updateModCommand
Replaces the command, its blanks and whether moderators may run it. Requires If-Match with the revision you read. Nothing is sent to the server. Needs servers.console.execute and automation.manage.
Workspace permission: servers.console.execute
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- modCommandId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body ModCommandRequestBody
description(string)enabled(boolean): Whether moderators may run it; false when left out.fields(list of ModCommandFieldBody)name(string)template(string): The console line; its first word is the command and each blank is a whole word `{name}`.
Success: 200 ModCommandResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Run a mod commandPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/mod-commands/{modCommandId}/actions/run
runModCommand
Runs the command at the revision in If-Match with one typed value per blank. A value may hold letters, numbers, spaces and a few harmless characters; anything else is refused and nothing is sent. A command with one blank takes several values in it, one per line (a digits blank also takes spaces or commas between them), and runs once for each; one refused value refuses them all. Returns the first operation and operationIds, one per value. Needs servers.modcommands.run.
Workspace permission: servers.modcommands.run
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- modCommandId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body RunModCommandRequestBody
admission(AdmissionBody)values(object)
Success: 202 ModCommandRunResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 412, 422, 428, default.
Remove a mod commandPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/mod-commands/{modCommandId}/archive
archiveModCommand
Stops the command from being changed or run. The operations that ran it are kept. Repeating it changes nothing. Needs servers.console.execute and automation.manage.
Workspace permission: servers.console.execute
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- modCommandId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ModCommandResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the commands a moderator can runGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/runnable-mod-commands
listRunnableModCommands
The server's switched-on mod commands: name, description and blanks, never the console line. Needs servers.modcommands.run.
Workspace permission: servers.modcommands.run
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ModCommandRunnableListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Plugin library
Read the plugin library of a serverGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugin-library
getPluginLibrary
Every plugin file the server's temporary changes turn on, with its state (in_library, missing, on_now or newer_in_plugins_folder), its version and the changes that use it; what each change still needs (the missing file names); the newer versions the plugins folder holds; and the automatic switch. Built from the plugin list the server's host reported and the saved changes, so reported is false until the host has sent its list. A file operation of the library that finished since the last read is applied first. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 PluginLibraryResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Add dropped plugin files to the libraryPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugin-library/actions/add
addToPluginLibrary
Each file must already be on the host in the library's inbox folder, inboxFolder of the library read (the upload route puts it there). One operation renames the library copy it replaces to Name.cs.previous and moves the new file into its place; nothing is replaced in place. A file that is flagged is added only with addAnyway; a plugin a temporary change that is on has on is refused (409 on_now). Returns the file operation; the next read shows the result. Needs schedules.manage, servers.files.write and plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body AddToPluginLibraryBody
admission(AdmissionBody)files(list of DroppedPluginBody): The files, each already on the host in the library's inbox folder (the upload puts it there).framework(string)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Add the plugin files in the inbox to the libraryPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugin-library/actions/add-from-inbox
addPluginLibraryFromInbox
Moves the files the last inbox check found into the library the way an add does (the replaced copy is kept as the previous version). fileNames names the files; leave it out for every file that is added by default. 409 inbox_checking while a check is going, 409 inbox_empty when there is nothing to add, 409 on_now for a plugin a running change has on. Returns the file operation. Needs schedules.manage, servers.files.write and plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body AddFromPluginInboxBody
addAnyway(list of string): File names that were flagged and are added anyway.admission(AdmissionBody)fileNames(list of string): The plugin file names to add; leave it out to add every file that is added by default.framework(string)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Look in the plugin inboxPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugin-library/actions/check-inbox
checkPluginLibraryInbox
Check now for the inbox folder (inboxFolder of the library read, below the framework's folder): lists it and reads the version in the header of each .cs file. Call it again (or read the library) to go on; the answer's inbox says checking while the host's answers are still coming and lists the files with what adding each would do when it has them. A folder that does not exist is an empty inbox. Needs schedules.manage, servers.files.read, servers.files.write and plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body CheckPluginInboxBody
admission(AdmissionBody)framework(string)
Success: 200 PluginLibraryResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Look for newer versions at the plugins' GitHub update sourcesPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugin-library/actions/check-sources
checkPluginLibrarySources
Check now for every plugin that has a GitHub update source (set with sources in savePluginLibrarySettings): the server's host reads GitHub's public pages (the latest release, else the repository's files). Call it again (or read the library) to go on; each plugin's source says checking while the host's answers are still coming. RustSC also repeats the check on its own for a plugin whose source is set. Nothing is downloaded. Needs schedules.manage, servers.files.write and plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body CheckPluginSourcesBody
admission(AdmissionBody)framework(string)
Success: 200 PluginLibraryResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Put the previous version of a library plugin backPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugin-library/actions/go-back
goBackInPluginLibrary
Swaps the library copy with its previous version; pressing it again swaps back. 409 no_previous_version when none is kept. Returns the file operation. Needs schedules.manage, servers.files.write and plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body GoBackPluginLibraryBody
admission(AdmissionBody)fileName(string)framework(string)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Check what dropped plugin files would doPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugin-library/actions/preview-drop
previewPluginLibraryDrop
For each file the browser read (name, version from its header, fingerprint, size): add (new), replace (a newer version replaces the library copy, which is kept), replace_unknown, same, same_version_changed, older (a downgrade), cannot_compare, unreadable_version, on_now (a temporary change that is on has the plugin on) or name_invalid, with whether it is added by default and whether the member can add it anyway. Nothing is changed. 422 framework_required at /framework when the server runs both frameworks. Needs schedules.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body PreviewPluginDropBody
files(list of DroppedPluginBody)framework(string): `oxide` or `carbon`; needed only when the server runs both.
Success: 200 PluginDropPreviewResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Swap a running plugin to the newer version in the inbox and reload itPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugin-library/actions/swap-now
swapPluginLibraryPluginNow
Only with the hot swap choice on and only for a plugin a running temporary change has on: copies the inbox file into the running plugins folder (the running copy is kept) and reloads the plugin with the framework's own reload command. The library copy is not touched; when the change ends it puts back the version it held and the file waiting in the inbox brings the library up to date. 409 hot_swap_off, not_on_now, nothing_to_swap. Returns the file operation. Needs schedules.manage, servers.files.write and plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body SwapPluginNowBody
admission(AdmissionBody)fileName(string)framework(string)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Update the library from the plugins folderPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugin-library/actions/update-from-folder
updatePluginLibraryFromFolder
Copies the newer version of each named plugin from the server's plugins folder into the library inside the host, keeping the copy it replaces. 409 nothing_newer when the plugins folder has nothing newer, 409 on_now for a plugin a change that is on has on. Returns the file operation. Needs schedules.manage, servers.files.write and plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body UpdatePluginLibraryFromFolderBody
admission(AdmissionBody)fileNames(list of string): The plugin file names to take from the plugins folder.framework(string)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Take the newer version from the plugins' GitHub update sources into the libraryPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugin-library/actions/update-from-source
updatePluginLibraryFromSource
Updates the named library plugins with newer versions. The previous plugin, settings and data are kept. For nothing_from_source, check for updates again later. For on_now, wait until the temporary change ends. If busy, try again later. Needs schedules.manage, servers.files.write and plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body UpdatePluginLibraryFromSourceBody
admission(AdmissionBody)fileNames(list of string): The plugin file names to take from their update sources.framework(string)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Save the plugin library's choicesPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/plugin-library/settings
savePluginLibrarySettings
autoUpdate: update the library automatically when a newer version is found in the plugins folder or the inbox (off until a member turns it on; turning it on needs servers.files.read, servers.files.write and plugins.manage as well). It takes only a newer version: never a downgrade, the same version or a version that cannot be read; it leaves a plugin that is in keepManual, a plugin a running temporary change has on, a plugin that kept changing version (paused) and a library copy that was changed by hand. Each update is one line in Activity. keepManual: the plugin file names never updated automatically; it replaces the list. hotSwap: the separate choice that makes Swap now available for a plugin a running change has on (off when left out). resume: the plugin file names to take off a pause. Needs schedules.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body SavePluginLibrarySettingsBody
autoUpdate(boolean)hotSwap(boolean): "Also swap and reload the plugin on a running set".keepManual(list of string): The plugin file names kept manual; replaces the list.resume(list of string): The plugin file names to take off a pause (a plugin that kept changing version is paused until a member resumes it).selfHealing(boolean): "Put the previous version back when an update RustSC applied fails to load".sourcePicks(object): Plugin file name to the file picked from the source's list (a candidate's id).sources(object): Plugin file name to GitHub address (a repository, a releases page or a .cs file).timing(object): Plugin file name to `now`, `next_wipe` or `default`: when an update of that plugin is applied.updateTiming(string): The server's default for when an automatic run applies an update: `next_wipe` (held until the next wipe that counts, then applied) or `now`.
Success: 200 PluginLibraryResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Quick actions
List quick actionsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/quick-actions
listQuickActions
The quick actions that apply here: with player (a Steam ID) the actions for that player, without it the actions for the server. Each names what it asks for and the kinds of step it runs, in order. Reading changes nothing. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- player (query)
- See the downloadable contract for the field schema.
Success: 200 QuickActionListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 422, default.
Preview a quick actionPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/quick-actions/{actionId}/preview
previewQuickAction
Shows the steps the action would run with these values, in order, the exact input of each, whether it cannot be taken back and whether the caller holds the permission of each step now. Nothing is sent and nothing is saved; a value that is the wrong type, out of its bounds or holds a line break is refused at its pointer. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- actionId (path, required)
- See the downloadable contract for the field schema.
Request body QuickActionPreviewBody
arguments(object)player(string)
Success: 200 QuickActionPreviewResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Release channels
List release channelsGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/release-channels
listReleaseChannels
The chosen release channel of Rust, Oxide and Carbon on this server, the last release check of each and the channels each offers. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 ReleaseChannelListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Choose a release channelPUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/release-channels/{component}
selectReleaseChannel
Chooses the release channel of one component and checks it for releases. Choosing only checks: it installs nothing and changes no files on the server. Send the revision you read in If-Match ("r0" for the first choice). Choosing the current channel again changes nothing. Needs servers.software.manage.
Workspace permission: servers.software.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- component (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The component's revision as read, for example "r3"; "r0" before the first choice.
Request body SelectReleaseChannelRequestBody
buildFlavor(string): `none`, or for Carbon `release`, `debug` or `minimal`.channel(string): The RustSC channel name, for example `public`.platform(string): `linux-x64` or `windows-x64`.
Success: 200 ReleaseComponentResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 412, 422, 428, default.
Check a release channel againPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/release-channels/{component}/refresh
refreshReleaseChannel
Checks the chosen channel of one component for releases again. Installs nothing. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- component (path, required)
- See the downloadable contract for the field schema.
Success: 200 ReleaseComponentResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, default.
Temporary changes
List a server's temporary changesGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes
listTimedChanges
The server's temporary changes in the order they were made, each with its state (on, upcoming, paused, not_ready or finished), its group, its next start and its last run, and the figure under the list: what the server keeps of saved files against what it may keep. A temporary change stays after it finishes until it is deleted. delivery is waiting until the server's host has confirmed the newest saved version. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 TimedChangeListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a temporary changePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes
createTimedChange
Saves a named set of file changes with a start and end. Saving leaves the server as it is until the start. Upload files first, then send their sha256 and size. Review overlaps before saving. A 422 response lists any field to correct. Needs schedules.manage, servers.files.write and, when changing plugin folders, plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body TimedChangeRequestBody
enabled(boolean): On a save: false keeps the change paused.end(TimedChangeEndBody)files(string): `folder` for a change whose files are the ones in its visible folder on the server's host at every start (it then has no items); left out for a change that names its files in `i...items(list of TimedChangeItemBody)messages(TimedChangeMessagesBody)name(string)start(TimedChangeStartBody)timeZone(string): The member's IANA time zone, for example `Europe/London`.
Success: 201 TimedChangeResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
Take a plugin from the libraryPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/actions/prepare-library-plugin
prepareTimedChangeLibraryPlugin
The server's host looks up the newest release of the plugin in the library (uMod), downloads it itself, checks that it is a plugin file (an archive, an error page or a file over the size limit is refused) and keeps it, so a temporary change can name it and a start later needs neither the cloud nor the internet. Returns the operation; its fetch stage result holds plugin, version, fileName, sha256 and size, which an item of a temporary change names as source {origin: library, libraryName, libraryVersion, sha256, size}. Calling it again finds the newest release again, which is how a newer version is checked for. 422 invalid at /plugin for a name that is not letters, digits, dot, underscore and hyphen (at most 64); capability_unavailable when the host is offline unless admission.ifOffline holds it for later. Needs schedules.manage, servers.files.write and plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body PrepareLibraryPluginBody
admission(AdmissionBody)plugin(string): The plugin's name in the library, a plugin file name without `.cs`: letters, digits, dot, underscore and hyphen, at most 64 characters.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
List the temporary changes that are onGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/active
listActiveTimedChanges
The runs that are on, ending or stuck on the server, with their change's name. Empty when none is on. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 TimedChangeActiveListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
List the saved files of a server's temporary changesGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/files
listTimedChangeFiles
The server's saved file library: each distinct file its temporary changes use, named by its fingerprint and size, with the changes that use it, whether the server's host holds it, and the figure under the list (what the server keeps against what it may keep). The files are on the server's host and nowhere else; RustSC keeps only this list. A change that names a file already in the list needs no upload for it. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 TimedChangeFileListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Check a temporary change before saving itPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/plan
previewTimedChange
Runs every check that saving runs and answers what saving would do: what each item does, the heavy effects in one sentence, the next start times, the overlaps with other changes and what the server would keep. Nothing is saved or sent. pass changeId in the body to leave out the change being edited. Needs schedules.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body TimedChangePreviewBody
changeId(string): The change being edited, as the API returned its ID.end(TimedChangeEndBody)files(string): `folder` or left out, as on a save.items(list of TimedChangeItemBody)messages(TimedChangeMessagesBody)name(string)start(TimedChangeStartBody)timeZone(string)
Success: 200 TimedChangePreviewResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
List the starting points for a temporary changeGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/starting-points
listTimedChangeStartingPoints
Two examples to edit: a PvP purge before the wipe and a daily plugin rotation. They are not saved, schedule nothing and leave empty what the member chooses (the time, the schedule, the files). Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Success: 200 TimedChangeStartingPointListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Delete a temporary changeDELETE /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}
deleteTimedChange
Deletes the change, its files list and its history for good, and tells the server's host to end it if it is on and to release its saved files. Nothing deletes a temporary change by itself: only this call does. With the query deleteFiles=true, a change that reads its folder also has its folder and everything in it removed from the host; otherwise the folder stays where it is. Needs schedules.manage, servers.files.write and, when an item touches the plugin folders, plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
- deleteFiles (query)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Read a temporary changeGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}
getTimedChange
The change at its current revision, with its overlaps; the ETag carries the revision. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
Success: 200 TimedChangeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change a temporary changePUT /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}
updateTimedChange
Send the revision you read in If-Match. A change already running keeps its original settings. The new settings take effect at the next start. Needs schedules.manage, servers.files.write and, for plugin folders in either version, plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body TimedChangeRequestBody
enabled(boolean): On a save: false keeps the change paused.end(TimedChangeEndBody)files(string): `folder` for a change whose files are the ones in its visible folder on the server's host at every start (it then has no items); left out for a change that names its files in `i...items(list of TimedChangeItemBody)messages(TimedChangeMessagesBody)name(string)start(TimedChangeStartBody)timeZone(string): The member's IANA time zone, for example `Europe/London`.
Success: 200 TimedChangeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Copy a temporary change that reads its folder to another serverPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/actions/copy-folder
copyTimedChangeFolder
Makes a new paused change on targetServerId with a manual start and end, and starts the copy of the folder: a server of the same host is copied inside the host, a server of another host is sent through RustSC in transit (transferId is then set; follow with copyTimedChangeFolderReceive when the send has finished). Needs schedules.manage on both servers and servers.files.write.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
Request body CopyTimedChangeFolderBody
admission(AdmissionBody)name(string): The copy's name; left out, the name of the original and " copy".targetServerId(string)
Success: 202 TimedChangeCopyResponse. Errors use Problem.
Response statuses: 202, 401, 403, 404, 409, 422, default.
Duplicate a temporary changePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/actions/duplicate
duplicateTimedChange
Makes a new change with the same files and settings (the files are shared, so nothing is uploaded again). It starts paused: it has the same times as the original, so switching it on is a choice. Needs schedules.manage, servers.files.write and, for the plugin folders, plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body DuplicateTimedChangeBody
name(string): The new name; left out, "`name` copy".
Success: 201 TimedChangeResponse. Errors use Problem.
Response statuses: 201, 401, 403, 404, 409, 422, default.
End a temporary change nowPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/actions/end
endTimedChange
Ends a running change by restoring the earlier files. If it returns not_on, the change is already off. Needs schedules.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body TimedChangeActionBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Extend a temporary changePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/actions/extend
extendTimedChange
Moves the end of the run that is on later by addMinutes (1 to 10080), for a change that ends after a time, at a time of day or on a date; up to 7 days in all. Returns the operation. 409 state_conflict not_on or cannot_extend (an end at a wipe, at a restart or when you press End). Needs schedules.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ExtendTimedChangeBody
addMinutes(integer): How many minutes later the end comes, 1 to 10080 (7 days).admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Create, fill or list-write a temporary change's folderPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/actions/folder
workOnTimedChangeFolder
Runs one operation on the server's host inside RustSC's folder: action create makes the schedule's folder (it never overwrites a file), action lists replaces the three text lists (lists is required), action export copies the files a change keeps as saved copies into its folder and reads every copy back (the result says verified). Returns the operation. capability_unavailable host_needs_update for a host that does not read folders. Needs schedules.manage and servers.files.write.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body TimedChangeFolderWorkBody
action(string): `create`, `lists` or `export`.admission(AdmissionBody)lists(TimedChangeFolderListsBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Keep a temporary change on anywayPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/actions/keep-on
keepTimedChangeOn
Restarts a change when its last run shows canKeepOn. If plugin status remains unknown, the change stays in place. If a plugin fails to load, the earlier files are restored. If the host is offline, retry later or use admission.ifOffline. Needs schedules.manage, servers.files.write and, for plugin folders, plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body TimedChangeActionBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Pause a temporary changePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/actions/pause
pauseTimedChange
Stops future starts and keeps everything saved; a run that is on still ends. Sends a new revision to the server's host. Repeating it changes nothing. Needs schedules.manage, servers.files.write and, for the plugin folders, plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Success: 200 TimedChangeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Receive a copied folder on the target hostPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/actions/receive-folder
receiveTimedChangeFolder
For the new change on the target server: names the finished send (sendOperationId), whose result holds the archive's fingerprint and size, and starts the receive on the target host. 409 state_conflict send_not_done until the send has succeeded. Needs schedules.manage and servers.files.write.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body ReceiveTimedChangeFolderBody
admission(AdmissionBody)sendOperationId(string)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Refresh the files of a temporary change that reads its folderPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/actions/rescan
rescanTimedChangeFolder
Asks the server's host to look at the schedule's folder again and send its files report. Read only: nothing is written. Returns the operation; read the folder again when it has succeeded. 409 state_conflict refreshed_just_now when the newest report is under 10 seconds old (nothing is started), not_folder for a change that keeps saved copies; capability_unavailable host_needs_update for a host that does not read folders. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body TimedChangeActionBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Resume a temporary changePOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/actions/resume
resumeTimedChange
Sends a new revision to the server's host. Repeating it changes nothing. Needs schedules.manage, servers.files.write and, for the plugin folders, plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Success: 200 TimedChangeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Run a finished temporary change againPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/actions/run-again
runTimedChangeAgain
For a change that starts once: saves a new revision with a new start (and, for a change that ends on a date, a new end) and switches it on, so it moves to upcoming. The files stay saved, so nothing is uploaded again. 409 state_conflict not_once_only for any other change; 422 when the new date has passed. Needs schedules.manage, servers.files.write and, for the plugin folders, plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body RunTimedChangeAgainBody
at(string): The new start, a local date and time such as `2026-11-12T18:00`.endAt(string): For a change that ends on a date: the new end.
Success: 200 TimedChangeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Start a temporary change nowPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/actions/start
startTimedChange
Starts the saved change at once, as its start would: the server's host puts the files in place and reloads the plugins that changed. Returns the operation. 409 state_conflict paused, already_on or not_ready when it cannot start; capability_unavailable when the host is offline unless admission.ifOffline holds it for later. Needs schedules.manage, servers.files.write and, for the plugin folders, plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body TimedChangeActionBody
admission(AdmissionBody)
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Update a plugin a temporary change placesPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/actions/update-plugin
updateTimedChangePlugin
Uses a newer release of the library plugin for the next run. If the change is running, wait until it ends (409 used_by_schedule). If destination returns not_kept, choose a destination using a library plugin. Needs schedules.manage, servers.files.write and plugins.manage.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body UpdateKeptPluginBody
admission(AdmissionBody)destination(string): The destination of the item that places the plugin, as the change names it, for example `carbon/plugins/Caravan.cs`.
Success: 202 OperationResponse. Errors use Problem.
Response statuses: 202, 400, 401, 403, 404, 409, 422, default.
Save a temporary change as one that reads its folderPOST /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/actions/use-folder
useTimedChangeFolder
Saves the next revision with files folder and no items, only when exportOperationId is the finished export of this change at expectedRevision and its result says verified. 409 state_conflict not_verified otherwise, already_folder when it reads its folder already. Needs schedules.manage and servers.files.write.
Workspace permission: schedules.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
Request body UseTimedChangeFolderBody
expectedRevision(integer): The revision the member read.exportOperationId(string): The operation ID of the finished export of this change at that revision; the save is refused unless its result says verified.
Success: 200 TimedChangeResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read what a temporary change didGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/activations
listTimedChangeActivations
The latest 50 runs, newest first: when each started and ended, how it ended (on time, early, extended, by the failsafe, late, undone) and starts that were skipped with the reason. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
Success: 200 TimedChangeRunListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read the visible folder of a temporary changeGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/folder
getTimedChangeFolder
What the server's host last reported about the change's visible folder, the files it will use at its next start: each file's path, size, last change and state (will_be_used, in_use, changed, new, removed, not_used or blocked), the three text lists, the folder's path, the not-ready reason and when the host looked. Names, sizes, times and states only, never contents. reported is false until the host has sent a look, usesFolder is false for a change that keeps saved copies. Needs servers.setup.read.
Workspace permission: servers.setup.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
Success: 200 TimedChangeFolderResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Read the next start times of a temporary changeGET /api/v1/workspaces/{workspaceId}/servers/{serverId}/timed-changes/{changeId}/next-times
listTimedChangeNextTimes
The next five starts, each with the wipe or restart it is counted from and when it ends where that is known. Empty with a reason for a paused change, a manual one, one whose wipe or restart schedule is not on, and a once-only change that has run. Needs servers.read.
Workspace permission: servers.read
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
- changeId (path, required)
- See the downloadable contract for the field schema.
Success: 200 TimedChangeNextTimesResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Settings profiles
List the settings profilesGET /api/v1/workspaces/{workspaceId}/setting-profiles
listSettingProfiles
The workspace's profiles by name. A profile is a named set of settings to copy to servers; saving one changes no server.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 SettingProfileListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save a settings profilePOST /api/v1/workspaces/{workspaceId}/setting-profiles
createSettingProfile
Saves a name and the fields to copy. Only settings that mean the same on every server are accepted; a refused field is a 422 on /fields/<name> (managed_by_launch_plan, managed_by_world, secret_not_allowed, unknown_field, not_shareable, or the value rule it broke). Needs profiles.manage.
Workspace permission: profiles.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body SettingProfileBody
fields(object): Console variable to value, in the shapes the configuration route uses.name(string): What the member calls the profile, for example `Hardcore rates`.
Success: 201 SettingProfileResponse. Errors use Problem.
Response statuses: 201, 400, 401, 403, 404, 409, 422, default.
Delete a settings profileDELETE /api/v1/workspaces/{workspaceId}/setting-profiles/{profileId}
deleteSettingProfile
Deletes the profile and its overrides. No server is changed. Needs profiles.manage.
Workspace permission: profiles.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- profileId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 412, 422, 428, default.
Read a settings profileGET /api/v1/workspaces/{workspaceId}/setting-profiles/{profileId}
getSettingProfile
One profile with its fields and the servers that keep their own value for some of them.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- profileId (path, required)
- See the downloadable contract for the field schema.
Success: 200 SettingProfileResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Change a settings profilePUT /api/v1/workspaces/{workspaceId}/setting-profiles/{profileId}
updateSettingProfile
Replaces the name and fields as the next revision. Needs profiles.manage.
Workspace permission: profiles.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- profileId (path, required)
- See the downloadable contract for the field schema.
- If-Match (header, required)
- The ETag you read, for example "r3". A stale revision is 412 revision_conflict and changes nothing.
Request body SettingProfileBody
fields(object): Console variable to value, in the shapes the configuration route uses.name(string): What the member calls the profile, for example `Hardcore rates`.
Success: 200 SettingProfileResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 412, 422, 428, default.
Let a server keep its own valuePUT /api/v1/workspaces/{workspaceId}/setting-profiles/{profileId}/overrides/{serverId}
setProfileOverrides
Names the profile fields this server keeps its own value for; applying the profile leaves them alone until the override is removed. An empty list removes the server's overrides. Needs profiles.manage.
Workspace permission: profiles.manage
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- profileId (path, required)
- See the downloadable contract for the field schema.
- serverId (path, required)
- See the downloadable contract for the field schema.
Request body ProfileOverridesBody
fields(list of string): Console variables of the profile; an empty list removes the server's overrides.
Success: 200 SettingProfileResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Temporary access
List temporary accessGET /api/v1/workspaces/{workspaceId}/temporary-access
listTemporaryAccess
The groups and permissions players have for a set time, soonest end first (state ended: newest end first), 100 to a page (pass nextCursor as cursor). Filter by steamId, serverId and state: active (adding, active or ending), attention (could not add or could not take away) or ended (ended or kept). Lists the servers where you hold players.read.sensitive; servers names the servers where you may give temporary access now.
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- steamId (query)
- See the downloadable contract for the field schema.
- serverId (query)
- See the downloadable contract for the field schema.
- state (query)
- See the downloadable contract for the field schema.
- cursor (query)
- See the downloadable contract for the field schema.
Success: 200 TemporaryAccessListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Give temporary accessPOST /api/v1/workspaces/{workspaceId}/temporary-access
giveTemporaryAccess
Gives a player groups and permissions (1 to 10) for a set time on the servers named, or on every server that offers it now (allServers). Name a saved pack instead of the groups, permissions and length to give what it holds for its usual length (a length or endsAt replaces the usual one). Choose length ({ amount, unit: minutes, hours or days }) or endsAt: 1 minute to 366 days from now. Something the player already has for a time gets the time added instead (a length adds to the time left; endsAt moves the end to the later one). It is added at once and taken away at the end; if the player already had it, the end takes nothing away. Staff groups, permissions that run the server and the permissions only the workspace Owner gives are refused (staff_not_allowed, owner_only). A reference is used once: giving again with it answers what it gave first (change already_given) and gives nothing more. With preview true nothing is given. Needs players.permissions.temporary on every server named.
Workspace permission: players.permissions.temporary
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header)
- Recommended. A new key per creation; repeat it only to repeat the same request after a lost response.
Request body GiveTemporaryAccessBody
allServers(boolean): True for every server that offers it now and where you may give it.endsAt(string): When it ends.groups(list of string): The groups to give, such as vip.length(TemporaryLengthBody)note(string): A note for your team, at most 200 characters.pack(string): The name of a saved pack to give instead of groups, permissions and length.permissions(list of string): Single permissions to give, such as plugin.use.playerName(string): The player's name as you know it, kept for the list (at most 32 characters).preview(boolean): True to see what would happen without giving anything.reference(string): An order number or note from your store, at most 100 characters.serverIds(list of string): The servers (`srv_...`).steamId(string): The player's 17 digit Steam ID.
Success: 200 GiveTemporaryAccessResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
End what an order reference gavePOST /api/v1/workspaces/{workspaceId}/temporary-access/actions/end-by-reference
endTemporaryAccessByReference
An order that added time to something the player already had takes off only its own time; something with no time left ends now. Using the same reference again changes nothing. Needs players.permissions.temporary on every server it was given on.
Workspace permission: players.permissions.temporary
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body EndTemporaryAccessByReferenceBody
reference(string): The order reference used when it was given or when time was added with it.
Success: 200 TemporaryAccessEntriesResponse. Errors use Problem.
Response statuses: 200, 400, 401, 403, 404, 409, 422, default.
List temporary access packsGET /api/v1/workspaces/{workspaceId}/temporary-access/packs
listTemporaryAccessPacks
The packs saved for the workspace by name: each has groups, permissions and a usual length. Needs players.permissions.temporary on one of the workspace's servers.
Workspace permission: players.permissions.temporary
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 TemporaryAccessPackListResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Delete a temporary access packDELETE /api/v1/workspaces/{workspaceId}/temporary-access/packs/{name}
deleteTemporaryAccessPack
Deletes the pack. Access already given with it stays and ends as planned. Needs players.permissions.temporary on one of the workspace's servers.
Workspace permission: players.permissions.temporary
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- name (path, required)
- See the downloadable contract for the field schema.
Success: 204. Errors use Problem.
Response statuses: 204, 401, 403, 404, 409, 422, default.
Save a temporary access packPUT /api/v1/workspaces/{workspaceId}/temporary-access/packs/{name}
saveTemporaryAccessPack
Saves a pack under the name in the route (at most 40 characters; a pack with that name is replaced): 1 to 10 groups and permissions and a usual length. It gives nobody anything. Staff groups, permissions that run the server and owner-only permissions are refused. At most 50 packs. Needs players.permissions.temporary on one of the workspace's servers.
Workspace permission: players.permissions.temporary
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- name (path, required)
- See the downloadable contract for the field schema.
Request body SaveTemporaryAccessPackBody
groups(list of string): The groups the pack gives, such as vip.length(TemporaryLengthBody)permissions(list of string): Single permissions the pack gives, such as plugin.use.
Success: 200 TemporaryAccessPackResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Read temporary access settingsGET /api/v1/workspaces/{workspaceId}/temporary-access/settings
getTemporaryAccessSettings
The workspace's temporary access settings. endNotice is off until it is saved on. Needs players.permissions.temporary on one of the workspace's servers.
Workspace permission: players.permissions.temporary
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Success: 200 TemporaryAccessSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, default.
Save temporary access settingsPUT /api/v1/workspaces/{workspaceId}/temporary-access/settings
setTemporaryAccessSettings
Switches the end notice on or off. On, a player who linked their Discord account is told a day before their temporary access ends and when it has ended, for access that is running now and access given later. Off, nobody is told. Needs players.permissions.temporary on one of the workspace's servers.
Workspace permission: players.permissions.temporary
- workspaceId (path, required)
- See the downloadable contract for the field schema.
Request body SetTemporaryAccessSettingsBody
endNotice(boolean): True to tell the player on Discord a day before the end and at the end, if they linked their Discord account.
Success: 200 TemporaryAccessSettingsResponse. Errors use Problem.
Response statuses: 200, 401, 403, 404, 409, 422, default.
Add time to temporary accessPOST /api/v1/workspaces/{workspaceId}/temporary-access/{entryId}/actions/add-time
addTemporaryAccessTime
Adds time: a length is added to the time left, endsAt moves the end to the later one; at most 366 days from now. An entry that could not be added is tried again. Needs players.permissions.temporary on its server.
Workspace permission: players.permissions.temporary
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- entryId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Request body TemporaryAccessTimeBody
endsAt(string): A later end.length(TemporaryLengthBody)
Success: 200 TemporaryAccessEntryResponse. Errors use Problem.
Response statuses: 200, 400, 401, 403, 404, 409, 422, default.
Apply temporary access againPOST /api/v1/workspaces/{workspaceId}/temporary-access/{entryId}/actions/apply-again
applyTemporaryAccessAgain
Tries again what did not work (could not add, could not take away), or puts an active one back on the server. Needs players.permissions.temporary on its server.
Workspace permission: players.permissions.temporary
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- entryId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Success: 200 TemporaryAccessEntryResponse. Errors use Problem.
Response statuses: 200, 400, 401, 403, 404, 409, 422, default.
End temporary access nowPOST /api/v1/workspaces/{workspaceId}/temporary-access/{entryId}/actions/end
endTemporaryAccess
Ends it now: what was given is taken away (nothing, if the player had it before). Needs players.permissions.temporary on its server.
Workspace permission: players.permissions.temporary
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- entryId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Success: 200 TemporaryAccessEntryResponse. Errors use Problem.
Response statuses: 200, 400, 401, 403, 404, 409, 422, default.
Keep temporary accessPOST /api/v1/workspaces/{workspaceId}/temporary-access/{entryId}/actions/keep
keepTemporaryAccess
Stops the end: the player keeps it. Needs players.permissions.temporary on its server.
Workspace permission: players.permissions.temporary
- workspaceId (path, required)
- See the downloadable contract for the field schema.
- entryId (path, required)
- See the downloadable contract for the field schema.
- Idempotency-Key (header, required)
- Required. A new key, for example a UUID, per action; repeat it only to repeat the same request after a lost response, so the action runs once.
Success: 200 TemporaryAccessEntryResponse. Errors use Problem.
Response statuses: 200, 400, 401, 403, 404, 409, 422, default.