From 73f338b9f3d510dc8fa60f6697b276cb121a0ec5 Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Wed, 15 Apr 2026 15:29:59 -0700
Subject: [PATCH] Better example in API explorer for /-/upsert, closes #1936

---
 datasette/views/special.py | 10 ++++++++--
 tests/test_api_write.py    | 16 ++++++++++++++++
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/datasette/views/special.py b/datasette/views/special.py
index dbe5eab1..1df74f07 100644
--- a/datasette/views/special.py
+++ b/datasette/views/special.py
@@ -813,9 +813,15 @@ class ApiExplorerView(BaseView):
                                 "json": {
                                     "rows": [
                                         {
-                                            column: None
+                                            column: "<{}{}>".format(
+                                                column,
+                                                (
+                                                    " (primary key)"
+                                                    if column in pks
+                                                    else ""
+                                                ),
+                                            )
                                             for column in await db.table_columns(table)
-                                            if column not in pks
                                         }
                                     ]
                                 },
diff --git a/tests/test_api_write.py b/tests/test_api_write.py
index 91a88606..f600d4f5 100644
--- a/tests/test_api_write.py
+++ b/tests/test_api_write.py
@@ -44,6 +44,22 @@ def _headers(token):
     }
 
 
+@pytest.mark.asyncio
+async def test_api_explorer_upsert_example_json(ds_write):
+    response = await ds_write.client.get("/-/api", actor={"id": "root"})
+    print("STATUS", response.status_code)
+    assert response.status_code == 200
+    import urllib.parse
+
+    text = urllib.parse.unquote_plus(response.text)
+    upsert_idx = text.index("/data/docs/-/upsert")
+    upsert_chunk = text[upsert_idx : upsert_idx + 500]
+    assert '"id": "<id (primary key)>"' in upsert_chunk
+    assert '"title": "<title>"' in upsert_chunk
+    assert '"score": "<score>"' in upsert_chunk
+    assert '"age": "<age>"' in upsert_chunk
+
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
     "content_type",