Dataset tools

Datasets are reusable, organization-scoped bulk-create data sources (Canva-style "Bulk Create"). A dataset has a typed column schema and a list of rows; once bound to a design it drives one exported record per row. These tools let you discover, create, fill and manage datasets without an editor session.

Working with cells

To keep things simple, rows are plain objects keyed by column name (case-insensitive) or column id. You do not need to send the internal cell structure:

{ "Title": "Summer Sale", "Price": "19.99", "Active": "yes", "Photo": "https://cdn.example.com/a.jpg" }

Values are coerced to the column's type:

Column type	Accepts	Notes
text	any value	Converted to a string
select	any value	Free-text at the dataset level (see note below)
boolean	true/false, or "yes", "true", "1", "ja", "on"	Anything else is false
image / video	a URL (http(s)://…), an asset id, or { "assetId": "…" } / { "url": "…" }	A bare string starting with http is treated as an external URL; otherwise it is treated as a library asset id

Omitted columns are blank-filled; unknown keys are ignored. Datasets are limited to 300 rows and 150 columns.

Media asset ids are validated. When you reference a library asset id in an image/video cell, it must be a real, non-deleted asset in the organization (use get-assets to find ids). A non-existent id makes the write fail with a clear error instead of silently storing an empty image. Public URLs are accepted as-is.

select columns are free-text at the dataset level: there is no fixed option list stored on the column (the constrained option set lives on the template control the column is bound to). To help you stay consistent, get-dataset returns the distinct values already used in each select column as distinctValues.

Permissions: reading (get-datasets, get-dataset) only needs authentication. All mutating tools require the design.create permission in the organization (the same requirement as the REST dataset endpoints).

---

get-datasets

List the organization's datasets with their column schema and row counts.

Parameters

None.

Response

Field	Type	Description
datasets	array	List of datasets
datasets[].id	string	Dataset identifier
datasets[].name	string	Dataset name
datasets[].origin	string	csv | xlsx | manual | sheet | api
datasets[].rowCount	number	Number of rows
datasets[].columns	array	Column schema (id, name, type)
datasets[].createdAt	string	ISO date
datasets[].updatedAt	string	ISO date
count	number	Total number of datasets

Example

{
  "tool": "get-datasets",
  "arguments": {}
}

---

get-dataset

Get a single dataset including its column schema and rows (paginated). Cell values are returned as plain values keyed by column name.

Parameters

Parameter	Type	Required	Description
datasetId	string	Yes	Id of the dataset (from get-datasets)
offset	number	No	Row offset for pagination (default 0)
limit	number	No	Max rows to return (default 100, max 300)

Response

Field	Type	Description
success	boolean	Whether the dataset was found
dataset.id	string	Dataset id
dataset.name	string	Dataset name
dataset.origin	string	Data origin
dataset.rowCount	number	Total rows in the dataset
dataset.columns	array	Column schema (id, name, type)
dataset.columns[].distinctValues	string[]	select columns only: distinct values already in use (up to 50), as a fill hint
rows	array	The page of rows
rows[].id	string	Row id (stable; use it with upsert-dataset-rows / delete-dataset-rows)
rows[].values	object	Cell values keyed by column name
total	number	Total rows (for pagination)

Example

{
  "tool": "get-dataset",
  "arguments": { "datasetId": "<dataset id>", "limit": 50 }
}

---

create-dataset

Create a new dataset by defining its columns and (optionally) seeding initial rows.

Parameters

Parameter	Type	Required	Description
name	string	Yes	Dataset name
columns	array	Yes	Column definitions (name, optional type), 1–150 entries
columns[].name	string	Yes	Column header / field name
columns[].type	string	No	text (default), image, video, boolean, select
rows	array	No	Initial rows; each row is an object keyed by column name (or id), max 300

Column ids are generated automatically from the column names (e.g. "Product Title" → product-title); colliding names get a unique id.

Response

Field	Type	Description
success	boolean	Whether the dataset was created
dataset.id	string	Id of the new dataset
dataset.name	string	Name
dataset.rowCount	number	Number of seeded rows
dataset.columns	array	The resolved column schema (with generated ids)
message	string	Confirmation message

Example

{
  "tool": "create-dataset",
  "arguments": {
    "name": "Summer Products",
    "columns": [
      { "name": "Title", "type": "text" },
      { "name": "Price", "type": "text" },
      { "name": "Photo", "type": "image" },
      { "name": "On Sale", "type": "boolean" }
    ],
    "rows": [
      { "Title": "Sunglasses", "Price": "19.99", "Photo": "https://cdn.example.com/s.jpg", "On Sale": "yes" }
    ]
  }
}

---

add-dataset-rows

Append rows to an existing dataset (fill it with data) without touching the rows already there.

Parameters

Parameter	Type	Required	Description
datasetId	string	Yes	Id of the dataset to fill
rows	array	Yes	Rows to append; each row is an object keyed by column name (or id), 1–300

The call is rejected if it would push the dataset over the 300-row limit.

Response

Field	Type	Description
success	boolean	Whether the rows were appended
datasetId	string	The dataset id
added	number	Number of rows inserted
rowCount	number	New total row count
message	string	Confirmation message

Example

{
  "tool": "add-dataset-rows",
  "arguments": {
    "datasetId": "<dataset id>",
    "rows": [
      { "Title": "Beach Towel", "Price": "12.50", "On Sale": "no" },
      { "Title": "Flip Flops", "Price": "8.00", "On Sale": "yes" }
    ]
  }
}

---

replace-dataset-rows

Replace all rows of a dataset with the provided rows. The previous rows are discarded. Pass an empty array to clear the dataset. Use add-dataset-rows instead to append without removing existing data.

Parameters

Parameter	Type	Required	Description
datasetId	string	Yes	Id of the dataset
rows	array	Yes	The complete new set of rows (object keyed by column name), max 300

Response

Field	Type	Description
success	boolean	Whether the rows were replaced
datasetId	string	The dataset id
rowCount	number	New total row count
message	string	Confirmation message

Example

{
  "tool": "replace-dataset-rows",
  "arguments": {
    "datasetId": "<dataset id>",
    "rows": [{ "Title": "New Product", "Price": "29.99" }]
  }
}

---

upsert-dataset-rows

Update specific rows by id and/or insert new rows, leaving all other rows untouched. This is the right tool for editing a few rows of a larger dataset. Unlike replace-dataset-rows, you don't have to re-send the whole dataset.

Parameters

Parameter	Type	Required	Description
datasetId	string	Yes	Id of the dataset
rows	array	Yes	Rows to update/insert, 1–300
rows[].id	string	No	Existing row id (from get-dataset) to update. Omit (or pass an unknown id) to insert a new row
rows[].values	object	Yes	Cell values keyed by column name (or id)

The id is a separate field (not inside values) so it can never collide with a column literally named id.

Response

Field	Type	Description
success	boolean	Whether the upsert succeeded
datasetId	string	The dataset id
updated	number	Number of existing rows updated
inserted	number	Number of new rows inserted
rowCount	number	New total row count
message	string	Confirmation message

Example

{
  "tool": "upsert-dataset-rows",
  "arguments": {
    "datasetId": "<dataset id>",
    "rows": [
      { "id": "<existing row id>", "values": { "Price": "14.99" } },
      { "values": { "Title": "Brand New Item", "Price": "5.00" } }
    ]
  }
}

---

delete-dataset-rows

Delete specific rows by their ids, leaving the rest intact. To clear the whole dataset, use replace-dataset-rows with an empty array instead.

Parameters

Parameter	Type	Required	Description
datasetId	string	Yes	Id of the dataset
rowIds	string[]	Yes	Ids of the rows to delete (from get-dataset), 1–300

Response

Field	Type	Description
success	boolean	Whether the deletion succeeded
datasetId	string	The dataset id
deleted	number	Number of rows actually deleted
message	string	Confirmation message

Example

{
  "tool": "delete-dataset-rows",
  "arguments": {
    "datasetId": "<dataset id>",
    "rowIds": ["<row id 1>", "<row id 2>"]
  }
}

---

update-dataset

Update a dataset's name and/or column schema.

Parameters

Parameter	Type	Required	Description
datasetId	string	Yes	Id of the dataset
name	string	No	New dataset name
columns	array	No	New full column schema (replaces the existing columns)
columns[].id	string	No	Existing column id to preserve its cells; omit to add a new column
columns[].name	string	Yes	Column header / field name
columns[].type	string	No	text (default), image, video, boolean, select

At least one of name or columns must be provided. When sending columns, include every column you want to keep. Columns not present are removed. Pass an existing column's id so its row data stays aligned.

Response

Field	Type	Description
success	boolean	Whether the dataset was updated
dataset.id	string	Dataset id
dataset.name	string	Name
dataset.rowCount	number	Row count
dataset.columns	array	The resolved column schema
message	string	Confirmation message

Example

{
  "tool": "update-dataset",
  "arguments": {
    "datasetId": "<dataset id>",
    "name": "Summer Products 2026"
  }
}

---

delete-dataset

Soft-delete a dataset. Designs already bound to it keep their resolved data, but the dataset no longer appears in the library.

Parameters

Parameter	Type	Required	Description
datasetId	string	Yes	Id of the dataset to delete

Response

Field	Type	Description
success	boolean	Whether the dataset was deleted
datasetId	string	The dataset id
message	string	Confirmation message

Example

{
  "tool": "delete-dataset",
  "arguments": { "datasetId": "<dataset id>" }
}