Instance settings

These endpoints read and manage instance-wide configuration. Most are instance admin only; a few public projections expose just enough for unauthenticated screens (the login and forgot-password pages) to branch correctly. Secrets — OAuth client credentials — live in the environment and never leave it; these endpoints report only toggles and whether the runtime has credentials.

Email

Email delivery powers invitations and report-to-inbox notifications. It is off by default; turning it on requires a from address (otherwise every send would fail).

Email enabled

GET /api/v1/instance/email-enabled public

Public. Returns only the boolean — never the from address — so the forgot-password screen can choose between offering self-service recovery and telling the user to contact an admin.

{ "enabled": true }

Get email settings

GET /api/v1/instance/email scope: admin

Instance admin only. Returns the full email configuration.

curl

curl "https://<your-instance>/api/v1/instance/email" \
  -H "Authorization: Bearer spantail_pat_yourtoken"

Response

{
  "emailEnabled": true,
  "emailFromAddress": "noreply@example.com",
  "emailFromName": "Spantail"
}

Update email settings

PATCH /api/v1/instance/email scope: admin

Instance admin only. Omitted from* fields keep their current values. Enabling delivery without a from address (current or supplied) returns 400.

Request body

Field	Type	Required	Description
emailEnabled	boolean	yes	Turn delivery on or off.
emailFromAddress	string | null	no	Sender address. Required (current or supplied) when enabling.
emailFromName	string | null	no	Sender display name (≤ 100 chars).

curl -X PATCH "https://<your-instance>/api/v1/instance/email" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{ "emailEnabled": true, "emailFromAddress": "noreply@example.com", "emailFromName": "Spantail" }'

Agents

Whether the AI agent activity feature is on. Off by default because it can grow data volume.

Agents enabled

GET /api/v1/instance/agents-enabled public

Read by any caller to gate the agents UI; reports only the boolean.

{ "enabled": false }

Update agents

PATCH /api/v1/instance/agents scope: admin

Instance admin only. Toggles the feature.

Request body

Field	Type	Required	Description
agentsEnabled	boolean	yes	Turn the AI agent activity feature on or off.

curl

curl -X PATCH "https://<your-instance>/api/v1/instance/agents" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{ "agentsEnabled": true }'

Response

{ "enabled": true }

Realtime updates

Whether realtime SSE updates are on. Off by default because every open stream keeps a per-user Durable Object running, which can exhaust the Workers Free plan’s daily duration quota.

Realtime enabled

GET /api/v1/instance/realtime-enabled public

Read by any caller so clients can decide whether to open the stream; reports only the boolean.

{ "enabled": false }

Update realtime

PATCH /api/v1/instance/realtime scope: admin

Instance admin only. Toggles the feature.

Request body

Field	Type	Required	Description
realtimeEnabled	boolean	yes	Turn realtime SSE updates on or off.

curl

curl -X PATCH "https://<your-instance>/api/v1/instance/realtime" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{ "realtimeEnabled": true }'

Response

{ "enabled": true }

Social login

Google and GitHub sign-in. A provider can only be enabled when its client id and secret are configured in the environment; enabling an unconfigured provider returns 400.

Auth providers

GET /api/v1/instance/auth-providers public

Public. Tells the login screen which social buttons to show. A provider is true only when an admin enabled it and the runtime has its credentials. selfSignupAvailable is true only before the instance is claimed (no users yet), when the login screen offers a one-time sign-up form to bootstrap the first super-admin.

curl

curl "https://<your-instance>/api/v1/instance/auth-providers"

Response

{
  "google": true,
  "github": false,
  "selfSignupAvailable": false
}

Get OAuth settings

GET /api/v1/instance/oauth scope: admin

Instance admin only. Reports each provider’s enabled toggle and whether the runtime has its credentials (configured), plus the Google domain allowlist. Secrets never leave the environment.

curl

curl "https://<your-instance>/api/v1/instance/oauth" \
  -H "Authorization: Bearer spantail_pat_yourtoken"

Response

{
  "google": { "enabled": true, "configured": true },
  "github": { "enabled": false, "configured": false },
  "googleAllowedDomains": ["example.com"]
}

Update OAuth settings

PATCH /api/v1/instance/oauth scope: admin

Instance admin only. Omitted fields keep their current values. Enabling a provider whose credentials are not configured returns 400.

Request body

Field	Type	Required	Description
googleOAuthEnabled	boolean	no	Enable or disable Google sign-in.
githubOAuthEnabled	boolean	no	Enable or disable GitHub sign-in.
googleAllowedDomains	string[]	no	Google Workspace domains whose users may self-join via Google sign-in without an invitation (≤ 100 entries). Empty = invitation required for everyone.

Note

A domain in googleAllowedDomains lets matching Google users self-join (auto-provision) without an invitation. Matching is exact on the part after @; subdomains are not implicitly allowed. Out-of-domain Google users can still join by invitation.

curl -X PATCH "https://<your-instance>/api/v1/instance/oauth" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{ "googleOAuthEnabled": true, "googleAllowedDomains": ["example.com"] }'

Version

Version standing

GET /api/v1/instance/version auth required

Any signed-in member (not just admins). Returns the instance’s running version and whether a newer upstream release exists — the data behind the System page’s update notice. The running version is not secret; auth is required only because this performs an outbound update check, so it is not an open proxy. Best-effort and cached; latest is null when the check fails.

curl

curl "https://<your-instance>/api/v1/instance/version" \
  -H "Authorization: Bearer spantail_pat_yourtoken"

Response

{
  "current": "v0.5.1",
  "latest": "v0.6.0",
  "updateAvailable": true
}