{"openapi":"3.1.0","info":{"title":"LAKA Volumetric Writing Grammar System API","version":"1.0.0","summary":"Machine-readable writing rules, and an engine that runs them over text.","description":"Break writing into first principles and expose machine-readable IF / ELSE / AND / OR rules across grammar, style, narrative, nonfiction, technical writing, copywriting, accessibility, ethics, and editing.\n\nThe corpus holds 289 operational rule records across 228 base rules, 56 LAKA transformation states and 5 cross-axis rules.\n\nRule conditions are Boolean ASTs over named facts. Many of those facts are semantic and cannot be derived from raw text. The engine evaluates in three-valued logic and reports unresolved facts under `needs_input` rather than guessing them.\n\nThis is a decision system, not a universal command to make all prose plain or uniform. Apply genre, audience, stakes, dialect, locale, and deliberate exceptions while preserving truth, safety, accessibility, and intended meaning.","license":{"name":"Original synthesis. Source titles remain the property of their authors and publishers."},"contact":{"name":"Bow Tie Kreative","url":"https://bowtiekreative.com"}},"servers":[{"url":"https://writingsystem.bowtiekreative.com","description":"Production"}],"tags":[{"name":"Meta","description":"Index, health and specification."},{"name":"Corpus","description":"The rule corpus, verbatim and indexed."},{"name":"Engine","description":"Running the rules over text."}],"paths":{"/v1":{"get":{"tags":["Meta"],"summary":"API index","responses":{"200":{"description":"The index","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/health":{"get":{"tags":["Meta"],"summary":"Liveness and corpus counts","responses":{"200":{"description":"Health","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/openapi.json":{"get":{"tags":["Meta"],"summary":"This document","responses":{"200":{"description":"OpenAPI document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/manifest":{"get":{"tags":["Corpus"],"summary":"Manifest, inventory and load order","responses":{"200":{"description":"Manifest","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/files":{"get":{"tags":["Corpus"],"summary":"The 30 source files","responses":{"200":{"description":"File list","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/files/{slug}":{"get":{"tags":["Corpus"],"summary":"One source file, verbatim","parameters":[{"name":"slug","in":"path","required":true,"description":"File slug or two-digit number, e.g. `core-grammar-rules` or `07`.","schema":{"type":"string"}}],"responses":{"200":{"description":"The file","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No such file","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/principles":{"get":{"tags":["Corpus"],"summary":"Writing from first principles","responses":{"200":{"description":"Principles","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/primitives":{"get":{"tags":["Corpus"],"summary":"Linguistic primitives","responses":{"200":{"description":"Primitives","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/grid":{"get":{"tags":["Corpus"],"summary":"The LAKA volumetric grid","responses":{"200":{"description":"Grid","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/axes":{"get":{"tags":["Corpus"],"summary":"Context axes and precedence","responses":{"200":{"description":"Axes","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/operators":{"get":{"tags":["Corpus"],"summary":"Boolean and decision logic","responses":{"200":{"description":"Operators","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/schema":{"get":{"tags":["Corpus"],"summary":"JSON Schema for a rule","responses":{"200":{"description":"Schema","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/engine-spec":{"get":{"tags":["Corpus"],"summary":"Reference rule-engine specification","responses":{"200":{"description":"Engine spec","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/rules":{"get":{"tags":["Corpus"],"summary":"Search and filter the base rules","parameters":[{"name":"q","in":"query","required":false,"description":"Free-text match against id, name, logic, rationale and diagnostics.","schema":{"type":"string"}},{"name":"domain","in":"query","required":false,"description":"Comma-separated domains: grammar, punctuation, syntax, structure, clarity, technical_writing, copywriting, narrative, argument, accessibility, editing, ethics, voice, rhythm.","schema":{"type":"string"}},{"name":"layer","in":"query","required":false,"description":"Comma-separated layers: sentence, section, document, paragraph, phrase, content_system, clause, word, signal.","schema":{"type":"string"}},{"name":"strength","in":"query","required":false,"description":"Comma-separated strengths: hard_constraint, context_default, heuristic, creative_option.","schema":{"type":"string"}},{"name":"source","in":"query","required":false,"description":"Only rules citing this source id, e.g. `BK-002`.","schema":{"type":"string"}},{"name":"axis","in":"query","required":false,"description":"Only rules whose LAKA primary_axes include this axis.","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Return full rule records with tests and sources.","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–500.","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},{"name":"offset","in":"query","required":false,"description":"Rows to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Matching rules with facet counts","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/rules/{id}":{"get":{"tags":["Corpus"],"summary":"One rule, expanded","parameters":[{"name":"id","in":"path","required":true,"description":"Rule id, e.g. `GRM-001`.","schema":{"type":"string"}}],"responses":{"200":{"description":"The rule with its tests, sources and required facts","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No such rule","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/domains":{"get":{"tags":["Corpus"],"summary":"Rule counts by domain","responses":{"200":{"description":"Domains","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/layers":{"get":{"tags":["Corpus"],"summary":"Rule counts by layer","responses":{"200":{"description":"Layers","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/strengths":{"get":{"tags":["Corpus"],"summary":"Rule counts by strength","responses":{"200":{"description":"Strengths","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/transformations":{"get":{"tags":["Corpus"],"summary":"LAKA transformation-state rules","parameters":[{"name":"axis","in":"query","required":false,"description":"Restrict to one dynamic axis, e.g. `magnitude`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–500.","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},{"name":"offset","in":"query","required":false,"description":"Rows to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Transformation states","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/transformations/{id}":{"get":{"tags":["Corpus"],"summary":"One transformation state","parameters":[{"name":"id","in":"path","required":true,"description":"State id.","schema":{"type":"string"}}],"responses":{"200":{"description":"The state","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No such state","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/templates":{"get":{"tags":["Corpus"],"summary":"Conditional composition templates","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–500.","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},{"name":"offset","in":"query","required":false,"description":"Rows to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Conditional composition templates","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/templates/{id}":{"get":{"tags":["Corpus"],"summary":"Conditional composition templates — one record","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"string"}}],"responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No such record","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/pipelines":{"get":{"tags":["Corpus"],"summary":"End-to-end writing pipelines","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–500.","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},{"name":"offset","in":"query","required":false,"description":"Rows to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"End-to-end writing pipelines","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/pipelines/{id}":{"get":{"tags":["Corpus"],"summary":"End-to-end writing pipelines — one record","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"string"}}],"responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No such record","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/profiles":{"get":{"tags":["Corpus"],"summary":"Application profiles","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–500.","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},{"name":"offset","in":"query","required":false,"description":"Rows to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Application profiles","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/profiles/{id}":{"get":{"tags":["Corpus"],"summary":"Application profiles — one record","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"string"}}],"responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No such record","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/recipes":{"get":{"tags":["Corpus"],"summary":"Volumetric generation recipes","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–500.","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},{"name":"offset","in":"query","required":false,"description":"Rows to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Volumetric generation recipes","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/recipes/{id}":{"get":{"tags":["Corpus"],"summary":"Volumetric generation recipes — one record","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"string"}}],"responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No such record","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/tests":{"get":{"tags":["Corpus"],"summary":"Rule test cases and minimal pairs","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–500.","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},{"name":"offset","in":"query","required":false,"description":"Rows to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Rule test cases and minimal pairs","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/tests/{id}":{"get":{"tags":["Corpus"],"summary":"Rule test cases and minimal pairs — one record","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"string"}}],"responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No such record","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/sources":{"get":{"tags":["Corpus"],"summary":"Source bibliography","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–500.","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},{"name":"offset","in":"query","required":false,"description":"Rows to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Source bibliography","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/sources/{id}":{"get":{"tags":["Corpus"],"summary":"Source bibliography — one record","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"string"}}],"responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No such record","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/glossary":{"get":{"tags":["Corpus"],"summary":"Glossary terms","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–500.","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},{"name":"offset","in":"query","required":false,"description":"Rows to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Glossary terms","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/glossary/{id}":{"get":{"tags":["Corpus"],"summary":"Glossary terms — one record","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"string"}}],"responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No such record","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/metrics":{"get":{"tags":["Corpus"],"summary":"Quality measurement model","responses":{"200":{"description":"Metrics","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/search":{"get":{"tags":["Corpus"],"summary":"Search the whole corpus","parameters":[{"name":"q","in":"query","required":false,"description":"Query string. All terms must match.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Comma-separated types: rule, transformation, template, pipeline, term, source, file.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum results.","schema":{"type":"integer","default":25,"maximum":200}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/graph":{"get":{"tags":["Corpus"],"summary":"The corpus as nodes and edges","responses":{"200":{"description":"Graph","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/backlinks/{id}":{"get":{"tags":["Corpus"],"summary":"What cites, tests or neighbours an id","parameters":[{"name":"id","in":"path","required":true,"description":"A rule id or a source id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Backlinks","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No such id","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/engine/facts":{"get":{"tags":["Engine"],"summary":"Derived vs supplied facts","description":"Every fact path the analyser derives from raw text, and every path the rules read. The difference is what you must supply.","responses":{"200":{"description":"Fact paths","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/analyze":{"post":{"tags":["Engine"],"summary":"Surface analysis of a text","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","description":"The text to analyse."},"context":{"type":"object","description":"Rhetorical situation, merged into the model."}}},"example":{"text":"The report was written by the committee. It was approved without discussion."}}}},"responses":{"200":{"description":"Document, paragraph and sentence measurements","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Missing text","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/evaluate":{"post":{"tags":["Engine"],"summary":"Run the rule engine over a text","description":"Analyses the text, selects the rules that apply, and evaluates each one against every unit of its layer.\n\nResults split four ways: `blocking` (hard constraints demanding a change), `context_defaults`, `ranked_options` (heuristics and creative options), and `checks` (rules that ask you to verify or supply context rather than edit).\n\nRules whose conditions read facts the analyser cannot derive appear under `needs_input` with the exact paths required. Supply them under `facts` to resolve them.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":200000},"context":{"type":"object","description":"The rhetorical situation. Each axis takes one of the values declared in 03-context-axes.json.","properties":{"purpose":{"type":"string","enum":["inform","explain","instruct","record","analyze","argue","persuade","sell","entertain","inspire","warn","coordinate"]},"audience_role":{"type":"string","enum":["novice","learner","practitioner","expert","decision_maker","buyer","user","operator","reviewer","public"]},"audience_state":{"type":"string","enum":["unaware","problem_aware","solution_aware","offer_aware","ready_to_act","skeptical","confused","time_constrained","distressed"]},"channel":{"type":"string","enum":["book","article","report","email","web_page","landing_page","advertisement","social_post","proposal","documentation","user_interface","script","presentation"]},"genre":{"type":"string","enum":["narrative","exposition","argument","procedure","reference","description","correspondence","marketing","microcopy"]},"stakes":{"type":"string","enum":["low","ordinary","high","safety_critical"]},"formality":{"type":"string","enum":["intimate","conversational","professional","formal","ceremonial"]},"evidence_need":{"type":"string","enum":["none","illustrative","credible","documented","expert_or_scientific"]},"reading_condition":{"type":"string","enum":["focused","scanning","interrupted","mobile","screen_reader","translated","under_stress"]},"knowledge_gap":{"type":"string","enum":["none","small","moderate","large","unknown"]},"emotional_temperature":{"type":"string","enum":["calm","curious","hopeful","skeptical","anxious","angry","grieving","urgent"]},"lifecycle":{"type":"string","enum":["draft","developmental_edit","line_edit","copyedit","proofread","published","maintained"]}}},"facts":{"type":"object","description":"Semantic facts you assert, deep-merged over the derived ones. See GET /v1/engine/facts."},"profile":{"type":"string","enum":["PROFILE-GENERAL","PROFILE-PLAIN","PROFILE-TECH","PROFILE-NARRATIVE","PROFILE-COPY","PROFILE-SAFETY","PROFILE-UI"],"description":"Application profile; selects the active domains."},"domains":{"type":"array","items":{"type":"string","enum":["grammar","punctuation","syntax","structure","clarity","technical_writing","copywriting","narrative","argument","accessibility","editing","ethics","voice","rhythm"]}},"layers":{"type":"array","items":{"type":"string","enum":["sentence","section","document","paragraph","phrase","content_system","clause","word","signal"]}},"strengths":{"type":"array","items":{"type":"string","enum":["hard_constraint","context_default","heuristic","creative_option"]}},"rule_ids":{"type":"array","items":{"type":"string"},"description":"Evaluate exactly these rules."},"include_trace":{"type":"boolean","description":"Include the per-condition evaluation trace."}}},"example":{"text":"The committee reviewed the report, it was approved without discussion.","profile":"PROFILE-GENERAL","context":{"genre":"report","stakes":"medium"}}}}},"responses":{"200":{"description":"Engine result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Missing text","content":{"application/json":{"schema":{"type":"object"}}}},"413":{"description":"Text too large","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/resolve":{"post":{"tags":["Engine"],"summary":"Which rules govern a context, before you draft","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"string","enum":["PROFILE-GENERAL","PROFILE-PLAIN","PROFILE-TECH","PROFILE-NARRATIVE","PROFILE-COPY","PROFILE-SAFETY","PROFILE-UI"]},"domains":{"type":"array","items":{"type":"string","enum":["grammar","punctuation","syntax","structure","clarity","technical_writing","copywriting","narrative","argument","accessibility","editing","ethics","voice","rhythm"]}},"layers":{"type":"array","items":{"type":"string","enum":["sentence","section","document","paragraph","phrase","content_system","clause","word","signal"]}},"strengths":{"type":"array","items":{"type":"string","enum":["hard_constraint","context_default","heuristic","creative_option"]}},"context":{"type":"object"}}},"example":{"profile":"PROFILE-TECH"}}}},"responses":{"200":{"description":"The active rule set, its precedence and selection policy","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/score":{"post":{"tags":["Engine"],"summary":"Score a text against the twelve quality metrics","description":"Scores are supplied by you, 0–4. Four gate metrics — accuracy, evidence, accessibility, ethics — fail the document regardless of the average when they fall below 2. An unscored gate metric leaves the gate open; it is not a pass.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scores":{"type":"object","additionalProperties":{"type":"number","minimum":0,"maximum":4},"description":"Metric id to score. Ids: accuracy, grammar, clarity, usability, structure, evidence, accessibility, voice_fit, rhythm, ethics, maintainability, outcome."},"notes":{"type":"object","additionalProperties":{"type":"string"}}}},"example":{"scores":{"accuracy":3,"clarity":3,"usability":2,"evidence":3,"accessibility":3,"ethics":4}}}}},"responses":{"200":{"description":"Weighted score, gate verdict and per-metric detail","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/tests/run":{"get":{"tags":["Engine"],"summary":"Run the corpus test cases through this engine","description":"Executes the corpus' own minimal pairs. A case is decidable when the analyser can derive every fact its rule reads; the rest are reported as needing asserted facts.","responses":{"200":{"description":"Test results","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}