Standards compliance

All clients and servers MUST support HTTP 1.0. Clients and servers MAY support later versions of HTTP as well.

HTTP headers

Servers SHOULD set Content-Encoding to the algorithm used to compress the document(s) being served. Recognized algorithms are:

     - "identity"     -- RFC2616 section 3.5
     - "deflate"      -- RFC2616 section 3.5
     - "gzip"         -- RFC2616 section 3.5
     - "x-zstd"       -- The zstandard compression algorithm (www.zstd.net)
     - "x-tor-lzma"   -- The lzma compression algorithm, with a "preset"
                         value no higher than 6.

Clients SHOULD use Accept-Encoding on most directory requests to indicate which of the above compression algorithms they support.

To support older clients, and obsolete software, directory servers MUST also support GET requests to URLs with a “.z” suffix appended.

The semantics are as follows:

  • Clients SHOULD NOT request the .z URL.
  • Clients MUST NOT request a .z URL and include an Accept-Encoding hesder that fails to advertise deflate.
  • If the client does not send an Accept-Encoding header along with a .z URL, the server MUST send the response compressed with deflate and SHOULD NOT send a Content-Encoding header.
  • If the client does send an Accept-Encoding header along with a .z URL, the server SHOULD treat the request the same way as for the URL without the .z. If deflate is included in the Accept-Encoding, the response MUST be encoded, once, with an encoding advertised by the client, and be accompanied by an appropriate Content-Encoding.

Note that these semantics are irreconcilable with the HTTP specifications, and may give rise to malfunctions or inconsistencies when .z URLs are queried by normal, standards-conforming, HTTP clients. This suffix is allowed on all HTTP GET request URLs, except as explicitly noted. It is not supported on any HTTP POST request URLs.

Tor clients started sending Accept-Encoding in 0.3.1.1-alpha, but they still request .z URLs when sending Accept-Encoding. Up until June 2025, Arti requested .z URLs. Other software that sends .z URLs probably also exists.

For all documents, servers MUST support identity and deflate, and SHOULD support x-zstd. Servers SHOULD support serving current/consensus and current/consensus-microdesc with x-tor-lzma compression; this includes consensus diffs.

For all documents, clients MUST support identity and deflate.

For performance reasons, it will usually be necessary for each directory server to precalculate or cache the x-tor-lzma compressed form of the consensus* documents and diffs. For other documents and other compressions: deflate and x-zstd compression are cheap enough that it can be calculated on-the-fly in response to each directory client request.

Note that for anonymous directory requests (that is, requests made over multi-hop circuits, like those for onion service lookups) implementations SHOULD NOT advertise any Accept-Encoding values other than deflate. To do so would be to create a fingerprinting opportunity.

When receiving multiple documents, clients MUST accept compressed concatenated documents and concatenated compressed documents as equivalent.

Servers MAY set the Content-Length: header. When they do, it should match the number of compressed bytes that they are sending.

Servers MAY include an X-Your-Address-Is: header, whose value is the apparent IP address of the client connecting to them (as a dotted quad). For directory connections tunneled over a BEGIN_DIR stream, servers SHOULD report the IP from which the circuit carrying the BEGIN_DIR stream reached them.

Servers SHOULD disable caching of multiple network statuses or multiple server descriptors. Servers MAY enable caching of single descriptors, single network statuses, the list of all server descriptors, a v1 directory, or a v1 running routers document. XXX mention times.

HTTP status codes

Tor delivers the following status codes. Some were chosen without much thought; other code SHOULD NOT rely on specific status codes yet.

  200 -- the operation completed successfully
      -- the user requested statuses or serverdescs, and none of the ones we
         requested were found (0.2.0.4-alpha and earlier).

  304 -- the client specified an if-modified-since time, and none of the
         requested resources have changed since that time.

  400 -- the request is malformed, or
      -- the URL is for a malformed variation of one of the URLs we support,
          or
      -- the client tried to post to a non-authority, or
      -- the authority rejected a malformed posted document, or

  404 -- the requested document was not found.
      -- the user requested statuses or serverdescs, and none of the ones
         requested were found (0.2.0.5-alpha and later).

  503 -- we are declining the request in order to save bandwidth
      -- user requested some items that we ordinarily generate or store,
         but we do not have any available.