1 files changed, 50 insertions, 0 deletions
diff --git a/query/insert.md b/query/insert.md
new file mode 100644
index 0000000..899f804
--- /dev/null
+++ b/query/insert.md
@@ -0,0 +1,50 @@
+# Insert
+
+[back to query](README.md) /// [home](../README.md)
+
+Add a new row to a table.
+
+## Request
+
+```json
+{
+  "action": "insert",
+  "table": "items",
+  "data": {
+    "name": "New Widget",
+    "category_id": 3,
+    "price": 24.99,
+    "status": "draft"
+  }
+}
+```
+
+## Fields
+
+| Field    | Type   | Required | Notes                        |
+|----------|--------|----------|------------------------------|
+| `action` | string | yes      | must be `"insert"`           |
+| `table`  | string | yes      | target table                 |
+| `data`   | object | yes      | column value pairs to insert |
+
+## Response
+
+```json
+{
+  "success": true,
+  "data": 42,
+  "rows_affected": 1
+}
+```
+
+`data` is the auto increment ID of the newly inserted row (`last_insert_id`).
+
+## Behaviors
+
+- columns you dont have write access to should cause jsonderulo to start stripping for you and remove the naughty stuff from `data`. if theres nothing left after stripping you get an error (cant insert nothing lol)
+- system columns should be auto populated:
+  - `created_by` set to your user ID
+  - `pinned_to` set to your user ID (unless you have `rwa` permission and explicitly set it to someone else)
+  - `created_at` handled by SQL defaults
+- if the table has auto generation rules configured (like auto generated codes or UUIDs) those should get applied automatically
+- you need write permission on the table. read only permission codes like `r`, `rg` and `ro` will give you a nice 403