Config Service REST API

The Config Service is an authenticated REST API mounted at /api/v1/_config/* that lets you inspect and mutate flAPI's runtime configuration — endpoints, templates, caches, schema introspection, log level, and project metadata — without restarting the server.

It is the foundation that the flapii CLI and the MCP flapi_* administration tools wrap.

Activation

The Config Service is disabled by default. Start the server with --config-service to mount the routes:

# Auto-generated token printed to stdout
flapi --config-service

# Explicit token via flag
flapi --config-service --config-service-token "your-secret-token"

# Or via environment variable
export FLAPI_CONFIG_SERVICE_TOKEN="your-secret-token"
flapi --config-service

Without --config-service, requests to /api/v1/_config/* will not be routed at all.

Authentication

Every endpoint (except /health and /api/v1/doc.yaml) requires a bearer token. Two header forms are accepted:

Authorization: Bearer <token>

X-Config-Token: <token>

Missing or invalid token returns:

HTTP/1.1 401 Unauthorized
Content-Type: text/plain

Unauthorized: Invalid or missing token

Base Path

All routes are mounted under /api/v1/_config/. The Swagger document is the one exception: GET /api/v1/doc.yaml.

Endpoint Reference

Project Configuration

GET /api/v1/_config/project

Retrieve the parsed project configuration.

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/project

{
  "project-name": "my-api",
  "project-description": "Customer data API",
  "server-name": "localhost",
  "http-port": 8080,
  "template": { "path": "./sqls" }
}

GET /api/v1/_config/environment-variables

List the whitelisted environment variables and whether each is currently set.

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/environment-variables

{
  "variables": [
    { "name": "DB_PASSWORD", "value": "***", "available": true },
    { "name": "API_KEY", "value": null, "available": false }
  ]
}

---

Endpoint Management

Endpoints are identified by slug: REST endpoints use {METHOD}-{path} (e.g. GET-customers), MCP tools use their tool name. See Slug format.

GET /api/v1/_config/endpoints

List all configured endpoints.

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/endpoints

[
  {
    "url-path": "/customers",
    "method": "GET",
    "template-source": "customers.sql",
    "connection": ["customers-db"]
  }
]

POST /api/v1/_config/endpoints

Create a new endpoint.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url-path": "/orders",
    "method": "GET",
    "template-source": "orders.sql",
    "connection": ["orders-db"]
  }' \
  http://127.0.0.1:8080/api/v1/_config/endpoints

{ "success": true, "message": "Endpoint created", "slug": "GET-orders" }

GET /api/v1/_config/endpoints/{slug}

Get a single endpoint configuration.

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers

PUT /api/v1/_config/endpoints/{slug}

Replace the endpoint configuration.

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url-path": "/customers", "method": "GET", "template-source": "customers-v2.sql", "connection": ["customers-db"] }' \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers

{ "success": true, "message": "Endpoint updated" }

DELETE /api/v1/_config/endpoints/{slug}

Delete an endpoint.

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers

{ "success": true, "message": "Endpoint deleted" }

POST /api/v1/_config/endpoints/{slug}/validate

Validate an endpoint YAML body without persisting it.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary @endpoint.yaml \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers/validate

{ "valid": true, "errors": [], "warnings": [] }

POST /api/v1/_config/endpoints/{slug}/reload

Reload the endpoint definition from disk (useful after editing files directly).

curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers/reload

{ "success": true, "message": "Endpoint reloaded from disk" }

GET /api/v1/_config/endpoints/{slug}/parameters

Return parameter metadata for an endpoint.

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers/parameters

{
  "endpoint": "/customers",
  "method": "GET",
  "parameters": [
    {
      "name": "id",
      "in": "query",
      "required": false,
      "validators": [{ "type": "int", "min": 1 }]
    }
  ]
}

POST /api/v1/_config/endpoints/by-template

Find every endpoint (REST or MCP) bound to a given template file.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_path":"customers.sql"}' \
  http://127.0.0.1:8080/api/v1/_config/endpoints/by-template

{
  "template_path": "customers.sql",
  "count": 2,
  "endpoints": [
    { "url_path": "/customers", "method": "GET", "type": "REST" },
    { "mcp_name": "get_customers", "type": "MCP_Tool" }
  ]
}

---

Template Management

GET /api/v1/_config/endpoints/{slug}/template

Fetch the Mustache+SQL template body.

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers/template

{ "template": "SELECT * FROM customers WHERE 1=1 {{#params.id}} AND id = {{ params.id }} {{/params.id}}" }

PUT /api/v1/_config/endpoints/{slug}/template

Replace the template content.

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template":"SELECT * FROM customers WHERE status = '\''active'\''"}' \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers/template

{ "success": true, "message": "Template updated" }

POST /api/v1/_config/endpoints/{slug}/template/expand

Expand the template with sample parameters; useful for debugging without hitting the database.

Query parameters: include_variables (boolean), validate_only (boolean).

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{"id":"123","status":"active"}}' \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers/template/expand

{ "expanded": "SELECT * FROM customers WHERE 1=1 AND id = 123 AND status = 'active'" }

POST /api/v1/_config/endpoints/{slug}/template/test

Execute the template against the live connection with sample parameters, capped at 10 rows.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{"id":"123"}}' \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers/template/test

{
  "success": true,
  "columns": ["id", "name", "email"],
  "rows": [ { "id": 123, "name": "John Doe", "email": "john@example.com" } ]
}

---

Cache Management

GET /api/v1/_config/endpoints/{slug}/cache

Return cache configuration for an endpoint.

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers/cache

{
  "enabled": true,
  "table": "customers_cache",
  "schema": "cache",
  "schedule": "5m",
  "primary-key": ["id"],
  "cursor": { "column": "updated_at", "type": "timestamp" }
}

PUT /api/v1/_config/endpoints/{slug}/cache

Replace cache configuration.

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"table":"customers_cache","schedule":"10m"}' \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers/cache

{ "success": true, "message": "Cache configuration updated" }

GET /api/v1/_config/endpoints/{slug}/cache/template

Get the cache populate SQL template.

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers/cache/template

{ "template": "INSERT INTO {{cache.table}} SELECT * FROM source" }

PUT /api/v1/_config/endpoints/{slug}/cache/template

Update the cache populate template.

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template":"REPLACE INTO {{cache.table}} SELECT * FROM customers"}' \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers/cache/template

POST /api/v1/_config/endpoints/{slug}/cache/refresh

Trigger an out-of-band cache refresh.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers/cache/refresh

{ "success": true, "message": "Cache refresh triggered" }

POST /api/v1/_config/endpoints/{slug}/cache/gc

Run garbage collection on cached snapshots according to the retention policy.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/endpoints/GET-customers/cache/gc

---

Schema Introspection

GET /api/v1/_config/schema

Retrieve database schema metadata.

Query parameters: tables (boolean), connections (boolean), format=completion, connection={name}.

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/schema

{
  "main": {
    "tables": {
      "customers": {
        "is_view": false,
        "columns": {
          "id":    { "type": "INTEGER", "nullable": false },
          "name":  { "type": "VARCHAR", "nullable": false },
          "email": { "type": "VARCHAR", "nullable": true }
        }
      }
    }
  }
}

POST /api/v1/_config/schema/refresh

Force a refresh of the cached schema introspection data.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/schema/refresh

{ "success": true, "message": "Schema refreshed" }

---

Server Administration

GET /api/v1/_config/log-level

Get the current server log level.

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/log-level

{ "level": "info" }

PUT /api/v1/_config/log-level

Change the log level at runtime. Valid values: debug, info, warning, error.

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"level":"debug"}' \
  http://127.0.0.1:8080/api/v1/_config/log-level

{ "level": "debug", "message": "Log level updated successfully" }

---

Filesystem Operations

GET /api/v1/_config/filesystem

Return the project's on-disk structure — useful for tooling that wants to map files to endpoints.

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/_config/filesystem

{
  "base_path": "/home/user/project",
  "config_file": "flapi.yaml",
  "config_file_exists": true,
  "template_path": "/home/user/project/sqls",
  "tree": [
    {
      "name": "customers.yaml",
      "type": "file",
      "path": "customers.yaml",
      "extension": ".yaml",
      "yaml_type": "endpoint",
      "url_path": "/customers"
    },
    { "name": "customers.sql", "type": "file", "path": "customers.sql", "extension": ".sql" }
  ]
}

GET /api/v1/doc.yaml

Returns the live OpenAPI 3 specification for the public REST endpoints (user-defined endpoints, not the Config Service itself). No authentication required.

curl http://127.0.0.1:8080/api/v1/doc.yaml

---

HTTP Status Codes

Code	Meaning
200	OK — request successful
201	Created — resource created (e.g. new endpoint)
400	Bad Request — invalid input, malformed JSON, missing field
401	Unauthorized — invalid or missing token
404	Not Found — slug doesn't match any endpoint
500	Internal Server Error
501	Not Implemented
503	Service Unavailable — backend dependency unreachable

Error Envelope

Most failures return a JSON body:

{
  "error": "Validation failed",
  "details": ["field-name is required"]
}

401 Unauthorized is the one exception — it returns plain text (Unauthorized: Invalid or missing token) so token leakage in JSON logs is avoided.

Slug Format

Endpoint type	Format	Example
REST	{METHOD}-{path}	GET-customers, POST-orders
MCP Tool	{tool_name}	get_customers
MCP Resource	resource-{name}	resource-schema
MCP Prompt	prompt-{name}	prompt-analysis

Path conversion rules for REST slugs:

• Leading / is removed
• / becomes -slash-
• Other special characters become -
• Empty path becomes empty

Examples: /customers → GET-customers, /api/v1/users → GET-api-slash-v1-slash-users.

Related Tooling

The Config Service is the source of truth that higher-level tools wrap:

• flapii CLI — wraps every endpoint above as a friendly subcommand (flapii endpoints list, flapii templates expand, flapii cache refresh, etc.).
• MCP flapi_* tools — the AI integration surface exposes these same operations as MCP tools so that agents can manage flAPI through the MCP protocol.
• Cloud Storage and VFS — pair this API with remote flapi.yaml to roll out config changes without touching the filesystem.