Overview

Content-Location gives a specific URL where the exact representation just returned can be accessed directly. It points to the canonical address of the particular representation chosen by content negotiation.

For example, if `/articles/42` negotiated a JSON response, the server can advertise `/articles/42.json` — the address of that JSON representation itself — via Content-Location.

Details

It is easily confused with Location, but their roles are entirely different. Location points to a resource to navigate to or reference (3xx redirects, 201 Created), whereas Content-Location describes which URL the current response body is a representation of. Location is a navigation directive; Content-Location is metadata.

It shines with content negotiation (language, format, encoding). When a negotiable URL (`/report`) has several representations, exposing each negotiated result's stable direct URL (`/report.ko.html`, `/report.en.pdf`) via Content-Location helps caching, bookmarking, and sharing.

Per the spec, when Content-Location differs from the request URL, the body should be interpreted as a representation of the resource named by Content-Location, not the request URL. Because of this subtle semantic, misusing it on PATCH/PUT responses can make caches attribute the body to the wrong URL, so use it carefully.

Syntax

Content-Location: <url>

e.g. Content-Location: /articles/42.json

Notes

• Don't confuse Location (navigation / created-resource location) with Content-Location (address of the current representation). A 201 Created may carry both, with different meanings.
• Adding Content-Location may let some caches store the body as a representation of that URL too, so use it only when that URL genuinely yields the same body.
• Relative URLs are allowed and resolved against the request URL; an absolute URL reduces ambiguity.

Related headers

Related status codes

Specification