diff --git a/swh/web/ui/templates/includes/apidoc-header.html b/swh/web/ui/templates/includes/apidoc-header.html
index 0a190cf6..736eee5b 100644
--- a/swh/web/ui/templates/includes/apidoc-header.html
+++ b/swh/web/ui/templates/includes/apidoc-header.html
@@ -1,100 +1,107 @@
 <p>This document describes the <strong>Software Heritage Web API</strong>.</p>
 <ul>
 <li>
 <a href="{{ url_for('browse_api_doc') }}#endpoint-index">Endpoint index</a>
 </li>
 <li>
 <a href="{{ url_for('browse_api_doc') }}#data-model">Data model</a>
 </li>
 <li>
 <a href="{{ url_for('browse_api_doc') }}#version">Version</a>
 </li>
 <li>
 <a href="{{ url_for('browse_api_doc') }}#schema">Schema</a>
 </li>
 <li>
 <a href="{{ url_for('browse_api_doc') }}#parameters">Parameters</a>
 </li>
 <li>
 <a href="{{ url_for('browse_api_doc') }}#errors">Errors</a>
 </li>
 <li>
 <a href="{{ url_for('browse_api_doc') }}#pagination">Pagination</a>
 </li>
 <li>
 <a href="{{ url_for('browse_api_doc') }}#errors">Rate limiting</a>
 </li>
 </ul>
 <h3 id="endpoint-index">Endpoint index</h3>
 <p>You can jump directly to the <strong><a href="/api/1/">endpoint index</a></strong>, which lists all available API functionalities, or read on for more general information about the API.</p>
 <h3 id="data-model">Data model</h3>
 <p>The <a href="https://www.softwareheritage.org/">Software Heritage</a> project harvests publicly available source code by tracking software distribution channels such as version control systems, tarball releases, and distribution packages.</p>
 <p>All retrieved source code and related metadata are stored in the Software Heritage archive, that is conceptually a <a href="https://en.wikipedia.org/wiki/Merkle_tree">Merkle DAG</a>. All nodes in the graph are content-addressable, i.e., their node identifiers are computed by hashing their content and, transitively, that of all nodes reachable from them; and no node or edge is ever removed from the graph: the Software Heritage archive is an append-only data structure.</p>
 <p>The following types of objects (i.e., graph nodes) can be found in the Software Heritage archive <small>(for more information see the <a href="https://wiki.softwareheritage.org/index.php?title=Glossary">Software Heritage glossary</a>)</small>:</p>
 <ul>
 <li><strong>Content</strong>: a specific version of a file stored in the archive, identified by its cryptographic hashes (currently: SHA1, Git-like &quot;salted&quot; SHA1, SHA256). Note that content objects are nameless; their names are context-dependent and stored as part of directory entries (see below).<br /> <em>Also known as:</em> &quot;blob&quot;</li>
 <li><strong>Directory</strong>: a list of directory entries, where each entry can point to content objects (&quot;file entries&quot;), revisions (&quot;revision entries&quot;), or transitively to other directories (&quot;directory entries&quot;). All entries are associated to the local name of the entry (i.e., a relative path without any path separator) and permission metadata (e.g., chmod value or equivalent).</li>
 <li><strong>Revision</strong>: a point in time snapshot of the content of a directory, together with associated development metadata (e.g., author, timestamp, log message, etc).<br /> <em>Also known as:</em> &quot;commit&quot;.</li>
 <li><strong>Release</strong>: a revision that has been marked as noteworthy with a specific name (e.g., a version number), together with associated development metadata (e.g., author, timestamp, etc).<br /> <em>Also known as:</em> &quot;tag&quot;</li>
 <li><strong>Origin</strong>: an Internet-based location from which a coherent set of objects (contents, revisions, releases, etc.) archived by Software Heritage has been obtained. Origins are currently identified by URLs.</li>
 </ul>
 <h3 id="version">Version</h3>
 <p>The current version of the API is <strong>v1</strong>.</p>
 <h3 id="schema">Schema</h3>
 <p>API access is over HTTPS.</p>
 <p>All API endpoints are rooted at <a href="https://archive.softwareheritage.org/api/1/" class="uri">https://archive.softwareheritage.org/api/1/</a>.</p>
 <p>Data is sent and received as JSON by default.</p>
 <p>Example:</p>
 <ul>
 <li><p>from the command line:</p>
 <pre class="shell"><code>curl -i https://archive.softwareheritage.org/api/1/stat/counters/</code></pre></li>
 </ul>
 <h4 id="response-format-override">Response format override</h4>
 <p>The response format can be overridden using the <code>Accept</code> request header. In particular, <code>Accept: text/html</code> (that web browsers send by default) requests HTML pretty-printing, whereas <code>Accept: application/yaml</code> requests YAML-encoded responses.</p>
 <p>Example:</p>
 <ul>
 <li><a href="/api/1/stat/counters/" class="uri">/api/1/stat/counters/</a></li>
 <li><p>from the command line:</p>
 <pre class="shell"><code>curl -i -H &#39;Accept: application/yaml&#39; https://archive.softwareheritage.org/api/1/stat/counters/</code></pre></li>
 </ul>
 <h3 id="parameters">Parameters</h3>
 <p>Some API endpoints can be tweaked by passing optional parameters. For GET requests, optional parameters can be passed as an HTTP query string.</p>
 <p>The optional parameter <code>fields</code> is accepted by all endpoints that return dictionaries and can be used to restrict the list of fields returned by the API, in case you are not interested in all of them. By default, all available fields are returned.</p>
 <p>Example:</p>
 <ul>
 <li><a href="/api/1/stat/counters/?fields=content,directory,revision" class="uri">/api/1/stat/counters/?fields=content,directory,revision</a></li>
 <li><p>from the command line:</p>
 <pre class="shell"><code>curl https://archive.softwareheritage.org/api/1/stat/counters/?fields=content,directory,revision</code></pre></li>
 </ul>
 <h3 id="errors">Errors</h3>
 <p>While API endpoints will return different kinds of errors depending on their own semantics, some error patterns are common across all endpoints.</p>
 <p>Sending malformed data, including syntactically incorrect object identifiers, will result in a <code>400 Bad Request</code> HTTP response. Example:</p>
 <ul>
 <li><a href="/api/1/content/deadbeef/" class="uri">/api/1/content/deadbeef/</a> (client error: &quot;deadbeef&quot; is too short to be a syntactically valid object identifier)</li>
 <li><p>from the command line:</p>
 <pre class="shell"><code>curl -i https://archive.softwareheritage.org/api/1/content/deadbeef/</code></pre></li>
 </ul>
 <p>Requesting non existent resources will result in a <code>404 Not Found</code> HTTP response. Example:</p>
 <ul>
 <li><a href="/api/1/content/0123456789abcdef0123456789abcdef01234567/" class="uri">/api/1/content/0123456789abcdef0123456789abcdef01234567/</a> (error: no object with that identifier is available [yet?])</li>
 <li><p>from the command line:</p>
 <pre class="shell"><code>curl -i https://archive.softwareheritage.org/api/1/content/04740277a81c5be6c16f6c9da488ca073b770d7f/</code></pre></li>
 </ul>
 <h3 id="pagination">Pagination</h3>
