Skip to content

Machine-Readable API Contracts

The docs site publishes machine-readable files alongside human documentation so agents can discover and use LeafEnterprise systems without scraping prose.

Files

File Purpose
/machine/system-authority.json Backend authority decisions, non-authoritative source boundaries, and output ownership.
/machine/data-plane.json Source systems, storage layers, source roles, sensitivity posture, and allowed consumers.
/machine/calculation-registry.json Named savings/audit formulas, source tables, implementation paths, and blocked states.
/machine/evidence-lineage.json Evidence-to-output chains for reports, dashboards, workbooks, optimization, contract packets, and agent context.
/machine/backend-capability-map.json Backend provisions, integrations, workers, SDKs, and presentation boundaries.
/machine/domo-integration.json Domo PDP, group, App Studio/private embed, recovered estate evidence, and backend dual-enforcement rules.
/machine/api-reference.json Structured route families, endpoints, queue actions, owners, auth posture, fields, response sections, tests, and source modules.
/llms.txt High-level discovery file for agents and retrieval systems.

Contract Semantics

api-reference.json is intended for:

  • MCP tool generation,
  • route coverage checks,
  • retrieval metadata,
  • API catalog publication,
  • agent route selection,
  • human review of endpoint ownership.

The semantic registries are intended for:

  • authority-aware agent planning,
  • retrieval index metadata,
  • MCP tool descriptions,
  • savings/audit reproducibility explanations,
  • dashboard ownership checks,
  • source-system boundary enforcement.

Each endpoint record carries:

  • method,
  • path,
  • family,
  • handler,
  • summary,
  • auth,
  • query_params,
  • body_fields,
  • response_sections,
  • status_codes,
  • cache,
  • notes,
  • tests.

Source Control Rule

Do not edit generated machine files directly. Update:

  • docs-site/api-reference.yml for live-route metadata,
  • LeafEnterprise/service_contracts.py for stable product endpoint and queue-action contracts,
  • scripts/generate_docs_api_reference.py for generator behavior.

Then run:

python scripts\generate_docs_api_reference.py --check-route-coverage
python scripts\validate_docs_semantic_registry.py
python -m mkdocs build -f docs-site\mkdocs.yml --strict