Add Row
add_rowCreate a row in a v2 app's collection, or return the existing row when key is already present (deduped:true). Row creation goes through this tool; there is no separate strict-create verb. Omit key to add a new row with a server-generated key, or pass key to ensure a row exists at that key. Passing key is also what makes a retry safe: a call unsure whether it already landed can repeat it and get the same row back rather than a duplicate. Without key, a retry mints a second row with its own server-generated key, since there is nothing to dedup against. The collection must be declared in the app's manifest with a write list that reaches the caller, which is the list that gates creates. An agent acts with its owner's authority, so owner covers it; there is no separate 'agent' role, and a manifest that names one is rejected. When key matches a row the collection's read list does not reach for this caller, the result is row_not_found rather than the row, matching what get_row would return, so this never reads past read. Returns { row, deduped? }.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Optional stable key. Reusing an existing key returns the existing row (deduped:true), or row_not_found when the collection's read list does not reach that row for the caller. | |
| data | Yes | The row body - any JSON value valid against the collection's row schema (an object, or any JSON value for a schemaless collection). | |
| app_id | Yes | The app id. | |
| collection | Yes | The collection name. |