-<p>Foo bar</p>
+<p>Some requests which return multiple items will be paginated to 10 items by default. You can specify further results per page with the <code>?per_page</code> parameter (up to 50 results per page).</p>
+<p>Example:</p>
+<pre class="shell"><code>curl https://archive.softwareheritage.org/api/1/origin/1/visits/?per_page=2</code></pre>
+<h4 id="link-header">Link Header</h4>
+<p>To navigate through results, a 'Link' header is returned in the response. That Link header includes pagination information.</p>
+<p>Example:</p>
+<pre class="text"><code>Link: &lt;/api/1/origin/1/visits/?last_visit=2&amp;per_page=2&gt;; rel=&quot;next&quot;,</code></pre>
+<p>The possible 'rel' value is 'next' to indicate the immediate next page of results.</p>
 <h3 id="rate-limiting">Rate limiting</h3>
 <p>Due to limited resource availability on the back end side, API usage is currently rate limited. Furthermore, as API usage is currently entirely anonymous (i.e., without any authentication), API &quot;users&quot; are currently identified by their origin IP address.</p>
 <p>Three HTTP response fields will inform you about the current state of limits that apply to your current rate limiting bucket:</p>
 <ul>
 <li><code>X-RateLimit-Limit</code>: maximum number of permitted requests per hour</li>
 <li><code>X-RateLimit-Remaining</code>: number of permitted requests remaining before the next reset</li>
 <li><code>X-RateLimit-Reset</code>: the time (expressed in <a href="https://en.wikipedia.org/wiki/Unix_time">Unix time</a> seconds) at which the current rate limiting will expire, resetting to a fresh <code>X-RateLimit-Limit</code></li>
 </ul>
 <p>Example:</p>
 <ul>
 <li><p>from the command line:</p>
 <pre><code>curl -i https://archive.softwareheritage.org/api/1/stat/counters/ | grep ^X-RateLimit
 X-RateLimit-Limit: 60
 X-RateLimit-Remaining: 54
 X-RateLimit-Reset: 1485794532</code></pre></li>
 </ul>
