Create datasets
Last updated: November 3, 2026.
Create a dataset when an agent or application needs a stable row store it can come back to later.
Before you create one
Decide four things:
- the dataset name
- the headers
- the index column
- the instructions future agents should follow
If there is no reliable business key, omit index_column and let Rowset create
rowset_id. For the tradeoff, read Rowset rowset_id vs business
keys before production agents start updating
rows.
If you are choosing between a Rowset-hosted agent dataset and a spreadsheet-style
database workspace, review NocoDB alternatives for AI-agent-managed
datasets first.
Create through MCP
Use MCP when a trusted agent is doing the setup. First connect the client with an account-wide Read + write or Admin key. These levels are not per-dataset grants. Complete the first-project discovery and confirmation steps before creating a dataset for a new workflow; reuse an existing matching dataset.
The examples below are MCP argument objects, not complete protocol requests. They match the Rowset tool definitions at main 68b4a71, checked November 3, 2026. Check your connected client's live schema and replace angle-bracket placeholders with returned keys.
1. Create the empty schema
Call create_dataset with the approved project and section keys. This task
schema has no invented production rows:
{
"name": "Agent tasks",
"description": "Tasks delegated to trusted agents",
"instructions": "Keep task_id stable. Only move status to done when acceptance notes are present.",
"headers": ["task_id", "status", "next_action", "notes"],
"index_column": "task_id",
"column_types": {
"task_id": "text",
"status": {"type": "choice", "choices": ["todo", "doing", "blocked", "done"]},
"next_action": "text",
"notes": "text"
},
"project_key": "<project_key>",
"section_key": "<section_key>",
"prevent_duplicate_name": true
}
Omit section_key if the project has no section. For an intentionally ungrouped
dataset, omit both placement keys and prevent_duplicate_name; the duplicate-name
guard requires a project. A duplicate-name error is a reason to inspect the
matching dataset, not disable the guard and create again. Dataset instructions
are guidance: they do not enforce approval or the acceptance-notes rule.
2. Inspect the returned dataset key
Save dataset.key from the create result, then call get_dataset:
{"dataset_key": "<dataset_key>"}
The inspection returns dataset context directly. Confirm key,
index_column = task_id, index_generated = false, the headers and
column_schema, project placement, instructions, and row_count = 0.
A successful create is not proof that a useful row has been saved.
3. Save one real task and read it back
Take an actual authorized task from your workflow. Call create_dataset_row
with dataset_key and a data object keyed by these headers; supply its unique,
non-blank task_id. Then independently call get_dataset_row_by_index:
{"dataset_key": "<dataset_key>", "index_value": "<actual_task_id>"}
Confirm row.data contains the expected task and next action. The dataset key,
internal row ID, and task_id are different identifiers; this lookup uses the
configured index value. If a write times out, inspect that index before retrying.
For exact write arguments, duplicate handling, and safe updates, continue with
working with rows.
Create through REST
POST https://rowset.app/api/datasets
Authorization: Bearer YOUR_ROWSET_API_KEY
Content-Type: application/json
{
"name": "Agent tasks",
"description": "Tasks delegated to trusted agents",
"instructions": "Only move status to done when acceptance notes are present.",
"metadata": {
"status_values": ["todo", "doing", "blocked", "done"]
},
"headers": ["task_id", "status", "owner", "next_action", "notes"],
"index_column": "task_id",
"column_types": {
"task_id": "text",
"status": {
"type": "choice",
"choices": ["todo", "doing", "blocked", "done"]
},
"owner": "text",
"next_action": "text",
"notes": "text"
},
"rows": [
{
"task_id": "TASK-001",
"status": "todo",
"owner": "Rasul",
"next_action": "Draft the first row",
"notes": ""
}
]
}
Initial creation accepts up to 1,000 rows. Add larger batches after creation with row endpoints or MCP row tools.
Put it in a project
If the dataset belongs to a workflow group, include project_key. If it belongs
inside a project section, include both project_key and section_key.
{
"project_key": "{project_key}",
"section_key": "{section_key}"
}
Projects and sections help with discovery. They do not change who can access the dataset.
Good first datasets
- Personal CRM:
people, indexed byemailorperson_id - Agent task board:
agent_tasks, indexed bytask_id - Feedback triage:
feedback, indexed byfeedback_id - Content pipeline:
content_queue, indexed byslug - Product catalog:
products, indexed bysku
See Use cases for starter shapes.