Config API

Manage Claude Code configuration across all scopes. Codex CLI uses a separate TOML-backed config API because its file format and safety rules differ from Claude Code JSON settings.

Endpoints

List Config Files

GET /api/v1/config/files?project_path={path}

Returns all configuration file paths with their existence status.

Get Merged Config

GET /api/v1/config?project_path={path}

Returns the merged configuration from all scopes. This is the effective configuration that Claude Code uses.

Response:

{
  "settings": { ... },
  "mcp_servers": { ... },
  "hooks": { ... },
  "permissions": { ... },
  "commands": [ ... ],
  "agents": [ ... ]
}

Get Raw File Content

GET /api/v1/config/raw?path={file_path}&project_path={path}

Returns the raw content of a specific configuration file.

Get Settings by Scope

GET /api/v1/config/settings/{scope}?project_path={path}

scope: user or project

Get Resolved Config

GET /api/v1/config/resolved?project_path={path}

Returns resolved settings with the effective value and source scope for each key.

Get All Scopes

GET /api/v1/config/scopes?project_path={path}

Returns settings from all scopes (managed, user, project, local) without merging.

Update Settings

PUT /api/v1/config/settings

Request Body:

{
  "scope": "user",
  "settings": { "model": "claude-sonnet-4-6" },
  "project_path": "/path/to/project"
}

Validate Settings

POST /api/v1/config/validate-settings

Validates permission patterns without saving.

Request Body:

{
  "settings": { "permissions": { "allow": ["Bash(npm run *)"] } }
}

Codex Config Endpoints

Get Codex Config Summary

GET /api/v1/codex-config

Returns safe Codex config metadata, file list, summary values, and parse errors. The full parsed TOML config is not returned automatically.

List Codex Config Files

GET /api/v1/codex-config/files

Returns $CODEX_HOME/config.toml, profile config files, and rules files. Auth, history, cache, and log files are not exposed as raw config files.

Get Raw Codex File

GET /api/v1/codex-config/raw?path={file_path}

Returns raw content only for safe files under $CODEX_HOME.

Update Codex Settings

PUT /api/v1/codex-config/settings

Updates whitelisted Codex settings and feature overrides using a TOML writer that preserves formatting where possible. A backup is created before writing and the file is parsed before save.

Supported scalar settings include:

• model
• model_reasoning_effort
• profile
• sandbox_mode
• approval_policy
• search
• strict_config
• no_alt_screen

Feature updates are written under [features]. Boolean values add or update overrides. null removes an explicit override so Codex can fall back to its default.