diff --git a/swh/web/ui/templates/includes/apidoc-header.md b/swh/web/ui/templates/includes/apidoc-header.md
index 82663fc5..529eddea 100644
--- a/swh/web/ui/templates/includes/apidoc-header.md
+++ b/swh/web/ui/templates/includes/apidoc-header.md
@@ -1,172 +1,194 @@
 This document describes the <strong>Software Heritage Web API</strong>.
 
 <ul>
   <li><a href="{{ url_for('browse_api_doc') }}#endpoint-index">Endpoint index</a></li>
   <li><a href="{{ url_for('browse_api_doc') }}#data-model">Data model</a></li>
   <li><a href="{{ url_for('browse_api_doc') }}#version">Version</a></li>
   <li><a href="{{ url_for('browse_api_doc') }}#schema">Schema</a></li>
   <li><a href="{{ url_for('browse_api_doc') }}#parameters">Parameters</a></li>
   <li><a href="{{ url_for('browse_api_doc') }}#errors">Errors</a></li>
   <li><a href="{{ url_for('browse_api_doc') }}#pagination">Pagination</a></li>
   <li><a href="{{ url_for('browse_api_doc') }}#errors">Rate limiting</a></li>
 </ul>
 
 ### Endpoint index
 
 You can jump directly to the <strong><a href="/api/1/">endpoint
 index</a></strong>, which lists all available API functionalities, or read on
 for more general information about the API.
 
 
 ### Data model
 
 The [Software Heritage](https://www.softwareheritage.org/) project harvests
 publicly available source code by tracking software distribution channels such
 as version control systems, tarball releases, and distribution packages.
 
 All retrieved source code and related metadata are stored in the Software
 Heritage archive, that is conceptually
 a [Merkle DAG](https://en.wikipedia.org/wiki/Merkle_tree). All nodes in the
 graph are content-addressable, i.e., their node identifiers are computed by
 hashing their content and, transitively, that of all nodes reachable from them;
 and no node or edge is ever removed from the graph: the Software Heritage
 archive is an append-only data structure.
 
 The following types of objects (i.e., graph nodes) can be found in the Software
 Heritage archive <small>(for more information see
 the
 [Software Heritage glossary](https://wiki.softwareheritage.org/index.php?title=Glossary))</small>:
 
 - **Content**: a specific version of a file stored in the archive, identified
   by its cryptographic hashes (currently: SHA1, Git-like "salted" SHA1,
   SHA256). Note that content objects are nameless; their names are
   context-dependent and stored as part of directory entries (see below).<br />
   *Also known as:* "blob"
 - **Directory**: a list of directory entries, where each entry can point to
   content objects ("file entries"), revisions ("revision entries"), or
   transitively to other directories ("directory entries"). All entries are
   associated to the local name of the entry (i.e., a relative path without any
   path separator) and permission metadata (e.g., chmod value or equivalent).
 - **Revision**: a point in time snapshot of the content of a directory,
   together with associated development metadata (e.g., author, timestamp, log
   message, etc).<br />
   *Also known as:* "commit".
 - **Release**: a revision that has been marked as noteworthy with a specific
   name (e.g., a version number), together with associated development metadata
   (e.g., author, timestamp, etc).<br />
   *Also known as:* "tag"
 - **Origin**: an Internet-based location from which a coherent set of objects
   (contents, revisions, releases, etc.) archived by Software Heritage has been
   obtained. Origins are currently identified by URLs.
 
 
 ### Version
 
 The current version of the API is **v1**.
 
 
 ### Schema
 
 API access is over HTTPS.
 
 All API endpoints are rooted at <https://archive.softwareheritage.org/api/1/>.
 
 Data is sent and received as JSON by default.
 
 Example:
 
 - from the command line:
 ``` shell
 curl -i https://archive.softwareheritage.org/api/1/stat/counters/
 ```
 
 #### Response format override
 
 The response format can be overridden using the `Accept` request header. In
 particular, `Accept: text/html` (that web browsers send by default) requests
 HTML pretty-printing, whereas `Accept: application/yaml` requests YAML-encoded
 responses.
 
 Example:
 
 - [/api/1/stat/counters/](/api/1/stat/counters/)
 - from the command line:
 ``` shell
 curl -i -H 'Accept: application/yaml' https://archive.softwareheritage.org/api/1/stat/counters/
 ```
 
 ### Parameters
 
 Some API endpoints can be tweaked by passing optional parameters. For GET
 requests, optional parameters can be passed as an HTTP query string.
 
 The optional parameter `fields` is accepted by all endpoints that return
 dictionaries and can be used to restrict the list of fields returned by the
 API, in case you are not interested in all of them. By default, all available
 fields are returned.
 
 Example:
 
 - [/api/1/stat/counters/\?fields\=content,directory,revision](/api/1/stat/counters/?fields=content,directory,revision)
 - from the command line:
 ``` shell
 curl https://archive.softwareheritage.org/api/1/stat/counters/?fields=content,directory,revision
 ```
 
 
 ### Errors
 
 While API endpoints will return different kinds of errors depending on their
 own semantics, some error patterns are common across all endpoints.
 
 Sending malformed data, including syntactically incorrect object identifiers,
 will result in a `400 Bad Request` HTTP response. Example:
 
 - [/api/1/content/deadbeef/](/api/1/content/deadbeef/) (client error:
   "deadbeef" is too short to be a syntactically valid object identifier)
 - from the command line:
 ``` shell
 curl -i https://archive.softwareheritage.org/api/1/content/deadbeef/
 ```
 
 Requesting non existent resources will result in a `404 Not Found` HTTP
 response. Example:
 
 - [/api/1/content/0123456789abcdef0123456789abcdef01234567/](/api/1/content/0123456789abcdef0123456789abcdef01234567/)
   (error: no object with that identifier is available [yet?])
 - from the command line:
 ``` shell
 curl -i https://archive.softwareheritage.org/api/1/content/04740277a81c5be6c16f6c9da488ca073b770d7f/
 ```
 
 
 ### Pagination
 
-Foo bar
+Some requests which return multiple items will be paginated to 10
+items by default. You can specify further results per page with the
+`?per_page` parameter (up to 50 results per page).
+
+Example:
+
+``` shell
+curl https://archive.softwareheritage.org/api/1/origin/1/visits/?per_page=2
+```
+
+#### Link Header
+
+To navigate through results, a 'Link' header is returned in the
+response.  That Link header includes pagination information.
+
+Example:
+
+``` text
+Link: </api/1/origin/1/visits/?last_visit=2&per_page=2>; rel="next",
+```
+
+The possible 'rel' value is 'next' to indicate the immediate next page
+of results.
 
 
 ### Rate limiting
 
 Due to limited resource availability on the back end side, API usage is
 currently rate limited.  Furthermore, as API usage is currently entirely
 anonymous (i.e., without any authentication), API "users" are currently
 identified by their origin IP address.
 
 Three HTTP response fields will inform you about the current state of limits
 that apply to your current rate limiting bucket:
 
 - `X-RateLimit-Limit`: maximum number of permitted requests per hour
 - `X-RateLimit-Remaining`: number of permitted requests remaining before the
   next reset
 - `X-RateLimit-Reset`: the time (expressed
   in [Unix time](https://en.wikipedia.org/wiki/Unix_time) seconds) at which the
   current rate limiting will expire, resetting to a fresh `X-RateLimit-Limit`
 
 Example:
 
 - from the command line:
 
         curl -i https://archive.softwareheritage.org/api/1/stat/counters/ | grep ^X-RateLimit
         X-RateLimit-Limit: 60
         X-RateLimit-Remaining: 54
         X-RateLimit-Reset: 1485794532