llms.txt

HTTP Headers

Snaps use the media type application/vnd.farcaster.snap+json. Clients and servers coordinate snap responses with Accept, Content-Type, Vary, Link, and optionally X-Snap-Payload on GET requests.

The spec has one goal: a snap URL must never be silently missed. Any HTTP client performing a plain GET must be able to identify a snap — without knowing in advance to ask for snap content.

Accept (requests)

A client MAY include application/vnd.farcaster.snap+json in the Accept header to indicate snap support.

  • If application/vnd.farcaster.snap+json is the highest-priority acceptable type, the server MUST return a snap response.
  • If the request does not indicate snap support, the server SHOULD return valid HTML (not snap), so that shared links render for users who open them in a browser.
  • If the request does not indicate snap support and snap is the only representation the server supports, the server MUST return the snap directly — it has no valid alternative.

Content-Type (responses)

A snap response MUST set Content-Type: application/vnd.farcaster.snap+json, and a client receiving that Content-Type MUST render the body as a snap.

X-Snap-Payload (requests)

On GET, a client MAY send optional viewer-authentication data as a JFS compact string in the X-Snap-Payload header. See Authentication — Authenticated GETs.

Vary (responses)

When the representation depends on Accept, the server MUST include Vary: Accept so caches and intermediaries key correctly.

Snap servers that return snap JSON SHOULD also include Vary: X-Snap-Payload when they support authenticated GETs, so caches distinguish anonymous and viewer-specific representations.

When a snap response depends on viewer identity (action.user from GET or POST), the server SHOULD set Cache-Control: private or a short max-age together with Vary: X-Snap-Payload to avoid leaking personalized content between viewers.

A URL that is available as a snap MUST be discoverable on a plain GET. A server satisfies this in one of two ways:

  1. Return the snap directly with Content-Type: application/vnd.farcaster.snap+json, or

  2. Return HTML with a Link header advertising the snap as an alternate:

    Link: </resource>; rel="alternate"; type="application/vnd.farcaster.snap+json"

The only non-compliant pattern is HTML without a Link header — such a URL is invisible to any client that did not already know to ask for snap content.

Caching

Clients MAY cache GET responses from snap servers to avoid extraneous re-fetching.