Settings & Auth API

Endpoints for application settings, authentication, and system management.

Authentication

Get auth status

GET /api/auth/status

Returns whether a PIN is configured. Does not require authentication.

Response:

{ "requiresPin": true }

---

Login

POST /api/auth/login

Authenticates with a PIN. Does not require a prior auth header.

Request body:

Field	Type	Required	Description
pin	string	yes	The PIN to verify

Response: 200 { token: string } on success, 401 on failure.

Use the returned token as a Bearer token in subsequent API requests and as the ?token= query parameter for WebSocket connections.

---

PIN management

Set PIN

PUT /api/settings/pin

Sets or updates the dashboard PIN. Requires authentication if a PIN is already set.

Request body:

Field	Type	Required	Description
pin	string	yes	New PIN (4-8 characters)

Response: 200 { ok: true, token: string }

---

Remove PIN

DELETE /api/settings/pin

Removes PIN protection from the dashboard.

Response: 200 { ok: true }

---

Settings

Get all settings

GET /api/settings

Returns the full application configuration.

Response:

{
  "dataDir": "/home/user/.claudecontrol/data",
  "runtime": {
    "maxTurns": 12,
    "enableSubagents": true,
    "subagentLimit": 3,
    "model": null,
    "fallbackModel": null
  },
  "gitSync": false,
  "tunnelUrl": null,
  "hasPin": false,
  "claudePath": "/home/user/.local/bin/claude",
  "port": 22609,
  "version": "0.3.43",
  "build": "..."
}

---

Update data directory

PUT /api/settings

Changes the data directory. Agents are reloaded from the new location.

Request body:

Field	Type	Required	Description
dataDir	string	yes	Absolute path to the new data directory

Response: 200 with updated config.

---

Get runtime config

GET /api/settings/runtime

Returns only the runtime configuration values.

Response:

{
  "maxTurns": 12,
  "maxBudgetUsd": null,
  "model": null,
  "fallbackModel": null,
  "enableSubagents": true,
  "subagentLimit": 3,
  "subagentPromptMaxChars": 3000,
  "contextMaxChars": 8000,
  "contextWindowSize": 200000
}

---

Update runtime config

PUT /api/settings/runtime

Updates runtime configuration values. Only provided fields are changed.

Request body (all optional):

Field	Type	Constraints
maxTurns	number	1 -- 100
maxBudgetUsd	number or null	0+, null to remove
model	string	Empty string to clear
fallbackModel	string	Empty string to clear
enableSubagents	boolean	--
subagentLimit	number	0 -- 20
subagentPromptMaxChars	number	500 -- 50000
contextMaxChars	number	1000 -- 100000
contextWindowSize	number	10000 -- 1000000

Response: 200 with the full runtime config after updates.

---

System management

Clean raw logs

POST /api/settings/clean-raw-logs

Deletes all raw SDK message logs from every workspace to free disk space.

Response:

{ "ok": true, "deletedFiles": 42, "freedBytes": 10485760 }

---

Check for updates

GET /api/settings/update-check

Checks npm for a newer version of ClaudeControl.

Response:

{
  "current": "0.3.43",
  "latest": "0.3.44",
  "hasUpdate": true
}

---

Install update

POST /api/settings/update

Installs the latest version from npm and restarts the server. The response is sent immediately before the update starts.

Response: 200 { ok: true, message: "..." }

The server will restart automatically after the update completes.