From 57d3e114ce1ca185e1a438a4a8283709c6117dab Mon Sep 17 00:00:00 2001
From: soyuka <soyuka@users.noreply.github.com>
Date: Tue, 16 Jun 2026 16:24:43 +0200
Subject: [PATCH] docs: document allowCreate for PUT upsert

PUT to a missing item returns 404 by default. The `allowCreate: true`
option on the Put operation enables upsert (create when not found,
201 response), but it was undocumented.

Add an "Upsert" section to core/operations.md with PHP/YAML/XML
examples, and fix the misleading Laravel mention that implied enabling
PUT alone supports upsert.

Closes #8303
---
 core/operations.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++
 laravel/index.md   |  4 +++-
 2 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/core/operations.md b/core/operations.md
index a8ccd574fea..6239007ca39 100644
--- a/core/operations.md
+++ b/core/operations.md
@@ -63,6 +63,60 @@ Item operations:
 > properties not included in the payload are **not** removed, their current values are preserved. To
 > remove an existing property, its value must be explicitly set to `null`.
 
+## Upsert: Creating a Resource With PUT
+
+By default, sending a `PUT` request to an item that does not exist returns a `404 Not Found`. To
+enable an "upsert" behavior (update the resource if it exists, create it otherwise), set the
+`allowCreate` property to `true` on the `PUT` operation. The identifier provided in the URI is then
+used for the new resource and a `201 Created` response is returned when the item did not exist.
+
+<code-selector>
+
+```php
+<?php
+// api/src/Entity/Book.php
+namespace App\Entity;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Put;
+
+#[ApiResource(
+    operations: [
+        new Put(allowCreate: true),
+    ]
+)]
+class Book
+{
+    // ...
+}
+```
+
+```yaml
+# api/config/api_platform/resources.yaml
+resources:
+    App\Entity\Book:
+        operations:
+            ApiPlatform\Metadata\Put:
+                allowCreate: true
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- api/config/api_platform/resources.xml -->
+<resources xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+           xmlns="https://api-platform.com/schema/metadata/resources-3.0"
+           xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
+           https://api-platform.com/schema/metadata/resources-3.0.xsd">
+    <resource class="App\Entity\Book">
+        <operations>
+            <operation class="ApiPlatform\Metadata\Put" allowCreate="true" />
+        </operations>
+    </resource>
+</resources>
+```
+
+</code-selector>
+
 ## Enabling and Disabling Operations
 
 If no operation is specified, all default CRUD operations are automatically registered. It is also
diff --git a/laravel/index.md b/laravel/index.md
index 573d312f758..dfe58f2b890 100644
--- a/laravel/index.md
+++ b/laravel/index.md
@@ -734,7 +734,9 @@ You can change the default configuration (for instance, which operations are ena
 the config (`config/api-platform.php`).
 
 For the rest of this tutorial, we'll assume that at least all default operations are enabled (you
-can also enable `PUT` if you want to support upsert operations).
+can also enable `PUT`, optionally with
+[`allowCreate: true`](../core/operations.md#upsert-creating-a-resource-with-put) if you want to
+support upsert operations).
 
 ## Adding Filters