Content-Location content response

What it does

Content-Location provides a URL for the specific content that was returned in the response body. It answers the question: "if I want to fetch exactly this representation again, what URL do I use?"

This is subtly different from the request URL (which might be a generic endpoint like /api/users) and completely different from Location (which redirects you somewhere else). Content-Location is saying "the content you just received lives at this canonical URL."

Syntax

Content-Location: <url>

The value can be an absolute URL or a path relative to the request URL.

Examples:

Content-Location: /documents/foo.json
Content-Location: https://api.example.com/users/42
Content-Location: /api/users/42

The key distinction: Content-Location vs Location

These two headers are frequently confused:

Location changes where the client goes next. Content-Location labels what was just returned.

When it's actually useful

Content negotiation. When a server supports multiple formats at the same URL (e.g., /document returns JSON or XML based on Accept), Content-Location can specify the format-specific URL:

GET /document HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /document.json
Vary: Accept

POST that returns the created resource. A common REST pattern: POST to create a resource, and the server returns the created resource in the response body. Content-Location tells the client the URL of what was just created without requiring a separate GET:

POST /api/users HTTP/1.1

HTTP/1.1 201 Created
Location: /api/users/42
Content-Location: /api/users/42
Content-Type: application/json

{"id": 42, "name": "Sainesh"}

Here, Location says "resource created at this URL," and Content-Location confirms "the body I'm returning is that resource." Subtly, Location on a 201 means "go there if you want the resource"; Content-Location means "I'm already giving it to you right now."

Cacheable PUT responses. If a PUT response includes Content-Location matching the request URL, it signals that the response body is a valid cached representation of the resource at that URL.

Common mistakes and gotchas

Confusing it with Location on redirects. Content-Location is not a redirect. Never use it on 3xx responses to indicate where to go — that's Location's job. Content-Location on a 301/302 would be bizarre and probably ignored.

Using absolute URLs when relative would do. Relative paths are cleaner and more portable. /api/users/42 is better than https://api.example.com/api/users/42 unless you're explicitly pointing to a different origin.

Ignoring it on the client side. Many HTTP clients and frameworks ignore Content-Location entirely and just use the request URL for caching. If you're relying on Content-Location for cache key disambiguation, verify your client actually honours it.

Real-world examples

Content negotiation — client gets JSON, told the JSON-specific URL:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /reports/q1-2026.json
Vary: Accept

POST returning created resource:

HTTP/1.1 201 Created
Location: /api/orders/789
Content-Location: /api/orders/789
Content-Type: application/json

{"id": 789, "status": "pending", "total": 4999}

FAQ

Is Content-Location commonly used?

Not widely. It's one of the lesser-used HTTP headers in practice — most APIs don't implement content negotiation at a level where it matters, and POST-201 patterns often just use Location. You'll see it more in well-designed hypermedia APIs and document-centric systems.

Can Content-Location point to a different domain?

Technically yes, the spec doesn't prohibit it. But this would be unusual and potentially confusing — it implies the canonical content lives on a different server, which has caching and trust implications. In practice, keep Content-Location on the same origin.

Does Content-Location affect caching?

It can. If Content-Location matches the request URL, it reinforces that the response is a cacheable representation of that URL. If it points to a different URL, it tells the cache "this response is a valid representation for that URL too." Whether a specific cache implementation honours this is another matter.

Fun fact

Content-Location is one of those headers that's theoretically elegant — it solves a real problem in content negotiation — but rarely used because the web largely solved content negotiation differently (separate URLs per format, file extensions, API versioning in the URL). The header persists in the spec as a testament to HTTP's original vision of a web where format negotiation was transparent to users.