diff --git a/README.rst b/README.rst
index cbd06ec..b67096d 100644
--- a/README.rst
+++ b/README.rst
@@ -22,7 +22,8 @@ of grepping for string matches.
 The interface and behaviour is designed to match grep and ripgrep as far as it
 makes sense to do so.
 
-Documentation: in the process of migration to readthedocs, see docs/ for now.
+See `the documentation <https://pyastgrep.readthedocs.io/>`_ for more
+information, or the ``docs`` folder.
 
 
 History
diff --git a/docs/conf.py b/docs/conf.py
index 6a730b6..2acd4f8 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -16,6 +16,7 @@
 
 extensions = [
     "sphinx_rtd_theme",
+    "sphinx.ext.intersphinx",
 ]
 
 templates_path = ["_templates"]
@@ -30,3 +31,7 @@
 
 
 pygments_style = "sphinx"
+
+# --- Extensions
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
diff --git a/docs/history.rst b/docs/history.rst
index 6d6181e..848aa41 100644
--- a/docs/history.rst
+++ b/docs/history.rst
@@ -6,6 +6,7 @@ Version 1.3.2 - unreleased
 --------------------------
 
 * Fixed various crashers for permission errors or broken files
+* Documented API for use as a library.
 
 Version 1.3.1 - 2023-07-19
 --------------------------
diff --git a/docs/library.rst b/docs/library.rst
index 7038f83..66745f6 100644
--- a/docs/library.rst
+++ b/docs/library.rst
@@ -5,10 +5,75 @@ Use as a library
 pyastgrep is structured internally to make it easy to use as a library as well
 as a CLI, with a clear separation of the different layers. For now, the
 following API is documented as public and we will strive to maintain backwards
-compatibility with these things:
+compatibility with it:
 
-TODO
+.. currentmodule:: pyastgrep.api
 
+.. function:: search_python_files(paths, expression)
+
+   Searches for files with AST matching the given XPath ``expression``, in the given ``paths``.
+
+   If ``paths`` contains directories, then all Python files in that directory
+   and below will be found, but ``.gitignore`` and other rules are used to
+   ignore files and directories automatically.
+
+   Returns an iterable of :class:`Match` object, plus other objects.
+
+   The other objects are used to indicate errors, usually things like a failure to parse a file that had a ``.py`` extension. The details of these other objects are not being documented yet, so use at own risk, and ensure that you filter the results by doing an ``isinstance`` check for the ``Match`` objects.
+
+   :param paths: List of paths to search, which can be files or directories, of type :class:`pathlib.Path`
+   :type paths: list[pathlib.Path]
+
+   :param expression: XPath expression
+
+   :type expression: str
+
+   :return: Iterable[Match | Any]
+
+
+
+
+.. class:: Match
+
+   Represents a matched AST node. The public properties of this are:
+
+   .. property:: path
+
+      The path of the file containing the match.
+
+      :type: pathlib.Path
+
+   .. property:: position
+
+      The position of the matched AST node within the Python file.
+
+      :type: :class:`Position`
+
+   .. property:: ast_node
+
+      The AST node object matched
+
+      :type: ast.AST
+
+   .. property:: matching_line
+
+      The text of the whole line that matched
+
+      :type: str
+
+.. class:: Position
+
+   .. property:: lineno
+
+      Line number, 1-indexed, as per AST module
+
+      :type: int
+
+   .. property:: col_offset
+
+      Column offset, 0-indexed, as per AST module
+
+      :type: int
 
 
 For other things, we while we will try not to break things without good reason,