diff --git a/docs/index.rst b/docs/index.rst
index f86ee22..0b7aa8b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,19 +1,37 @@
 .. _swh-web-client:
 
 Software Heritage - Web client
 ==============================
 
 Client for Software Heritage Web applications, via their APIs.
 
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+Sample usage
+------------
+
+.. code-block:: python
+
+   from swh.web.client import WebAPIClient
+   cli = WebAPIClient()
+
+   # retrieve any archived object via its PID
+   cli.get('swh:1:rev:aafb16d69fd30ff58afdd69036a26047f3aebdc6')
+
+   # same, but for specific object types
+   cli.revision('swh:1:rev:aafb16d69fd30ff58afdd69036a26047f3aebdc6')
 
+   # get() always retrieve entire objects, following pagination
+   # WARNING: this might *not* be what you want for large objects
+   cli.get('swh:1:snp:6a3a2cf0b2b90ce7ae1cf0a221ed68035b686f5a')
 
-Indices and tables
-==================
+   # type-specific methods support explicit iteration through pages
+   next(cli.snapshot('swh:1:snp:cabcc7d7bf639bbe1cc3b41989e1806618dd5764'))
+
+
+API Reference
+-------------
+
+.. toctree::
+   :maxdepth: 2
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   /apidoc/swh.web.client