diff --git a/docs/api.rst b/docs/api.rst
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -36,9 +36,9 @@
 identify vault objects. The syntax and meaning of ``:objectid`` for the
 different object kinds is detailed below.
 
-Optionally, a third parameter, ``:format``, can be used (when multiple formats
-are supported) to specify the format of the resulting bundle when needed. The
-URL fragment becomes then ``:objectkind/:objectid/:format``.
+In the case of revisions, a third parameter, ``:format``, must be used to
+specify the format of the resulting bundle. The URL fragment becomes then
+``:objectkind/:objectid/:format``.
 
 
 Directories
@@ -103,8 +103,8 @@
 before it can be retrieved. Cooking is idempotent, and a no-op in between a
 previous cooking operation and expiration.
 
-.. http:post:: /vault/:objectkind/:objectid/:format
-.. http:get:: /vault/:objectkind/:objectid/:format
+.. http:post:: /vault/:objectkind/:objectid[/:format]
+.. http:get:: /vault/:objectkind/:objectid[/:format]
 
     **Request body**: optionally, an ``email`` POST parameter containing an
     e-mail to notify when the bundle cooking has ended.
@@ -166,7 +166,7 @@
 
 Retrieve a specific bundle from the vault with:
 
-.. http:get:: /vault/:objectkind/:objectid/:format/raw
+.. http:get:: /vault/:objectkind/:objectid[/:format]/raw
 
    Where ``:format`` is optional, depending on the object kind.