Settings API

The Settings API stores your workspace preferences: which build mode to use by default, the deploy target and server to pre-select, and a saved git token for cloning private repos. These follow you across devices and sync to Alaf Server Cloud. In the dashboard this is the Settings page; there is no dedicated alaf server CLI command for these values (the CLI's alaf server system settings manages instance-level settings, a different module).

Settings is an org-singleton resource: there is no :id — the routes always act on the settings row for the authenticated user in the current organization (resolved from the X-Organization-Id header or your session default). Available on both self-hosted and cloud instances.

Endpoints

Get settings

Returns the merged view of your preferences. The clone token is never returned — only whether one is stored, when it was set, and whether it's flagged as the default.

GET /api/settings

curl https://your-host/api/settings \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN"

The response includes buildMode, defaultDeployTarget, defaultServerId, a cloneToken object (hasToken, setAt, asDefault), and cloneStrategyPreference.

Upsert settings

Creates the settings row if it doesn't exist, or updates it. Only buildMode is accepted here; use the PATCH routes below for the other fields.

PUT /api/settings

curl -X PUT https://your-host/api/settings \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"buildMode":"server"}'

Update build mode

Sets just the default build mode without touching the other preferences.

PATCH /api/settings/build-mode

curl -X PATCH https://your-host/api/settings/build-mode \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"buildMode":"local"}'

Update deploy defaults

Pre-selects a deploy target (and, for server, which server) in the deploy picker. Pass null to clear. An explicit per-deploy choice always wins over these defaults.

PATCH /api/settings/deploy-defaults

curl -X PATCH https://your-host/api/settings/deploy-defaults \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"defaultDeployTarget":"server","defaultServerId":"srv_123"}'

Update clone credentials

Stores an encrypted git token used to clone private repos, or clears it. The token is encrypted at rest and never returned by any endpoint — the response is the same read-only state as GET /api/settings.

PATCH /api/settings/clone-credentials

# Store a token and use it by default
curl -X PATCH https://your-host/api/settings/clone-credentials \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"token":"ghp_xxx","asDefault":true}'

# Clear the stored token
curl -X PATCH https://your-host/api/settings/clone-credentials \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"token":null}'

Update clone-strategy preference

Records the choice made on the first-time deploy nudge. Once set to anything other than prompt, the nudge stops asking.

PATCH /api/settings/clone-strategy-preference

curl -X PATCH https://your-host/api/settings/clone-strategy-preference \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"preference":"remote-with-token"}'

Errors you might see