PUT method

The HTTP PUT method replaces a document fragment or creates a new document. When combined with a selector range unit, it replaces the matched element with the request body.

When to reach for it

Use PUT to overwrite an existing element or to store a new document at a given path. The server returns 206 Partial Content with a Content-Range header identifying the replaced element.

All PUT requests are subject to authorization.

Examples

Replace a single element

Given a document with a heading and a paragraph, replace the heading:

PUT /put-replace-test.html
Range: selector=h1
Content-Type: text/html

<h1>New Header</h1>

HTTP/1.1 206

<h1>New Header</h1>

Write persists

After replacing a heading, the change is stored:

PUT /put-persist-test.html
Range: selector=h1
Content-Type: text/html

<h1>Updated Title</h1>

HTTP/1.1 206

<h1>Updated Title</h1>

Reading the document back confirms the update:

GET /put-persist-test.html
Range: selector=h1

HTTP/1.1 206

<h1>Updated Title</h1>

Concurrency

To protect a whole-document PUT against lost updates, send the ETag you last read in an If-Match header. The write only succeeds if the document is still at that version when the write commits — if another client's save lands first, even a moment before yours, your PUT is rejected with 412 Precondition Failed instead of silently overwriting their work. The 412 response carries the document's current ETag, so you can re-read and retry without an extra GET.

If-Match accepts the standard HTTP forms:

• a single ETag — If-Match: "abc123...";
• a comma-separated list — If-Match: "abc...", "def..." — which succeeds if any listed version is current;
• the wildcard If-Match: *, which succeeds as long as the document exists at all (any version), and fails with 412 if it doesn't.

The mirror header If-None-Match blocks a write when a listed ETag (or *, meaning "if it exists at all") matches the current version — use If-None-Match: * for create-only semantics: the PUT succeeds only when the path is not yet taken.

Error cases

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. Two cases still 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.

Reserved namespace. The /.pagelove/ path prefix is reserved for the platform's internal documents and is not writable. Any write (PUT, POST, DELETE, MOVE) targeting a path under /.pagelove/ is refused with 403 Forbidden; choose a different path for your own documents.

Request body size limit

Every write request's body is subject to an operator-configured size cap (1 GiB unless changed; it can also be tuned per site, so the limit may differ between hosts). A request whose Content-Length exceeds the cap is answered 413 Content Too Large immediately, without the body being read; an upload without an accurate Content-Length (for example, chunked) is rejected with 413 as soon as it exceeds the cap. The 413 response body is HTML carrying https://pagelove.org/Error Microdata with status and message properties, and the connection is closed.

Send an accurate Content-Length when uploading large content so an over-limit request fails fast instead of transferring the whole body.

See also

• Modeling data — schema validators that check content values on write
• Shape Constraints — validate document structure on write
• Transient Elements — session-scoped element content