Skip to main content

​
How an agent asks

The link answers by what the request asks for:
A password-protected link answers 401 with the code password_required until the password is sent. An agent sends it in the x-viewer-password header on every request, the index and each file alike:
An expired link answers 410 and a revoked one 403, the same as for a person. The deck’s HTML also points at the index. When the viewer adds its bar, notes or forms to a page, it adds in the page’s <head> a <link rel="alternate" type="text/markdown" href="/v/<secret>/?format=agent"> and a comment naming ?format=agent and ?format=json, so an agent that received the HTML anyway finds its way.

​
What the index holds

  • The deck’s title and kind, the version the link serves, and whether the link follows the latest version or is pinned to one.
  • What the link allows: downloads, annotations, form submissions, PDF export, and the expiry date.
  • The entry document, with its size and type, and the ?raw URL that returns it byte for byte.
  • The deck’s AGENT.md, inlined (up to 64 KB; a longer file is cut and its full URL given). A deck without one says so. See Deck self-description.
  • Every file of the deck with its size, its type and its absolute URL.
  • When the link allows downloads and the version carries files, the list of those files and the URL of the zip that holds them all.
  • The URLs of the markdown and JSON forms of the index.
The JSON form carries the same facts as fields: deck, version, link, agentDoc, entry, files, downloads (null when the link does not allow them or the version has none) and zipUrl, plus index with the two URLs.

​
What it never holds

The index says nothing the link does not already hand out. Every URL in it is one the same link opens anyway. A link with downloads off has no downloads section at all and no download address; the deck’s own AGENT.md is inlined as written, so whatever it says about its files is what the author wrote. The index never shows the deck’s owner, the workspace, the other links, or the other versions.

​
Counting and search engines

An index read counts on the link as an agent read (agentReadCount on the API), apart from its views: it never adds a view, never records a view event, and sets no cookie. HEAD requests and the dashboard’s own previews never count. See Link analytics. The deck, its files and the index all carry X-Robots-Tag: noindex, nofollow, so a link that leaks into a public page is not indexed by search engines.