diff --git a/docs/api.org b/docs/api.org
index 3c2753255..60ca95768 100644
--- a/docs/api.org
+++ b/docs/api.org
@@ -169,7 +169,41 @@ It is integrated into Helpful, in Doom.
 *** TODO lambda!!
 *** TODO load!
 *** TODO map!
-*** TODO package!
+*** package!
+#+BEGIN_SRC elisp :eval no
+;; To install a package that can be found on ELPA or any of the sources
+;; specified in `doom-core-package-sources':
+(package! evil)
+(package! js2-mode)
+(package! rainbow-delimiters)
+
+;; To disable a package included with Doom (which will no-op all its `after!'
+;; and `use-package!' blocks):
+(package! evil :disable t)
+(package! rainbow-delimiters :disable t)
+
+;; To install a package from a github repo
+(package! so-long :recipe (:host github :repo "hlissner/emacs-so-long"))
+
+;; If a package is particularly big and comes with submodules you don't need,
+;; you can tell the package manager not to clone the repo recursively:
+(package! ansible :recipe (:nonrecursive t))
+
+;; To install a particular branch, commit or tag:
+(package! evil
+  ;; if :host and :fetcher aren't specified, the package manager will fall back
+  ;; to evil's default source provided by their (M)ELPA recipes:
+  :recipe (:commit "e7bc39de2f961505e8e112da8c1b315ae8afce52"))
+
+(package! evil :recipe (:branch "stable"))
+
+(package! evil :recipe (:tag "1.2.9"))
+
+;; If you share your config between two computers, and don't want bin/doom
+;; refresh to delete packages used only on one system, use :ignore
+(package! evil :ignore (not (equal system-name "my-desktop")))
+#+END_SRC
+
 *** TODO pushnew!
 *** TODO quiet!
 *** remove-hook!