# Insert a row (new note). Values are validated against the columns; the note path comes from

`POST /datanotes/operations/insert_row/` (operation `insert_row`)

Insert a row (new note). Values are validated against the columns; the note path comes from
the table's `path`/`filename` patterns (e.g. an event logged today about last night lands in
last night's day folder when you set `occurred_at` to last night). `body` is the note text.
Generated / identity columns are computed (do not pass them); CHECK constraints are enforced.
Returns `migration_id` (undo) and the created path in `planned_creates`.
`body` links the notes it mentions by name, at their first mention (automatic links; off with
`autolink: false` or the database's `autolink` setting). `links_added` lists the links made;
`ambiguous_mentions` lists the mentions left as text with the notes they may name: read those,
then link the right one with update_row and `autolink: false`, or leave the text.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |

## Request body

`application/json`, required

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `table` | `string` | yes |  |  |
| `values` | `object` | yes |  |  |
| `body` | `string \| null` | no | `null` |  |
| `path` | `string \| null` | no | `null` | Optional note path (vault-relative), instead of the table's file-name pattern; `.md` is added if missing; it must stay inside the vault. |
| `dry_run` | `boolean` | no | `false` |  |
| `autolink` | `boolean \| null` | no | `null` | Automatic links for this write: true links the notes `body` mentions by name, false writes it as given. Default: the calling token's `autolink` default, else the database's `autolink` setting (on unless configure_database turned it off). |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | Done. | `OpResult` (application/json) |
| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
| 401 | Missing or wrong bearer token. | `Error` (application/json) |
| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
| 409 | Ambiguous table name: it matches several tables (`paths` or `tables` lists them). | `AmbiguousName` (application/json) |
| 422 | Refused (validation failures, conflicts, an unmet `expect`): nothing written. Same body as 200, with `ok: false` and the reasons. | `OpResult` (application/json) |
| 500 | Unexpected error (`{error}`), or a write that failed partway and could not be rolled back: `rolled_back: false`, `failed` lists the files left (undo_migration on `migration_id` retries the rollback). | `OpResult \| Error` (application/json) |
| 503 | A write that failed partway (a file another program holds) and was rolled back: `rolled_back: true`, nothing written. Send it again later. Same body as 200, with `ok: false` and `failed`. | `OpResult` (application/json) |

The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).