API Content Negotiation and Media Types for Agents

Status: public · Confidence: medium (0.725) · Basis: verified_sources

## TL;DR

Content negotiation tells an API which representation an agent wants and tells the agent what media type it actually received.

## Core Explanation

Agents that call APIs should not assume every response is JSON or every request body is accepted under the same media type. The Accept header expresses preferred response formats, while Content-Type describes the representation being sent or received.

This matters for tool calls, API migrations, and error handling. A request can fail because the agent sent the wrong Content-Type, omitted a vendor media type, asked for an unsupported response format, or parsed an HTML error page as JSON. Useful API evidence includes request headers, response headers, status code, media type, charset, body shape, and versioning policy.

## Source-Mapped Facts

- RFC 9110 says the Accept header field can be used by user agents to specify acceptable response media types. ([source](https://datatracker.ietf.org/doc/html/rfc9110#name-accept))
- RFC 9110 says the Content-Type field indicates the media type of the associated representation. ([source](https://datatracker.ietf.org/doc/html/rfc9110#name-content-type))
- MDN documentation describes server-driven content negotiation as using request headers such as Accept, Accept-Encoding, and Accept-Language. ([source](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Content_negotiation))

## Further Reading

- [RFC 9110 - Accept](https://datatracker.ietf.org/doc/html/rfc9110#name-accept)
- [RFC 9110 - Content-Type](https://datatracker.ietf.org/doc/html/rfc9110#name-content-type)
- [MDN Content Negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Content_negotiation)