diff --git a/.gitignore b/.gitignore
@@ -8,4 +8,5 @@ tpch-data/
 .claude
 docs/superpowers
 docs/build/
+docs/source/_extra/
 docs/venv/
diff --git a/docs/README.md b/docs/README.md
@@ -24,8 +24,11 @@ documentation site.
 
 ## Build
 
-Building the docs requires Python 3.9 or newer. A virtual environment under
-`docs/venv/` is the recommended workflow.
+Building the docs requires Python 3.9 or newer and a working `./mvnw` at the
+repo root (the build runs `./mvnw javadoc:javadoc` to generate the API
+reference, which also needs JDK 17 and one-time network access to fetch
+upstream `.proto` files). A virtual environment under `docs/venv/` is the
+recommended workflow.
 
 ```sh
 cd docs

diff --git a/docs/build.sh b/docs/build.sh
@@ -22,6 +22,14 @@ set -e
 cd "$(dirname "$0")"
 
 rm -rf build
+rm -rf source/_extra
+
+# Generate Javadoc from the repo root. javadoc:javadoc triggers
+# generate-sources, which fetches upstream protos via wget.
+(cd .. && ./mvnw -q -DskipTests javadoc:javadoc)
+
+mkdir -p source/_extra
+cp -R ../target/reports/apidocs source/_extra/api
 
 if [ -d venv ]; then
   # shellcheck disable=SC1091

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -32,7 +32,7 @@
 }
 
 templates_path = ["_templates"]
-exclude_patterns = []
+exclude_patterns = ["_extra"]
 
 html_theme = "pydata_sphinx_theme"
 html_theme_options = {
@@ -48,6 +48,7 @@
 }
 
 html_static_path = ["_static"]
+html_extra_path = ["_extra"]
 
 # Auto-generate anchor links for headings h1, h2, h3.
 myst_heading_anchors = 3

diff --git a/docs/source/user-guide/api-reference.md b/docs/source/user-guide/api-reference.md
@@ -0,0 +1,32 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# API Reference
+
+Generated Javadoc for the public Java API lives at
+<!-- Raw HTML link: MyST resolves relative .html Markdown links as
+     cross-references, which fails sphinx-build -W. The Javadoc tree is
+     copied verbatim via html_extra_path and is unknown to Sphinx. -->
+<a href="../api/index.html"><strong>api/index.html</strong></a>.
+
+The reference covers the `org.apache.datafusion` package, including
+`SessionContext`, `SessionContextBuilder`, `DataFrame`, `CsvReadOptions`,
+`ParquetReadOptions`, and `NativeLibraryLoader`, plus the
+`org.apache.datafusion.proto` helpers. Auto-generated protobuf classes are
+intentionally excluded from the Javadoc — they are an implementation detail.
diff --git a/docs/source/user-guide/index.md b/docs/source/user-guide/index.md
@@ -38,6 +38,7 @@ dataframe
 parquet
 proto-plans
 project-status
+api-reference
 ```
 
 > Early development: no releases yet, API will change. Bug reports and

diff --git a/pom.xml b/pom.xml
@@ -205,6 +205,22 @@ under the License.
                     </execution>
                 </executions>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>3.11.2</version>
+                <configuration>
+                    <source>17</source>
+                    <failOnError>true</failOnError>
+                    <failOnWarnings>false</failOnWarnings>
+                    <doctitle>Apache DataFusion Java ${project.version}</doctitle>
+                    <windowtitle>Apache DataFusion Java ${project.version}</windowtitle>
+                    <links>
+                        <link>https://docs.oracle.com/en/java/javase/17/docs/api/</link>
+                    </links>
+                    <excludePackageNames>datafusion_common:org.apache.datafusion.protobuf</excludePackageNames>
+                </configuration>
+            </plugin>
         </plugins>
     </build>
 </project>