HTTP Batch API

Reference for the FeatureMesh HTTP Batch API — the JSON interface exposed by the demos stack and similar self-hosted setups (commonly on port 8101). Paths match the Python BatchClient methods. Send Content-Type: application/json.

For how the pieces fit together, start with Overview . Most notebook work can stay in Python and never call HTTP.

Common fields

structured

Use "structured": true whenever your script needs rows, SQL, or typed errors. Python clients already return those fields without this flag.

debug

Leave at "off" unless you are investigating a compiler issue and need on-disk pipeline logs. Ordinary query work does not require it.

Routes

GET /capabilities

Lists enabled endpoints, backends, and optional serving executors for this server.

GET /health

Liveness check.

POST /query

Run FeatureQL and return results.

{
  "query": "SELECT F := 1;",
  "backend": "duckdb",
  "structured": true
}

With structured: true, expect sql, dataframe, errors, warnings, and timings. Errors look like:

{
  "code": "UE/…",
  "message": "…",
  "location": [{"line": 1, "column": 10}],
  "hint": "… optional"
}

Additional fields (context, dependency path, …) appear when relevant.

POST /translate

Same body as /query, without execution. Structured responses emphasize sql, errors, warnings.

POST /validate

Formatting, feature graph, and optional SQL dry-run. See Productivity tools .

{
  "query": "SELECT A := 1, B := A + 1;",
  "backend": "duckdb",
  "structured": true,
  "detail": "compact"
}

detail is "compact" (default) or "full". Structured fields include formatted_featureql, output_schema, features, warnings, sql_valid, generated_sql.

POST /diagnose

Runs the query incrementally until the first failure. See Productivity tools .

{
  "query": "SELECT A := 1, B := CONCAT(1, 2) + A;",
  "backend": "duckdb",
  "structured": true
}

Important fields: failed_step, steps (each with feature_added, optional error list), explain_json.

POST /describe

{
  "prefixes": ["FM.DEMO."],
  "backend": "duckdb",
  "structured": true
}

Requires at least one non-empty prefix.

POST /help

{
  "terms": ["extend"],
  "backend": "duckdb",
  "structured": true,
  "detail": "normal",
  "examples": 5
}

Structured responses include doc_pages, code_samples, signatures, and tests. Good starting terms: mental_model, getting_started.

POST /sltest and POST /sltest_stream

Run documentation / conformance tests. Bodies are mutually exclusive:

{
  "backend": "duckdb",
  "where": "NAME LIKE '%extend%#%'",
  "limit": 50,
  "halt_on_fail": false
}

where / limit: where is a FeatureQL predicate; dependency-aware (keeps # depends:). Only "fetch_backend": "duckdb" is required for the outer depends CTE (or "backend": "duckdb" when fetch defaults to it). Transient registry timeouts are retried automatically.

Or a custom fetch (any backend that can run the FeatureQL; you own the universe / optional RUN):

{
  "backend": "duckdb",
  "source": "SHOW DOCS (INCLUDE (CONTENT)) WHERE CATEGORY='CODE_SAMPLE' AND NAME LIKE '%extend%#%' ORDER BY NAME",
  "halt_on_fail": false
}

source must return NAME and CONTENT. Optional RUN selects targets while still honoring # depends:. /sltest returns the full result list; /sltest_stream streams progress.

Guide: Conformance tests .

POST /sltest_multi

Multi-backend execution when the server is configured for it. Ordinary runs use /sltest.

POST /direct_sql_query

Raw SQL through the server’s optional SQL executor — not FeatureQL.

Errors

A successful HTTP status can still include errors: […]. Use code and location when handling them in automation. Invalid request bodies return VALIDATION-ERROR with the same shape.

Examples

BASE=http://localhost:8101

curl -s "$BASE/capabilities"

curl -s -X POST "$BASE/validate" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT F := 1;","backend":"duckdb","structured":true}'

curl -s -X POST "$BASE/query" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT F := 1;","backend":"duckdb","structured":true}'

Next

• Conformance tests
• Productivity tools
• Working with an assistant