Skip to content

Customer API reference

Operations, request fields and responses for the customer API.

Customer API v1. Select an action to see its inputs and responses. Writes made with a browser session require X-CSRF-Token.

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

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.

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.

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.

Read the groups the permission sync keeps the sameGET /api/v1/workspaces/{workspaceId}/permission-sync/shared

getSharedPermissions

The shared set the Global view shows: each group with how many permissions and members it has, or one group opened (its permissions and its first members) when group is given. Needs players.read.sensitive for the whole workspace.

Workspace permission: players.read.sensitive

workspaceId (path, required)
See the downloadable contract for the field schema.
group (query)
See the downloadable contract for the field schema.

Success: 200 SharedPermissionsResponse. Errors use Problem.

Response statuses: 200, 401, 403, 404, default.

Change the shared groups once for every serverPOST /api/v1/workspaces/{workspaceId}/permission-sync/shared/edits

editSharedPermissions

Nothing is sent from here and nothing is touched on a server that cannot be read. The framework's staff and starting groups are refused, and so is an item that is paused.

workspaceId (path, required)
See the downloadable contract for the field schema.

Request body EditSharedPermissionsBody

  • edits (list of SharedEditBody, 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

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

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.

    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.

    Analytics settings

    Analytics are off.

    Help improve RustSC with page counts and performance measurements. Privacy details