Site administration API

GET /api/v1/site is public and returns siteName, accentColor, hasLogo, demoEnabled, and cliDownloadUrl (the rdesk CLI download link, or null). GET /site/logo returns the current PNG, JPEG, or WebP logo with a five-minute public cache header, or 404 when absent. Neither route discloses access rules or credentials.

All /api/v1/admin routes require a signed-in instance owner. An organization owner is not automatically an instance owner. These routes do not accept API tokens.

Method and path suffix under /api/v1/admin	Success	Purpose
GET /site	200 JSON	Effective settings, locks, allowed users, and read-only URLs
PATCH /site	200 JSON	Update optional site settings
PUT /site/logo	200 JSON	Upload raw image bytes; returns { "hasLogo": true }
DELETE /site/logo	204	Remove logo
POST /allowed-users	201 JSON	Add { "login": "github-name" }
DELETE /allowed-users/:login	204	Remove a runtime allowed login
GET /storage	200 JSON	Storage type and redacted configuration
POST /storage/test	200 JSON	Test an S3 configuration; returns { "ok": true }
PUT /storage	200 JSON	Save S3 configuration
DELETE /storage	200 JSON	Clear saved storage configuration
GET /mail	200 JSON	Mail transport and redacted configuration
POST /mail/test	200 JSON	Test SMTP settings; returns { "ok": true }
PUT /mail	200 JSON	Save SMTP settings
DELETE /mail	200 JSON	Clear saved mail configuration
GET /owners	200 JSON	{ "items": [...] } of instance owners
POST /owners	201 JSON	Grant ownership by { "githubLogin": "name" }
DELETE /owners/:userId	204	Revoke ownership

PATCH /site accepts any subset of branding (siteName, accentColor), public-page (landingEnabled, rootPath, footerLinks, showTesterSignInLink, cliDownloadUrl), access (allowedOrgs, orgCreation), and limit (maxUploadMb, statsRetentionDays, retainReleasesPerChannel, maxTestersPerOrg) fields. See the response's locked mapping for settings pinned by environment variables. values contains resolved settings, while readOnly contains baseUrl and trustedOrigins.

The logo body must be a nonempty PNG, JPEG, or WebP image of at most 512 KiB. Send bytes directly, not multipart form data.

S3 input requires bucket, accessKeyId, and optionally endpoint, region and secretAccessKey. SMTP input requires host, from, and optionally port, secure, user, and password. Omit an existing secret to retain it. Responses use hasSecret or hasPassword; they never return the secret. Saving credentials requires RD_MASTER_KEY. An environment-pinned storage or mail transport takes precedence over saved settings. Use the corresponding /test route to validate credentials before saving.

For organization mail status and templates, see Email.