{"authentication":{"header":"Authorization: Bearer <API_KEY>","how_to_get_key":"POST https://api.hiholo.ai/generate-api-key (no auth required, key valid 7 days, 1 active key per IP).","notes":["Each temporary key gets an isolated tenant store — your data is not shared with other testers.","All /api/* endpoints require Authorization header."],"type":"bearer"},"base_url":"https://api.hiholo.ai","content_type":"application/json","endpoints":[{"method":"POST","name":"Symbolic regression — discover interpretable formula","path":"/api/v2/discover/holo-formula","request_example":{"data":[[1000.0,50.0],[2000.0,100.0],[3000.0,150.0]],"output":[150.0,297.0,449.0],"var_names":["ad_spend","leads"]},"request_schema":{"data":"Vec<Vec<f64>>  // each inner vec = one observation's features","output":"Vec<f64>       // same length as data","var_names":"Option<Vec<String>>  // optional feature names"},"response_fields":["sexp","r2","rmse","coefficients","complexity","vars"],"use_case":"Find a human-readable formula (s-expression with coefficients, R², RMSE) from arbitrary (features, output) data. Best on linear / polynomial multi-variable forms.","verified_latency_ms":250},{"method":"POST","name":"Apply algebraic law to inputs","path":"/api/v2/solve","request_example":{"a":4,"b":7,"law":"Multiplication"},"request_schema":{"a":"number","b":"number","inputs":"Option<Vec<number>>  // alternative N-ary form","law":"string | object  // e.g. \"Addition\" or {Symbolic: {...}}","scale":"Option<u32>  // for rational mode"},"response_fields":["law","answer","confidence"],"use_case":"Apply a known algebraic law (Addition, Subtraction, Multiplication, Division, ...) to two inputs (or N inputs via 'inputs' field).","verified_latency_ms":245},{"method":"POST","name":"Continuous optimization (golden-section)","path":"/api/v2/solve/optimize","request_example":{"expression":"(x - 3)^2 + 1","lower":-10.0,"objective":"minimize","upper":10.0,"variable":"x"},"request_schema":{"expression":"string  // supports + - * / ^ ln exp sin cos","lower":"f64","max_iterations":"Option<usize>","method":"Option<\"golden_section\" | \"grid_search\">","objective":"\"minimize\" | \"maximize\"","tolerance":"Option<f64>","upper":"f64","variable":"string"},"response_fields":["optimum_x","optimum_value","converged","iterations","method"],"use_case":"Minimize or maximize an analytical expression over a bounded interval. Reliable for unimodal 1D objectives.","verified_latency_ms":250},{"method":"POST","name":"Canonical math functions (Taylor, Newton, bisection)","path":"/api/v2/solve/math","request_example":{"function_type":"taylor_sin","params":[1.0]},"request_schema":{"function_type":"\"taylor_sin\" | \"taylor_cos\" | \"taylor_exp\" | \"taylor_ln\" | \"polynomial\" | \"newton_root\" | \"bisection_root\"","params":"Vec<f64>  // taylor_*: [x] or [x, terms]; polynomial: [x, c0, c1, ...]; newton_root/bisection_root: [x0, target_value, ...]"},"response_fields":["result.function_type","result.convergence_info","result.iterations","result.parameters"],"use_case":"Evaluate / root-find for canonical math functions. params is a flat Vec<f64> whose meaning depends on function_type.","verified_latency_ms":230},{"method":"POST","name":"Universal CSP solver (Sudoku, scheduling, all_diff)","path":"/api/solve","request_example_csp":{"constraints":[{"scope":["*"],"type":"all_diff"}],"domain":["mon_am","mon_pm","tue_am","tue_pm"],"max_depth":50,"rows":[{"hearing":"caseA","slot":null},{"hearing":"caseB","slot":null},{"hearing":"caseC","slot":null},{"hearing":"caseD","slot":null}],"target_key":"slot","use_hints":true},"request_example_sudoku":{"grid":[5,3,0,0,7,0,0,0,0,6,0,0,1,9,5,0,0,0,0,9,8,0,0,0,0,6,0,8,0,0,0,6,0,0,0,3,4,0,0,8,0,3,0,0,1,7,0,0,0,2,0,0,0,6,0,6,0,0,0,0,2,8,0,0,0,0,4,1,9,0,0,5,0,0,0,0,8,0,0,7,9],"max_depth":50,"use_hints":true},"request_schema":{"constraints":"Option<Vec<{type, scope}>>","domain":"Option<Vec<string>>","grid":"Option<Vec<u8>>  // 81 cells for Sudoku, 0 = blank","max_depth":"Option<usize>","rows":"Option<Vec<Map<String, Value>>>","target_key":"Option<string>  // column to fill","use_hints":"Option<bool>"},"response_fields":["solved","valid","elapsed_ms","backtracks"],"use_case":"Solve constraint satisfaction: Sudoku via {grid:[...]} OR generic via {rows, target_key, domain, constraints}.","verified_latency_ms":215},{"method":"POST","name":"Online learning — observe","path":"/api/cognitive/observe","request_example":{"rows":[{"amount":"high","device":"new","label":"fraud","location":"foreign","time":"night"},{"amount":"low","device":"known","label":"legit","location":"domestic","time":"day"},{"amount":"high","device":"new","label":"fraud","location":"foreign","time":"night"}],"target_key":"label"},"request_schema":{"entropy":"Option<f64>","rows":"Vec<Map<String, String>>  // all values as strings","target_key":"string  // the label column"},"response_fields":["nodes","target_key","hierarchy_order","tree.nodes"],"use_case":"Phase 1 of stateful online learning. Rows MUST contain string-encoded values for both features and the target_key column.","verified_latency_ms":230},{"method":"POST","name":"Online learning — predict","path":"/api/cognitive/predict","related":["POST /api/cognitive/feedback {input, actual} — close the learning loop"],"request_example":{"input":{"amount":"high","device":"new","location":"foreign","time":"night"}},"request_schema":{"input":"Map<String, String>"},"response_fields":["value","confidence","path","method","bary_shift"],"use_case":"Phase 2: classify a new input after observe. Input is a flat string→string map (excluding the target_key column).","verified_latency_ms":245},{"method":"POST","name":"Text RAG — ingest a single document","path":"/api/feed_text","request_example":{"chunk_separator":"<<<NEVER>>>","doc_id":"gdpr_art_6","metadata":{"category":"compliance","jurisdiction":"EU"},"min_chunk_len":10,"text":"Lawfulness of processing requires that the data subject has given consent..."},"request_schema":{"chunk_separator":"Option<string>  // default \"\\n\\n\". Pass a non-occurring delimiter (e.g. \"<<<NEVER>>>\") to force one atomic chunk per call","doc_id":"Option<string>  // user-supplied id; returned in /api/query_text response","metadata":"Option<Map<String,String>>  // tags indexed for retrieval; returned in `matched_metadata` when query matches any value","min_chunk_len":"Option<usize>  // default 50; chunks shorter than this are dropped","text":"string  // raw text; will be auto-chunked by `chunk_separator`"},"response_fields":["nodes","added","message"],"use_case":"Ingest one document per call. Call multiple times for a corpus.","verified_latency_ms":280},{"method":"POST","name":"Text RAG — semantic query","path":"/api/query_text","request_example":{"k":3,"query":"user consent requirements for data processing"},"request_schema":{"fuzzy_threshold":"Option<f64>  // n-gram similarity for fuzzy fallback, default 0.5","k":"Option<usize>  // top-k (NOT 'top_k'). Default 5.","query":"string"},"response_fields":["results[].chunk_id     // string, e.g. \"chunk_0\" — unique only within a doc_id","results[].doc_id       // string, the user-supplied id from feed_text","results[].d_h          // f64, hyperbolic distance (lower = closer)","results[].text_preview // string, first 120 chars of chunk","results[].matched_words // Vec<string>","results[].matched_metadata // Vec<{key, value}>, populated when query word matches a metadata value","method","query_words","chunks_considered"],"use_case":"Retrieve relevant chunks by meaning. Uses native hyperbolic barycenter hybrid scoring. Sort: matches_count DESC, then d_H ASC.","verified_latency_ms":268},{"method":"POST","name":"Textual abductive reasoning","path":"/api/reason","request_example":{"observations":"officer breach_fiduciary_duty | observe | outcome plaintiff\ndirector self_dealing | observe | outcome plaintiff\nofficer good_faith_decision | observe | outcome defendant","query":"current officer breach_fiduciary_duty self_dealing"},"request_schema":{"observations":"string  // newline-separated, each line in form: 'subject preds | observe | conclusion target'","query":"string","rows":"Option<Vec<Map<String, Value>>>  // alternative tabular format","target_key":"Option<string>"},"response_fields":["ok","backend","observation_count","generated_observations"],"use_case":"Given textual observations + a query, infer ranked plausible conclusions / causes. NOT a strict SAT solver — pattern-based abduction.","verified_latency_ms":255},{"method":"POST","name":"One-shot categorical rule discovery + gap filling","path":"/api/discover","quality_note":"law.sparsity=1-5 → clean interpretable rule. law.verified=true + law.coverage=1.0 → fully reliable prediction.","request_example":{"domain":["approved","rejected"],"rows":[{"decision":"approved","employed":"yes","history":"good","income":"high"},{"decision":"rejected","employed":"no","history":"bad","income":"low"},{"decision":"approved","employed":"yes","history":"good","income":"medium"},{"decision":"approved","employed":"yes","history":"good","income":"low"},{"decision":"rejected","employed":"no","history":"bad","income":"medium"},{"employed":"no","history":"good","income":"high"}],"target_key":"decision"},"request_schema":{"domain":"Option<Vec<string>> — all possible target values; auto-inferred if omitted","max_depth":"usize (default 100)","rows":"Vec<{key: value}> — mix of labeled (target present) and unlabeled rows","target_key":"string — name of the field to predict","use_hints":"bool (default true)"},"response_fields":["law","solved","valid","rows","steps","elapsed_ms"],"use_case":"Discover a Boolean/categorical law from labeled examples AND fill in unlabeled rows in one call. Best for: credit/eligibility rules, IF/ELSE decision logic, PLC/automation rules, medical protocols — any data where the target depends on discrete symbolic features. Auto-detects Z_p per column. Returns the formula, truth table, and completed rows.","verified_latency_ms":5},{"gotchas":["EC_CURVE must appear before any EC_POINT in the DSL.","EC results are in ec_points (not points).","FOOT(P, line_name) — second arg must be a named LET line, not inline LINE().","No spaces inside construction calls: CIRCUMCENTER(A,B,C) not CIRCUMCENTER(A, B, C)."],"method":"POST","name":"Geometric constraint solver + EC arithmetic + Lean 4 proof","path":"/api/geometry_solve","request_example":{"dsl":"POINT A = (0,0)\nPOINT B = (4,0)\nPOINT C = (2,3)\nLET CC = CIRCUMCENTER(A,B,C)\nGOAL EQDIST CC A CC B\nGOAL EQDIST CC B CC C"},"request_schema":{"dsl":"string — geometry DSL program (POINT/LET/GIVEN/GOAL) or EC program (EC_CURVE/EC_POINT/EC_MUL/EC_ADD/GOAL EC_EQ)"},"response_fields":["solved","points","ec_points","constraints_satisfied","constraints_failed","residuals","derived","lean_proof","elapsed_ms"],"use_case":"Verify Euclidean geometry constructions (CIRCUMCENTER, INCENTER, CENTROID, FOOT, ANGLE_BISECTOR, ORTHOCENTER, INTERSECTION, MIDPOINT) and elliptic curve arithmetic (EC_MUL/EC_ADD/EC_NEG/EC_DOUBLE) over arbitrary F_p including secp256k1. Returns satisfied/failed constraint lists and auto-generated Lean 4 proof skeleton.","verified_latency_ms":5},{"gotchas":["Only field in request is dsl — noise/shots are specified inside the DSL via MODE density_matrix and NOISE DEPOL <q> <p>.","probabilities is sparse indexed pairs [[basis_state_idx, prob]] not a flat array.","ground_energy (not energy) is the molecule energy field.","SURFACE_CODE d must be odd and >= 3.","Supported molecules: H2, HeH+, LiH, H2O, NH3, CH4, N2, CO, HF, C2H4."],"method":"POST","mode_detection":{"stabilizer_tree":"triggered by QUBIT+GATE with Clifford-only (H,X,Z,S,CNOT) or SURFACE_CODE d=N","state_vector":"triggered by QUBIT+GATE with Y/T/RX/RY/RZ/NOISE/MODE/IF, or OpenQASM input","variational_phase_relax":"triggered by MOLECULE / ORBITAL / HAMILTONIAN / RELAX"},"name":"Quantum solver — molecules (STO-3G), circuits, surface codes","path":"/api/quantum_tree_solve","request_example":{"dsl":"MOLECULE H2O\nRELAX max_iter=1"},"request_schema":{"dsl":"string — MOLECULE <name> / RELAX | QUBIT / GATE / MEASURE | SURFACE_CODE d=N | OPENQASM 2.0;"},"response_fields":["solved","mode","n_qubits","probabilities","measured","ground_energy","converged","iterations","molecule","occupations","surface_code_info","constraints_satisfied","constraints_failed","elapsed_ms"],"use_case":"Three modes in one DSL — auto-detected by first keyword. MOLECULE: Hartree-Fock energy for H2/HeH+/LiH/H2O/NH3/CH4/N2/CO/HF/C2H4 (STO-3G, <0.02% vs PySCF, 33x faster). QUBIT/GATE/MEASURE: state-vector or stabilizer simulation with Clifford and universal gates, noise models, conditional gates. SURFACE_CODE d=N: stabilizer QEC code, returns syndrome info. OpenQASM 2.0 auto-detected.","verified_latency_ms":5}],"killer_combos":[{"name":"Discover → Apply (no-code ML)","steps":["POST /api/v2/discover/holo-formula on historical (data, output) pairs → get s-expression and R²","If law is canonical (Addition/Multiplication/...), POST /api/v2/solve with {law, a, b} for instant prediction","For arbitrary formula, evaluate sexp client-side or pass into /api/v2/solve/optimize"]},{"name":"Online adaptive controller","steps":["POST /api/cognitive/observe {target_key, rows} as stream arrives","POST /api/cognitive/predict {input} before each decision","POST /api/cognitive/feedback {input, actual} to close the loop. No retraining."]},{"name":"RAG + Reasoning","steps":["POST /api/feed_text {text, doc_id} once per document","POST /api/query_text {query, k} → retrieve top-k chunks","Transform retrieved facts into 'subject preds | observe | conclusion target' lines","POST /api/reason {observations, query} → ranked conclusions with backend trace"]}],"name":"Holo Engine API","tagline":"Discover laws, solve constraints, learn online, search by meaning — in one geometric substrate.","tips_for_ai_agents":["Always send Content-Type: application/json on POST.","Cognitive endpoints take STRING values only in rows/input maps (not numbers).","/api/feed_text accepts ONE document per call — loop for a corpus.","/api/query_text uses field 'k', not 'top_k'.","/api/v2/solve/optimize response uses 'optimum_x', 'optimum_value' (not 'optimal_x').","/api/v2/solve/math response is nested under 'result'.","/api/reason observations is a single string with \\n separators, not an array.","Numeric values must be finite (no NaN / Infinity).","For heavy discovery use 30–120s client timeout.","Need full internal API surface? Contact admin — /api/schema/full is restricted."],"version":"2.0.1"}