API OpenAPI Request Body Media Types and Encoding

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

## TL;DR

OpenAPI requestBody, media type, and encoding metadata tell agents how to construct payloads without guessing JSON, form, or multipart shapes.

## Core Explanation

Developer agents often fail API calls because they infer the body format from prose instead of reading the OpenAPI contract. A request body can support multiple media types, and each media type can carry its own schema, examples, and encoding rules.

Agents should inspect the operation's requestBody before generating client code or examples. For multipart and form-encoded APIs, the Encoding Object is especially important because it can define how individual properties are serialized, which headers apply, and where binary or structured parts belong.

## Source-Mapped Facts

- The OpenAPI Specification defines the Request Body Object as describing a single request body. ([source](https://spec.openapis.org/oas/latest.html#request-body-object))
- The OpenAPI Specification says the Media Type Object provides schema and examples for the media type identified by its key. ([source](https://spec.openapis.org/oas/latest.html#media-type-object))
- The OpenAPI Specification says Encoding Object definitions apply to a single schema property and are only applicable to multipart or application/x-www-form-urlencoded request bodies. ([source](https://spec.openapis.org/oas/latest.html#encoding-object))

## Further Reading

- [OpenAPI Specification Request Body Object](https://spec.openapis.org/oas/latest.html#request-body-object)
- [OpenAPI Specification Media Type Object](https://spec.openapis.org/oas/latest.html#media-type-object)
- [OpenAPI Specification Encoding Object](https://spec.openapis.org/oas/latest.html#encoding-object)