Endpoints that send a body (POST, PUT, PATCH) have a Format toggle at the top of the Body Parameters section with two options: Key / Value and Nested JSON. They differ in the editor you get and in how HuxxConnect processes the values before sending — choosing the wrong one is the most common reason a write request is rejected.

Quick version:

• Key / Value (default): repeater rows. Values are type-coerced (true → boolean, 42 → number, ["a"] → array). Flat bodies only — a nested object typed into a row is sent as a string.
• Nested JSON: a JSON textarea. The document is sent exactly as written — no coercion, no flattening. Required for nested structures.
• In Nested JSON mode, API-level Default Body Parameters are not merged in; runtime body_variables merge at the top level only.
• The toggle is separate from Body Encoding (JSON / URL Encoded / Multipart / Raw / None), and hidden for Multipart.

Key / Value: the default repeater#

Key / Value stores the body as rows of key and value, edited in the same repeater UI as query parameters. At request time the rows are flattened into one object and each string value is coerced to its natural type (src/Http/RequestBuilder.php), so with JSON encoding the wire format is correct:

That last row is the trap: Key / Value cannot express a nested object. If a field’s value must itself be an object, switch to Nested JSON.

Example — rows title = Test Product, price = 42, in_stock = true on a POST endpoint with path /products/add:

{"title":"Test Product","price":42,"in_stock":true}

New to APIs? Read this first

The request body is the data payload of a write request — the fields of the record you are creating or updating, usually formatted as JSON. Reads (GET) have no body. See What is an API.

Nested JSON: exact-document mode#

Nested JSON replaces the repeater with a JSON textarea (with a Format button, Tab indentation, and bracket auto-pairing). What you type is what gets sent: the document passes to the encoder verbatim, with no type coercion and no flattening. If you write "skip": "0", the API receives the string "0" — in this mode you author the exact wire shape yourself.

Two behavioral differences from Key / Value:

• API-level Default Body Parameters are not merged in. A nested document has no clean merge with flat key-value pairs, so the endpoint’s document is the whole configured body.
• Runtime body_variables merge at the top level only. A runtime key replaces the entire top-level value of the same name, nested contents included; it cannot reach inside a nested object to change one leaf.

Example — the same /products/add endpoint in Nested JSON mode:

{
    "title": "Test Product",
    "price": 42,
    "dimensions": {
        "width": 10,
        "depth": 5
    }
}

Sent with the exact values and structure you wrote (re-serialized as minified JSON), as application/json.

Trying it against DummyJSON#

DummyJSON’s /products/add echoes the body back with a new id, which makes it a safe test target.

Shortcode (Key / Value endpoint configured as above):

Output: nothing is rendered — format="no_display" fires the request without printing the response.

PHP, overriding one field at runtime:

$created = huxx_api( 'demo_api', 'add_product', array(
    'body_variables' => array( 'title' => 'Runtime Title' ),
) );

echo esc_html( $created['id'] . ': ' . $created['title'] );

Output:

195: Runtime Title

Advanced#

Switching formats#

Switching an endpoint from Key / Value to Nested JSON converts the rows into a JSON document, but the values arrive as strings: a row price = 42 becomes "price": "42". Key / Value would have coerced that to a number at send time; Nested JSON will not. After switching, edit the document and remove the quotes from values that should be numbers or booleans.

Switching in the other direction is guarded: if the document contains nested objects, the UI warns that they will be flattened “into JSON strings. Most APIs reject this format when the request is sent,” and asks you to confirm with Flatten anyway or Cancel.

Format vs Body Encoding#

Body Encoding (JSON, URL Encoded, Multipart, Raw, None) decides how the assembled body is serialized and which Content-Type is sent; Format decides how you author it and how values are processed first. Nested JSON with URL Encoded is legal but almost never what an API expects — the editor’s helper text flags it and suggests JSON encoding. Multipart endpoints bypass the Format toggle entirely; their parts have their own file-aware structure.

The raw-body escape hatch#

In Key / Value mode, a single row with an empty key and a value makes that value the entire body. Under JSON Body Encoding, a value that already looks like JSON (starts with { or [) passes through verbatim — no double-encoding — while any other string is JSON-encoded, so hello is sent as "hello". The Raw and None encodings both send the value untouched. This exists for WPGetAPI-migrated configurations — see Keep WPGetAPI code working. For new endpoints, prefer Nested JSON; it does the same job with validation and an editor.

If it didn’t work#

The API rejects a field that should be an object. You are in Key / Value mode and typed {"a":1} into a value — it was sent as a string. Switch the Format toggle to Nested JSON and author the structure directly.

An API-level Default Body Parameter is missing from requests. The endpoint uses Nested JSON, where defaults are intentionally not merged. Add the key to the endpoint’s JSON document.

No body was sent at all. Bodies go out only for POST, PUT, and PATCH — check the endpoint’s Method. Then confirm what was actually transmitted with Debug API requests.