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>

What the response contains

The response body is the markup you created, without any whitespace before or after it. So if your request body ends in a newline, the response does not. The ETag describes exactly that body: hash the body with SHA-256 and you get the first part of the ETag. A later read of the created element returns the same ETag. The stored document keeps the whitespace you sent.

A body that is only whitespace creates no element, so it is refused with 422 Unprocessable Entity and an error in HTML Microdata. Nothing is stored and the response has no ETag. A POST to a transient element is refused the same way.

POST with no selector

A POST with no Range: selector= works in one of two ways, depending on the page it is sent to.

Where an element deny applies to you, a POST with no selector is checked like a whole-page PUT of its body. See an element deny also guards a whole-page write.

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

Put placement=<keyword> after the selector and write nothing else after the ;: Range: selector=ul; placement=prepend. Write placement in lower case, with no space before the =. The keyword can be in any case. If anything else comes before the placement or after the keyword, including a second placement=, the server ignores the placement and appends the body to the 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>

Posting to a large page

A POST addressed by #id, by .class, by an exact attribute value such as [data-key="7"], or by a position inside one of those, such as #column-4 .cards > article:first-child, can read only the part of the page it changes, so its cost does not grow with the page. The server reads the part of the page around the new element, adds the element there, and stores only that part.

When anything else needs the whole page, the POST reads the whole page as before. That happens when the request has an If-None-Match header, when a shape constraint applies to the page or the page declares one, when a transition rule watches something on the page or in your body, when your schema has a @validate expression or a @write resolver, and when the page uses itemref or declares a namespace. The response does not say which route was taken, but two things differ afterwards. The live-update event for the POST has an empty etag, and a WebDAV PROPFIND with Depth: 1 leaves the page out of the <D:getetag> values until the page has been read whole again. A POST over WebDAV always reads the whole page and answers as it always has, with the page's ETag.

The response is the same either way. It carries the created element and the element's ETag, which a GET of the element returns next. A POST that reads only its part of the page does not work out the page's own ETag. The live-update event it sends names none, and the next GET of the page returns the new one. You can send an If-Match or If-None-Match for the page straight after a POST, before any GET, and it is compared with the page's real ETag.

Error cases

Condition Status
Document does not exist 404 Not Found
Selector matches no element 416 Range Not Satisfiable
Authorization denied 403 Forbidden
A Range header with more than one selector= 400 Bad Request
Schema validation fails 422 Unprocessable Entity
Shape or cardinality rule broken, including by an append re-applied after a concurrent write 422 Unprocessable Entity
Concurrent writes kept the append from landing after 16 attempts 409 Conflict
Host has transition rules and the page changed while the write was being checked 409 Conflict
Host has transition rules and a file that is not HTML would replace a page holding a watched item with no declared exit 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 normally both land, and neither append is lost. The server applies each append against the latest stored version of the document, so concurrent appends accumulate rather than one overwriting the other.

The server checks an append again when it re-applies it. If the two appends together break a shape constraint or a schema cardinality rule, the later one gets 422 Unprocessable Entity and nothing is saved. If concurrent writes keep changing the page and the append still has not landed after 16 attempts, you get 409 Conflict with a WriteContention error. The same happens if a concurrent write turns the page into a template, or a template into a page, while the append is being retried. Inspect the actual refusal and current target before deciding on another request; a 409 alone does not establish that repeating the append is appropriate.

On a host with transition rules, the server does not retry an append for you. Every POST the rules check is pinned to the version of the page the server read, and if the page changed in between, you get 409 Conflict with a WriteContention error on the first clash. Review the current target and intended addition before preparing a deliberate new request; the new attempt is evaluated against that current state. See TransitionConstraint for the writes the rules do not check.

A POST of a file that is not HTML, with no selector, to a path that holds a web page counts as deleting that page when the host has transition rules. It is refused with 422 if the page holds a watched item and the rules declare no exit for it. See Transition constraints. A POST with a selector never saves a file. Sent to a path that names a page, it adds its body to the element as markup, whatever its Content-Type. Sent to a directory path, it updates every matching page, and a text/plain body there sets the text of each matched element.

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 rather than applied against the new state. Retain the submitted body and review the current target before preparing a new conditional request.

Keep the frozen submitted body, intended resource/selector and original validator separate from any newer local draft until the outcome is resolved. If the reply is lost, treat the outcome as Unknown, not a confirmed refusal: an append may already have committed, and repeating it can add the same content again. Inspect current state through a permitted read and use operation-specific evidence where the application provides it before deciding on another request. Matching content alone does not identify which request inserted it. Reconcile independently persisted trigger effects separately; do not assume automatic deduplication. See Save a fragment without losing your draft for the pending/draft distinction; its PUT example is not an append-retry implementation.

A selector-scoped If-Match can also fail for a second reason. If the version you quoted is still current but the ETag does not name the element as it is stored, the 412 body carries a problem item of type https://pagelove.org/Problem/RepresentationMismatch. Re-reading will not help. See PUT for the full explanation, including which pages can and cannot be written back through.

The same eligible internal re-apply applies when the matched element was projected from another resource via <p:stamp> or <p:include>: the append is routed to that element's origin resource. It remains subject to the same conditional and transition guards, validation and retry limits; routing to an origin does not make every concurrent append succeed or make client replay duplicate-safe.

See also