What is a Payload in an API? JSON, XML, Examples

What is a payload in an API?

An API payload is the data a request or response actually carries in its body, as opposed to the URL, method, headers and status code that describe it. A POST that creates a user has that user's JSON as its payload; a GET response has the requested resource as its payload. It is the part your application code reads, validates and stores.

The word comes from networking, where it meant the cargo of a packet as opposed to its routing headers. Headers tell the server how to read the message; the payload is the message.

Where the payload sits in an HTTP message

An HTTP message is a start line, headers, an empty line and then the body. The body holds the payload.

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 73
Authorization: Bearer xyz123

{
  "name": "Alice",
  "email": "alice@example.com",
  "role": "member"
}

Everything above the empty line is metadata. The JSON object below it is the payload. Which methods carry one:

• POST, PUT and PATCH normally send a request payload, because their job is to send data to the server.
• GET, HEAD and DELETE normally have no request body. Parameters travel in the path or query string instead (how parameters are sent in an HTTP POST request shows the difference).
• Responses usually carry a payload too. The exceptions are responses with no content, such as 204 and 304.

Common payload formats

• JSON is the default for most REST APIs: readable, and supported by every language. See what JSON is.
• XML is older and more verbose, and still common in SOAP and enterprise integrations.
• application/x-www-form-urlencoded is what plain HTML forms send: name=Alice&role=member.
• multipart/form-data combines form fields and files in one request. See multipart/form-data.
• Binary (application/octet-stream, image/png) carries raw bytes such as downloads and images.
• Protocol Buffers and MessagePack are compact binary encodings used by gRPC and performance-sensitive APIs. They are smaller than JSON but unreadable without decoding.

The Content-Type header declares which of these the payload is. If it is missing or wrong, the receiver parses the body the wrong way.

Payload size and limits

• Servers cap request bodies. nginx, for example, defaults client_max_body_size to 1m and answers 413 when a body is larger. RFC 9110 now names that status "Content Too Large".
• Big payloads cost time and memory. Many servers buffer the whole body before processing it, so large bodies raise memory use and latency under concurrency.
• Compress text payloads. gzip or brotli (negotiated with Accept-Encoding and Content-Encoding) usually shrinks JSON a lot, though the saving depends on the data.
• Do not return everything. Return large collections a page at a time. See API pagination.

Validate every payload you receive

• Check the structure against a schema (JSON Schema, Zod, Pydantic) and reject what does not match.
• Enforce a maximum size so one huge request cannot exhaust memory.
• Check types and ranges, and allow only the fields you expect. Otherwise a client can slip in "role": "admin" (mass assignment).
• Take the caller's identity from authentication, never from an ID inside the payload.

Common mistakes

• Missing or wrong Content-Type. Send Content-Type: application/json with JSON bodies.
• Charset mismatches. Use UTF-8 end to end, or accented characters and emoji arrive garbled.
• JSON inside a JSON string. Stringified JSON in a field must be escaped once, not twice.
• Logging whole payloads. Passwords, tokens and personal data end up in your log store. Filter sensitive fields first.
• Sending a body with GET. HTTP gives it no defined meaning, so servers and proxies may ignore or reject it.

Payloads in load testing and monitoring

A test that posts {"k":"v"} measures very little. Parsing, validation and database writes all scale with payload size and shape, so use bodies that look like production traffic and vary them per virtual user (see data-driven load testing scripts). Also test just under and just over the size limit, and expect a clean 413 rather than a 500. In API testing, assert on the response body, not only the status code.

LoadFocus runs your JMeter and k6 scripts from 25 cloud regions (load testing), and you can start from a cURL command with the steps in turning cURL, HAR, Postman or OpenAPI into a load test. For ongoing checks, API monitoring can assert on status code, response body, headers and response time. To send a one-off payload from the browser, use the free curl online tool, and see the curl command entry for the flags.

FAQ: API payloads

Is the URL part of the payload?

No. The path and query string are metadata that identify the resource. The payload is the body.

Do GET requests have payloads?

Not in practice. HTTP defines no meaning for a GET body, so many servers and proxies ignore it. Use path or query parameters for GET.

What is the difference between payload and body?

They are close to synonyms. The body is the HTTP term for the bytes after the headers; payload is the everyday term for the meaningful data inside it.

Can a response have no payload?

Yes. 204 No Content and 304 Not Modified responses have no body, and a DELETE often returns 204.

What is the maximum payload size?

It is set by the server, proxy or gateway in front of your API, not by HTTP. nginx defaults to 1m, so check the limit at each layer and configure it for your use case.

How do I test API payloads under load?

Use a tool that can parameterize bodies per virtual user, such as JMeter or k6, and send realistic sizes and shapes instead of minimal placeholders.