Skip to main content

Configuration API

The configuration API reads, saves, checks, and validates YAML. Validate and back up production configuration before saving it, then reload and inspect status.

Config Check Endpoints​

GET /api/config​

Purpose:

  • Reads the config file referenced by the current startup options.
  • Returns the raw YAML text, config path, content version, and file update time.
  • Does not expand environment variable placeholders; content matches the file on disk.

Example response:

{
  "ok": true,
  "path": "/etc/oxidns/config.yaml",
  "format": "yaml",
  "content": "plugins:\n  - tag: forward\n    type: forward\n",
  "version": "sha256-hex",
  "updated_at_ms": 1760000000000
}

PUT /api/config​

Purpose:

  • Saves the full YAML config file.
  • Runs the same validation as POST /api/config/validate before writing by default.
  • Can request an application-level reload after a successful save.
  • Writes the original request text, not the expanded values of ${VAR} placeholders.

Request body:

{
  "format": "yaml",
  "content": "plugins:\n  - tag: debug_main\n    type: debug_print\n",
  "base_version": "sha256-hex",
  "validate": true,
  "reload": false
}

Responses:

  • 200 OK
    • The config was saved. The response includes the new version, plugin count, and init order.
  • 400 Bad Request
    • The YAML cannot be parsed, validation failed, or format is not yaml.
  • 409 Conflict
    • base_version does not match the current file version, or a reload was requested while another reload is already running.

GET /api/config/check​

Purpose:

  • Validates the config file at the current config path.
  • Expands environment variable placeholders in memory for validation, without modifying the file on disk.

Good fit:

  • Check whether the on-disk config parses correctly and passes plugin dependency validation.

POST /api/config/validate​

Purpose:

  • Validates YAML config text sent directly in the request body.
  • Also accepts the JSON envelope used by PUT /api/config.
  • Expands environment variable placeholders in memory for validation, without returning or saving expanded config text.

Request body requirements:

  • Non-empty UTF-8 YAML text; or
  • JSON: {"format":"yaml","content":"...yaml..."}

Good fit:

  • Validate a config in the control plane before writing it to disk.