diff --git a/.gitignore b/.gitignore
index 3e23706e3a9..aabb4e8c509 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,6 +29,7 @@ ocaml/xenopsd/scripts/xen-backend.rules
 ocaml/xenopsd/xentoollog_flags
 
 ocaml/idl/gen_lifecycle.exe
+ocaml/idl/datamodel_main.exe
 
 .hugo_build.lock
 go.sum
diff --git a/ocaml/idl/dune b/ocaml/idl/dune
index 713462e7ffa..9ed5d9edcf3 100644
--- a/ocaml/idl/dune
+++ b/ocaml/idl/dune
@@ -31,21 +31,26 @@
   (libraries
     dune-build-info
     mustache
+    xapi-consts.xapi_version
     xapi-datamodel
     xapi-stdext-std
     xapi-stdext-pervasives
     xapi-stdext-unix
   )
+  (promote (until-clean))
 )
 
+; use the binary promoted file from the source dir (not the build dir) that has
+; the correct version number embedded
 (rule
   (alias markdowngen)
   (deps
-    (:x datamodel_main.exe)
+    datamodel_main.exe
     (source_tree templates)
+    (universe)
   )
   (package xapi-datamodel)
-  (action (run %{x} -closed -markdown))
+  (action (system "%{project_root}/../../ocaml/idl/datamodel_main.exe -closed -markdown"))
 )
 
 (test
diff --git a/ocaml/idl/markdown_backend.ml b/ocaml/idl/markdown_backend.ml
index 4b8e39e48fc..8787665342f 100644
--- a/ocaml/idl/markdown_backend.ml
+++ b/ocaml/idl/markdown_backend.ml
@@ -533,6 +533,12 @@ let generate_errors () =
     ("api_errors.mustache", "api-ref-autogen-errors.md")
     error_json templatesdir destdir
 
+let generate_ref () =
+  let ref_json = `O [("version", `String Xapi_version.version)] in
+  render_file
+    ("api_ref.mustache", "api-ref-autogen.md")
+    ref_json templatesdir destdir
+
 let all api =
   (* Remove private messages that are only used internally (e.g. get_record_internal) *)
   let api =
@@ -549,6 +555,7 @@ let all api =
   in
 
   List.iter generate_class system ;
+  generate_ref () ;
   generate_classes system ;
   generate_relationships api ;
   generate_types system ;
diff --git a/ocaml/idl/autogen/api-ref-autogen.md b/ocaml/idl/templates/api_ref.mustache
similarity index 91%
rename from ocaml/idl/autogen/api-ref-autogen.md
rename to ocaml/idl/templates/api_ref.mustache
index 7abf22b6872..deb1a6716bd 100644
--- a/ocaml/idl/autogen/api-ref-autogen.md
+++ b/ocaml/idl/templates/api_ref.mustache
@@ -4,7 +4,7 @@
 
 # API Reference
 
-Version **@xapi-version@**
+Version {{version}}
 
 -  [Classes](@root@management-api/classes.html)
 -  [Relationships Between Classes](@root@management-api/relationships-between-classes.html)