diff --git a/doc/README.txt b/doc/README.txt
index 3b1d49d..fd364bf 100644
--- a/doc/README.txt
+++ b/doc/README.txt
@@ -30,7 +30,7 @@ Examples
 patool extract archive.zip otherarchive.rar
 patool test --verbose dist.tar.gz
 patool list package.deb
-patool create --verbose myfiles.zip file1.txt dir/
+patool create --verbose /path/to/myfiles.zip file1.txt dir/
 patool diff release1.0.tar.gz release2.0.zip
 patool search "def urlopen" python-3.3.tar.gz
 patool repack linux-2.6.33.tar.gz linux-2.6.33.tar.bz2
@@ -40,6 +40,23 @@ Website
 --------
 See http://wummel.github.io/patool/ for more info and downloads.
 
+API
+----
+You can use patool functions from other Python applications.
+Log output will be on sys.stdout and sys.stderr.
+On errors, `PatoolError` will be raised.
+
+```
+import patoolib
+patoolib.extract_archive("archive.zip", outdir="/tmp")
+patoolib.test_archive("dist.tar.gz", verbosity=1)
+patoolib.list_archive("package.deb")
+patoolib.create_archive("/path/to/myfiles.zip", ("file1.txt", "dir/"))
+patoolib.diff_archives("release1.0.tar.gz", "release2.0.zip")
+patoolib.search_archive("def urlopen", "python3.3.tar.gz")
+patoolib.repack_archive("linux-2.6.33.tar.gz", "linux-2.6.33.tar.bz2")
+```
+
 Test suite status
 ------------------
 Patool has extensive unit tests to ensure the code quality.