POST method

The HTTP POST method appends content to a document fragment or creates a new resource. When combined with a selector range unit, it appends the request body as a child of the matched element.

When to reach for it

Use POST to add content without replacing what already exists. The server returns 206 Partial Content with a Content-Range header identifying the updated element.

All POST requests are subject to authorization.

Examples

Append to a list

Given a document with a list, append a new item:

POST /post-append-test.html
Range: selector=ul
Content-Type: text/html

<li>New item</li>

HTTP/1.1 206

<li>New item</li>

Verify the append

Reading the list back confirms that existing items are preserved alongside the new one:

GET /post-verify-test.html
Range: selector=ul

HTTP/1.1 206

<ul>
    <li>Existing item</li>
  <li>Appended item</li>
</ul>

Placement

By default POST appends the request body as the last child of the element matched by Range:. To insert at a different position, supply placement=<value> as a Range: sub-field:

Placement	Insertion site
`append` (default)	Last child of the matched element
`prepend`	First child of the matched element
`before`	Previous sibling of the matched element
`after`	Next sibling of the matched element

placement=before and placement=after against a parentless anchor (e.g. <html>) return 400 Bad Request — there's no sibling slot.

Prepend a list item

POST /post-prepend-test.html
Range: selector=ul; placement=prepend
Content-Type: text/html

<li>New first item</li>

HTTP/1.1 206

<li>New first item</li>

Insert before a specific sibling

POST /post-before-test.html
Range: selector=li#beta; placement=before
Content-Type: text/html

<li>Inserted before beta</li>

HTTP/1.1 206

<li>Inserted before beta</li>

Insert after a specific sibling

POST /post-after-test.html
Range: selector=li#alpha; placement=after
Content-Type: text/html

<li>Inserted after alpha</li>

HTTP/1.1 206

<li>Inserted after alpha</li>

Error cases

Condition	Status
Document does not exist	`404 Not Found`
Selector matches no element	`416 Range Not Satisfiable`
Authorization denied	`403 Forbidden`
Schema validation fails	`422 Unprocessable Entity`

Absence and denial are distinct. A selector that matches no element gets 416, and one you are not permitted to write gets 401/403 — the two are never confused. Where the edge cannot see your target it re-checks against the live document before answering, so a 416 means the element really was absent at that moment — for an append that does not name a placement. A POST that specifies placement=before or placement=after currently refuses instead of reporting 416 when its anchor is absent.

Two further cases refuse rather than reporting 416: a target that exists but is covered by a rule denying it, which is a genuine authorization answer rather than an absence; and a target you would not be permitted to read, since "there is nothing there" is itself information about the page. If you can write to part of a page you cannot read, writes refuse identically whether the target exists or not.

Concurrency

A selector POST is additive: it appends to the matched element rather than replacing it. Two clients that append to the same element at the same time both land — neither append is lost, and both requests succeed. The server applies each append against the latest stored version of the document, so concurrent appends accumulate rather than one overwriting the other.

If you send a conditional append with If-Match: "<etag>" and the document changed since that ETag, the append is rejected with 412 Precondition Failed (re-read the document and retry against the current version) rather than applied against the new state.

This accumulation guarantee also holds when the matched element was projected into the page from another resource (via <p:stamp> or <p:include>): the append is routed to that element's origin resource and re-applied against the origin's latest version on conflict, so concurrent appends to a stamped or included element accumulate just as they do for a same-document append.