Everything the dashboard does goes through a JSON API under /api, and you can call it too. Anything you can click has an endpoint, and curl can call it.
Conventions
The dashboard is just a client of this API, so anything you can click has an endpoint. It is not versioned.
One handler serves the API, the webhook, and the dashboard.
JSON, camelCase. IDs are 12-character lowercase base32 strings. Times are RFC 3339 UTC. A 204 has no body.
Errors are {"error": "message"} with a real status. Unexpected failures are logged and reported as a generic 500 internal error.
Authentication is the shed_session cookie. Auth, setup, the webhook, and the OAuth endpoints under /oauth and /.well-known are public; everything else answers 401 without a session. /mcp takes only a bearer token, never the cookie; see MCP. Unknown /api/* paths are a JSON 404, not the dashboard.
Paging. Deployment and backup lists come a page at a time, newest first: limit (default 10, at most 100) and before, the id of the last record of the previous page. Each page has next, the before of the following page, or null on the last. A before that isn't in the list returns an empty page.
Mutations from a browser must come from the origin of server.url, and POST, PUT, and PATCH need Content-Type: application/json even with an empty body. See request protections.
Status
Meaning
400
Invalid input, or a request the target can't satisfy, such as a backup of a service with no volumes.
401
No session, or the user is no longer on allowed_users.
403
untrusted request origin.
404
Unknown route or id.
409
Conflict: a name in use, a service busy with a backup or restore, fenced, stopped, or being deleted, or a missing 1Password item.
413 / 415
Webhook body too large, or a mutation without a JSON content type.
429
The webhook guard is full, or too many client registrations from one address.
502 / 503
GitHub failed on repos and branches, 1Password failed, or shed is shutting down.
Streams
Build logs, runtime logs, and shed's own log are server-sent events. Each frame is event: log with one line per data:, event: status when a deployment's status changes (data {"status":"…"}), and event: end when there's nothing more. An idle stream sends a : ping comment every 15 seconds. Reconnecting clients get history replayed. Runtime log lines start with the container's RFC 3339 timestamp and a space.
The API has no tokens. You authenticate with the shed_session cookie, so the simplest way to script it is to sign in with your browser and copy that cookie's value. It is HttpOnly, so page scripts can't read it; find it in your browser's developer tools under Application, Cookies. It is valid for 30 days.
POST, PUT, and PATCH need Content-Type: application/json, even with no body. curl sends no Origin header, so the origin check passes and the cookie is what authorizes the call. A browser-based client must instead run on the origin of server.url.
Placeholders like {id} are ids. POST endpoints that start work answer 202 with the new row.
Session and setup
Method
Path
Body
Response
Notes
GET
/api/me
User
GET
/api/auth/login?next=
302 to GitHub
Public. Sets the state cookie. next, a path on this server, is where sign-in ends.
GET
/api/auth/callback
302 to next or /
Public. Sets shed_session.
POST
/api/auth/logout
204
Public route, origin and JSON checks apply.
GET
/api/setup
Setup
Public.
GET
/api/setup/github?token=
HTML form
Public. Auto-submits the app manifest.
GET
/api/setup/github/callback?code=&state=
302 to GitHub
Public.
POST
/api/setup/github/import
ImportApp
Setup
Public, setup token required.
Projects and services
Method
Path
Body
Response
Notes
GET
/api/projects
Project[]
POST
/api/projects
{name}
Project
GET
/api/projects/{id}
ProjectDetail
PATCH
/api/projects/{id}
{name}
Project
DELETE
/api/projects/{id}
204
Tears down everything.
POST
/api/projects/{id}/services
NewService
Service
Creates the service and runs its first deploy.
GET
/api/services/{id}
Service
PATCH
/api/services/{id}
ServicePatch
Service
DELETE
/api/services/{id}
204
Containers, volumes, and images.
POST
/api/services/{id}/stop
Service
Cancels deploys, stops the container, removes routes.
POST
/api/services/{id}/start
Service
409 if never deployed or fenced.
POST
/api/services/{id}/restart
Service
409 if stopped, never deployed, or fenced.
POST
/api/services/{id}/restore-fence/clear
Service
Keeps the current data. 409 while held.
GET
/api/services/{id}/variables
Record<string,string>
From the 1Password item when connected. 409 if it is missing; 502 if 1Password fails.
PUT
/api/services/{id}/variables
Record<string,string>
Record<string,string>
Replaces all variables. Writes the 1Password item when connected, creating it if missing.
GET
/api/services/{id}/variables/resolved
Record<string,string>
References expanded, injected variables included. 409 if a needed 1Password item is missing.
POST
/api/services/{id}/domains
{host?}
Domain
No host generates one.
DELETE
/api/domains/{id}
204
POST
/api/services/{id}/volumes
{mountPath}
Volume
DELETE
/api/volumes/{id}
204
Removes the data.
Deployments, logs, and metrics
Method
Path
Body
Response
Notes
GET
/api/services/{id}/deployments?before=&limit=
DeploymentPage
Newest first, paged. limit default 10, at most 100.
POST
/api/services/{id}/deployments
Deployment
Deploys the branch head or image. 409 if fenced.
GET
/api/deployments/{id}
Deployment
POST
/api/deployments/{id}/redeploy
Deployment
Reuses the image, so it is a rollback. 409 if fenced.
POST
/api/deployments/{id}/cancel
Deployment
GET
/api/deployments/{id}/logs
SSE
Replays the build log, follows while building.
GET
/api/services/{id}/logs
SSE
Runtime logs: last 500 lines, then follow.
GET
/api/services/{id}/metrics?range=
Metrics
range is 1h, 6h, 24h, or 7d. Default 1h.
GET
/api/host/metrics?range=
HostMetrics
Same ranges.
GET
/api/logs
SSE
shed's own log: last 1000 lines, then follow.
Backups
Method
Path
Body
Response
Notes
GET
/api/services/{id}/backups?before=&limit=
ServiceBackups
Newest first, paged. limit default 10, at most 100.
PUT
/api/services/{id}/backups/policy
BackupPolicyInput
BackupPolicy
POST
/api/services/{id}/backups
202, Backup
Run now. 409 if one is queued, running, or uploading. 400 without volumes or a deployment.
GET
/api/backups/system?before=&limit=
SystemBackups
Newest first, paged like service backups.
PUT
/api/backups/system/policy
BackupPolicyInput
BackupPolicy
POST
/api/backups/system
202, Backup
GET
/api/backups/{id}/download
archive
Decrypted, still zstd-compressed. Content-Disposition names it.
POST
/api/backups/{id}/restore
202, Restore
409 if busy or fenced. 400 for shed.db, unsuccessful, or vanished backups.
DELETE
/api/backups/{id}
204
Local file and S3 object. 409 while active or being restored.
GET
/api/backups/settings
BackupSettings
Never includes the S3 secret.
PUT
/api/backups/settings
BackupSettingsInput
BackupSettings
POST
/api/backups/settings/test
BackupSettingsInput
204
400 with the S3 error. A blank secret uses the stored one.
GET
/api/backups/settings/key
{ identity }
The age secret key. 404 if none.
Notifications
Method
Path
Body
Response
Notes
GET
/api/notifications/providers
string[]
Provider names.
GET
/api/notifications/channels
NotificationChannel[]
Never includes the target.
POST
/api/notifications/channels
NotificationChannelInput
201, NotificationChannel
400 if the name is empty, the provider unknown, or the target rejected.
PATCH
/api/notifications/channels/{id}
NotificationChannelPatch
NotificationChannel
An empty or absent target keeps the stored one.
DELETE
/api/notifications/channels/{id}
204
Also deletes its deliveries.
POST
/api/notifications/channels/{id}/test
204
Sends now, even if disabled. 400 with the failure.
GET
/api/notifications/rules
NotificationRule[]
The rule catalog with overrides applied.
PATCH
/api/notifications/rules/{id}
NotificationRulePatch
NotificationRule
404 if unknown. 400 for a threshold or duration the rule does not allow. 502 if Grafana can't apply a metric rule; the value is still saved.
GET
/api/notifications/deliveries?limit=
NotificationDelivery[]
Newest first. Default 50, max 200.
GitHub
Method
Path
Body
Response
Notes
GET
/api/github/repos
Repo[]
GET
/api/github/repos/{owner}/{repo}/branches
string[]
POST
/api/github/webhook
202
Public. HMAC-signed by GitHub.
1Password
Method
Path
Body
Response
Notes
GET
/api/onepassword
OnePassword
POST
/api/onepassword/vaults
{token}
OnePasswordVault[]
Vaults the token can access, by name. 400 if 1Password rejects the token.
PUT
/api/onepassword
{token, vault?}
OnePassword
Connects to vault (an ID), or the token's only vault: creates the items and moves variables out of shed.db. 400 if 1Password rejects the token or there is no such vault; 502 if it fails.
DELETE
/api/onepassword
OnePassword
Disconnects: copies variables back into shed.db. 502 if 1Password fails, and nothing changes.
Updates
Method
Path
Body
Response
Notes
GET
/api/update
UpdateStatus
POST
/api/update/check
UpdateStatus
Checks GitHub now. 409 if unsupported or busy.
POST
/api/update/download
202 UpdateStatus
409 if unsupported, no newer release, or busy.
PUT
/api/update/settings
{autoDownload?, channel?}
UpdateStatus
At least one. channel is "stable" or "nightly".
POST
/api/update/install
202 UpdateStatus
Then shed restarts. 409 if nothing is downloaded or busy.
Newest first. limit default 100, at most 500. actor is a login or kind; action an action or its dotted prefix.
GET
/api/audit/settings
AuditSettings
PUT
/api/audit/settings
AuditSettings
AuditSettings
400 unless 1 to 3650 days.
Telemetry
Method
Path
Body
Response
Notes
GET
/api/telemetry
Telemetry
PUT
/api/telemetry
TelemetrySettings
Telemetry
Turns telemetry on or off and sets retention and caps. 400 out of bounds. The stack follows in the background.
POST
/api/telemetry/components/{name}/restart
Telemetry
name is metrics, logs, traces, or grafana. 409 while telemetry is off, 404 for another name.
DELETE
/api/telemetry/data
204
Removes the containers, volumes, and stored data. 409 while telemetry is on.
GET
/grafana/*, other methods
Grafana
Reverse-proxied as the signed-in user. Signed-out page loads go to sign-in; other requests get 401. Redirects to /server/telemetry while telemetry is off.
Agents (OAuth and MCP)
Method
Path
Body
Response
Notes
GET
/.well-known/oauth-protected-resource[/mcp]
RFC 9728 metadata
Public, CORS.
GET
/.well-known/oauth-authorization-server
RFC 8414 metadata
Public, CORS.
POST
/oauth/register
RFC 7591 JSON
201 client
Public, CORS. 429 past the per-address limit, 503 past the cap.
GET
/oauth/authorize?…
302 to /authorize or sign-in
Public. 400 HTML page for an invalid request.
GET
/oauth/authorize?request=
302 to /authorize
Resumes a request after sign-in, once. 400 HTML page if expired.
POST
/oauth/token
form
token response
Public, CORS.
POST
/oauth/revoke
form
200
Public, CORS. RFC 7009.
GET
/api/oauth/requests/{id}
OAuthRequest
404 if unknown, expired, decided, or another user's.
POST
/api/oauth/requests/{id}
{approve}
{redirect}
Decides the request once.
GET
/api/oauth/grants
OAuthGrant[]
The signed-in user's, newest first.
DELETE
/api/oauth/grants/{id}
204
Revokes all its tokens.
POST
/mcp
JSON-RPC
JSON-RPC
MCP Streamable HTTP. Bearer token only. GET and DELETE answer 405.
GET /* serves the dashboard with an index.html fallback, so client-side routes survive a reload. Missing assets are 404.
Types
These are the shapes behind the responses above, written as TypeScript types.
Account and setup
type User = { login: string; name: string; avatarUrl: string };
type Setup = { githubConfigured: boolean; appSlug: string; installUrl: string };
type ImportApp = {
token: string;
appId: number;
clientId: string;
clientSecret: string;
webhookSecret: string;
privateKey: string;
};
Projects and services
type ServiceKind = "app" | "postgres" | "mysql" | "mongo" | "redis";
type ServiceStatus = "offline" | "deploying" | "active" | "failed" | "crashed" | "stopped";
type Project = {
id: string; name: string; createdAt: string;
updatedAt: string; // latest of createdAt and its services' and deployments' creation
services: { id: string; name: string; kind: ServiceKind; status: ServiceStatus }[];
};
type ProjectDetail = Omit<Project, "services"> & { services: Service[] };
type Service = {
id: string; projectId: string; name: string; kind: ServiceKind;
repo: string; branch: string; rootDir: string; image: string;
dockerfilePath: string; startCommand: string;
port: number; healthcheckPath: string; publicPort: number;
cpuLimit: number; // cores, 0 = unlimited
memoryLimit: number; // bytes, 0 = unlimited
autoDeploy: boolean; waitForCi: boolean;
status: ServiceStatus;
privateHost: string; // "<name>"
domains: Domain[];
volumes: Volume[];
latestDeployment: Deployment | null;
restoreFence: RestoreFence | null; // set while a restore runs or after one failed
createdAt: string;
};
type RestoreFence = {
restoreId: string;
phase: "retaining" | "replacing" | "loading";
createdAt: string;
};
// Create: kind "app" needs repo+branch or image; database kinds need only name.
type NewService = { name: string; kind: ServiceKind; repo?: string; branch?: string; image?: string };
// Patch: any subset of the editable Service fields (name excluded).
type ServicePatch = Partial<Pick<Service,
"repo" | "branch" | "rootDir" | "image" | "dockerfilePath" | "startCommand" |
"port" | "healthcheckPath" | "publicPort" | "cpuLimit" | "memoryLimit" |
"autoDeploy" | "waitForCi">>;
type Domain = { id: string; host: string; generated: boolean; url: string };
type Volume = { id: string; mountPath: string; createdAt: string };
type Repo = { fullName: string; defaultBranch: string; private: boolean };
// Container resource usage. Sample i is at start + i*step seconds; series
// are the same length, oldest first, null where nothing was running.
type Metrics = {
range: "1h" | "6h" | "24h" | "7d";
start: string; step: number; // step in seconds
cpuLimit: number; // cores, 0 = unlimited
memoryLimit: number; // bytes, 0 = unlimited
cpu: (number | null)[]; // percent of one core (200 = two cores busy)
memory: (number | null)[]; // bytes in use
netRx: (number | null)[]; // bytes/s received
netTx: (number | null)[]; // bytes/s sent
diskRead: (number | null)[]; // bytes/s
diskWrite: (number | null)[]; // bytes/s
};
// Resource usage of the whole host, bucketed like Metrics.
type HostMetrics = {
range: "1h" | "6h" | "24h" | "7d";
start: string; step: number;
cpus: number; // online CPUs
memoryTotal: number; // bytes
diskTotal: number; // bytes, filesystem holding data.dir
cpu: (number | null)[]; // percent of one core (max cpus*100)
memory: (number | null)[]; // bytes in use (total - available)
diskUsed: (number | null)[]; // bytes used on that filesystem
netRx: (number | null)[]; // bytes/s, physical interfaces
netTx: (number | null)[];
diskRead: (number | null)[]; // bytes/s, physical disks
diskWrite: (number | null)[];
};
Backups
type BackupCompression = "fastest" | "default" | "better" | "best";
type BackupPolicy = {
enabled: boolean;
schedule: string; // cron, UTC unless "CRON_TZ=<zone> ..."
compression: BackupCompression;
keepLocal: number; // 0 only with upload; local kept until uploaded
upload: boolean; // ignored while S3 is not configured
keepRemote: number; // >= 1 when upload
nextRunAt: string | null; // null when disabled
};
type BackupPolicyInput = Omit<BackupPolicy, "nextRunAt">;
type BackupStatus = "queued" | "running" | "uploading" | "succeeded" | "failed";
type Backup = {
id: string; serviceId: string | null; // null = shed.db
trigger: "schedule" | "manual" | "pre-restore";
method: "dump" | "volume" | "sqlite";
status: BackupStatus;
fileName: string; // download name, e.g. "postgres-20261004-030000.sql.zst"
size: number; // archive bytes
encrypted: boolean;
local: boolean; remote: boolean;
remoteError: string; error: string;
createdAt: string; finishedAt: string | null;
};
type Restore = {
id: string; serviceId: string; backupId: string;
status: "running" | "succeeded" | "failed"; error: string;
createdAt: string; finishedAt: string | null;
};
// next is the before of the following page, null on the last.
type ServiceBackups = {
policy: BackupPolicy; backups: Backup[]; next: string | null; restore: Restore | null;
};
type SystemBackups = { policy: BackupPolicy; backups: Backup[]; next: string | null };
type S3Settings = {
endpoint: string; // URL, e.g. "https://s3.us-east-1.amazonaws.com"
region: string; bucket: string; prefix: string;
accessKeyId: string; pathStyle: boolean;
hasSecret: boolean;
};
type BackupSettings = {
s3: S3Settings | null;
encryption: { enabled: boolean; recipient: string }; // recipient "" until a key exists
};
// secretAccessKey omitted or "" keeps the stored secret. s3 null removes the destination.
type BackupSettingsInput = {
s3: (Omit<S3Settings, "hasSecret"> & { secretAccessKey?: string }) | null;
encryption: { enabled: boolean };
};
Notifications
type NotificationChannel = {
id: string; name: string;
provider: string; // from GET /api/notifications/providers
enabled: boolean;
createdAt: string;
};
type NotificationChannelInput = { name: string; provider: string; target: string; enabled: boolean };
// provider is fixed. An omitted or empty target keeps the stored one.
type NotificationChannelPatch = { name?: string; target?: string; enabled?: boolean };
type NotificationRule = {
id: string; title: string; description: string;
enabled: boolean;
threshold: number | null; // effective value; null if the rule has none
unit: string; // label of the threshold: "crashes", "%", "s"; "" if none
forSeconds: number | null; // effective duration; null if the rule has none
needsTelemetry: boolean; // reads metrics, so it works only while telemetry is on
available: boolean; // false if it cannot fire now (needs telemetry, which is off)
};
// An omitted field stays as it is. threshold and forSeconds only for rules that have them.
type NotificationRulePatch = { enabled?: boolean; threshold?: number; forSeconds?: number };
type NotificationDelivery = {
id: string; channelId: string; channelName: string;
title: string; body: string;
status: "pending" | "sent" | "failed";
attempts: number; // failed sends so far
lastError: string; // "" if none; never the target
createdAt: string; sentAt: string | null;
};
Updates
type Release = { version: string; url: string; notes: string; publishedAt: string };
type UpdateStatus = {
current: string; // running version, e.g. "v1.3.2" or "dev-v1.3.2-4-gabc1234"
latest: Release | null; // null until a check succeeds
available: boolean; // latest is newer than current
checkedAt: string | null;
state: "idle" | "checking" | "downloading" | "restarting";
staged: string; // verified version ready to install, "" if none
error: string; // last check or download failure, "" if none
autoDownload: boolean;
channel: "stable" | "nightly";
unsupported: string; // why this build can't update itself, "" if it can
};
1Password
// The token is write-only: PUT /api/onepassword takes it.
type OnePassword = {
connected: boolean;
vault: string; // the vault's name, "" when not connected
items: number; // services with an item in the vault
};
// POST /api/onepassword/vaults {token} lists them; PUT takes one's id.
type OnePasswordVault = { id: string; name: string };
Telemetry
type TelemetryCaps = { spansPerSecond: number; logsPerSecond: number; series: number };
type TelemetrySettings = {
enabled: boolean;
metricsRetentionDays: number; // 1 to 3650, default 30
logsRetentionDays: number; // 1 to 3650, default 14
tracesRetentionDays: number; // 1 to 3650, default 14
diskLimitGB: number; // logs + traces, default 20
defaultCaps: TelemetryCaps; // 5000 spans/s, 2000 log records/s, 50000 series
};
type TelemetryComponent = {
name: "metrics" | "logs" | "traces" | "grafana";
state: "running" | "starting" | "stopped" | "failed";
version: string;
error: string; // last failure starting it, "" if none
cpuPercent: number | null;
memoryBytes: number | null;
memoryLimit: number;
diskBytes: number | null; // null for grafana
};
type Telemetry = {
settings: TelemetrySettings;
components: TelemetryComponent[]; // empty while never enabled
ingest: { spans: number; logs: number; points: number }; // per second, last minute
droppedLastHour: { reason: string; signal: string; count: number }[];
firingAlerts: { name: string; serviceId: string; since: string }[];
grafanaUrl: string; // "<server.url>/grafana/"
otlpEndpoint: string; // "http://localhost:4318"
};
Agents
type OAuthRequest = {
id: string;
clientName: string; // self-reported at registration, not verified
clientUri: string; // "" when the client registered none
redirectHost: string; // where the code will be sent
scopes: string[];
};
type OAuthGrant = {
id: string; clientName: string; redirectHost: string; scopes: string[];
createdAt: string; lastUsedAt: string | null; // null until first used
};