Configuration API

Configuration API

Three endpoints are available under /api/configuration/. They manage compilation configuration defaults, validation, and layer resolution.

---

GET /api/configuration/defaults

Returns the system defaults and hard limits for all compilations. No authentication required (anonymous tier).

Request

GET /api/configuration/defaults

Response

{
  "success": true,
  "defaults": {
    "compilation": { ... },
    "validation": { ... }
  },
  "limits": {
    "maxSources": 20,
    "maxExclusions": 1000
  },
  "supportedSourceTypes": ["adblock", "hosts"]
}

Status	Meaning
200	Defaults returned successfully
429	Rate limit exceeded (anonymous tier)

---

POST /api/configuration/validate

Validates a configuration object against the Zod ConfigurationSchema. Requires a Cloudflare Turnstile token when TURNSTILE_SECRET_KEY is configured.

Request

POST /api/configuration/validate
Content-Type: application/json

{
  "configuration": {
    "name": "My Filter List",
    "sources": [
      { "source": "https://example.com/filters.txt" }
    ]
  },
  "turnstileToken": "<optional-turnstile-token>"
}

Response — valid config

{
  "success": true,
  "valid": true,
  "configuration": { ... }
}

Response — invalid config

{
  "success": false,
  "valid": false,
  "errors": [
    { "path": "sources.0.source", "message": "Invalid URL" }
  ]
}

Status	Meaning
200	Validation complete (check valid field)
400	Malformed request body
403	Turnstile verification failed
429	Rate limit exceeded

---

POST /api/configuration/resolve

Merges one or more configuration layers and returns the effective IConfiguration. Useful for previewing the result of a config + environment overlay before submitting a compile job.

Request

POST /api/configuration/resolve
Content-Type: application/json

{
  "config": {
    "name": "Base Config",
    "sources": [
      { "source": "https://example.com/filters.txt" }
    ]
  },
  "override": {
    "transformations": ["Deduplicate", "RemoveEmptyLines"]
  },
  "applyEnvOverrides": true,
  "turnstileToken": "<optional-turnstile-token>"
}

Response

{
  "success": true,
  "resolved": {
    "name": "Base Config",
    "sources": [...],
    "transformations": ["Deduplicate", "RemoveEmptyLines"],
    ...
  }
}

Status	Meaning
200	Resolved configuration returned
400	Malformed or invalid configuration
403	Turnstile verification failed
429	Rate limit exceeded

---

Related Documentation

• Zod Validation — Runtime schema validation for all inputs
• OpenAPI Specification — Complete API schema
• Quick Reference — Common commands at a glance