Work with rows
Last updated: October 27, 2026.
Rows are the working records inside an active dataset. Agents should inspect the dataset first, then read or change rows using the most stable identifier available.
Inspect first
Before row work, call:
get_dataset
The response gives the agent the headers, index column, instructions, schema, project context, relationships, and asset references.
Save one real row and verify it
Already have a confirmed dataset and a real task, contact, or feedback item to save? Give your agent the dataset key or URL and that source input. If you have not connected an agent or chosen a dataset, start with the first-dataset quickstart; do not create a second dataset just to try row operations.
For a dataset with a stable business-key index, use this handoff:
Save the real input I provided in the confirmed dataset. Inspect the dataset
first and preserve its headers, schema, instructions, index, and privacy settings.
Do not invent missing values. Read the exact index before creating a row. If it
already exists, compare it with my input and update only the changes I requested;
report conflicting identity or unclear intent instead of overwriting it.
After the write, fetch the row again by index and compare the stored fields
with my input. If the write response is uncertain, read that index before retrying.
Report whether the row was created, updated, or already matched, and whether
the separate read-back confirmed the requested values.
The MCP sequence is get_dataset, get_dataset_row_by_index, the appropriate
create_dataset_row or update_dataset_row_by_index call, then a separate
get_dataset_row_by_index. Use the live tool schemas: row data is keyed by
the dataset's actual headers. A missing-row response permits creation only
after confirming the dataset and index; an authentication or network failure
does not establish that the row is absent. An unchanged row needs no write.
For a generated rowset_id index, keep the key returned by a successful create
and use it for later reads and updates. If a standalone create's response is
lost before you receive that key, stop and reconcile the existing rows rather
than blindly creating another. The
index-column guide explains which identity
path fits your source.
A successful write response alone is not a verified result. If the follow-up read fails or differs, report verification as incomplete. With no real source input, leave the dataset empty; do not insert a placeholder or enable a public preview to prove the connection works.
List rows
Use listing when you know the dataset and need a bounded page:
list_dataset_rows
REST:
GET https://rowset.app/api/datasets/{dataset_key}/rows
List rows supports pagination, text query, header filters, sort, and direction. For a worked REST example, follow pagination and response counts.
Search rows
Use profile-wide search when the relevant dataset is unknown:
search_rows
REST:
POST https://rowset.app/api/search
Use dataset search when you know the dataset and want ranked matches:
search_dataset_rows
REST:
POST https://rowset.app/api/datasets/{dataset_key}/search
Search uses hybrid vector and lexical retrieval when vector search is enabled. Rowset/Postgres remains the source of truth.
Read one row
Prefer index lookup when the dataset has a meaningful key:
get_dataset_row_by_index
REST:
GET https://rowset.app/api/datasets/{dataset_key}/rows/by-index?index_value=TASK-001
Use internal row id when you already have it:
get_dataset_row
Create and update rows
Create:
create_dataset_row
REST:
POST https://rowset.app/api/datasets/{dataset_key}/rows
Patch by index:
update_dataset_row_by_index
REST:
PATCH https://rowset.app/api/datasets/{dataset_key}/rows/by-index?index_value=TASK-001
For retry-prone agent workflows, use a stable index, patch absolute final values, and read the row after an uncertain response. The idempotent AI-agent updates guide includes a complete create-or-update and timeout-recovery pattern. When a row points to another dataset, apply the referential-integrity contract: verify the target, write the parent first, store the exact index, and resolve the link after the mutation. For cleanup jobs, use the same exact-key contract inside a reversible AI data-cleaning workflow that separates raw rows, proposed changes, approval, and verified publication. For product and stock workflows, the AI inventory agent guide applies that contract to catalogs, source observations, action proposals, and destination read-back.
Patch by row id:
update_dataset_row
REST:
PATCH https://rowset.app/api/datasets/{dataset_key}/rows/{row_id}
Delete rows
Deleting a row is destructive. Agents should ask first unless the user explicitly requested deletion.
delete_dataset_row
REST:
DELETE https://rowset.app/api/datasets/{dataset_key}/rows/{row_id}
For mistaken whole datasets, prefer archive and restore over deleting row by row.