Datasets

A dataset is a reusable, organization-scoped table of data that powers heycreo's bulk create workflow. Instead of editing one design at a time, you fill a dataset with rows, bind it to a design, and the platform renders one export per row — the same layout, populated with different content.

A dataset has two parts:

A typed column schema — an ordered list of columns, each with a name and a content type.
A list of rows — each row holds one cell value per column.

The same dataset can be bound to many designs, so a single product catalog or event list can drive posts, ads, and print pieces at once.

How it works

Create a dataset by defining its columns (and optionally seeding rows). Data can be imported from a file, entered manually, or pulled live from an API connector.
Bind the dataset to a design. A binding maps each dataset column to a control in the design's template (for example, the Title column → the headline text control, the Photo column → the image control).
Export. At render time the platform resolves the binding and produces one output per selected row, for every selected format/size.

Datasets are limited to 300 rows and 150 columns.

Column types

Each column has exactly one content type. Cell values are stored and validated against that type.

Type	Holds	Notes
`text`	A string	The default. Used for headlines, prices, labels, etc.
`image`	An image reference	Either an asset in the organization's library or a public image URL.
`video`	A video reference	Same shape as `image`; used for video controls.
`boolean`	`true` / `false`	Drives show/hide and other on/off controls.
`select`	A string	A choice value. The fixed option set lives on the template control the column is bound to, not on the column itself.

image and video cells hold a structured media value (an asset id or a URL); the other types hold a primitive value.

Dataset origins

Every dataset records where its data came from via its origin:

Origin	Description
`csv`	Imported from an uploaded CSV file.
`xlsx`	Imported from an uploaded Excel file.
`manual`	Created and edited by hand in the data editor (or via the API).
`api`	Pulled live from an API connector and refreshable.
`sheet`	Reserved for a future live spreadsheet source.

When a file with embedded images is imported, those images are ingested into the organization's asset library and the cells reference the resulting assets.

The dataset object

interface Dataset {
  id: string;                 // UUID
  name: string;               // Dataset name
  origin: 'csv' | 'xlsx' | 'manual' | 'sheet' | 'api';

  columns: DataColumn[];      // Typed column schema
  rowCount: number;           // Number of rows

  // Only set for `api` (connector-backed) datasets
  connectorId?: string | null;     // Source connector
  lastSyncedAt?: string | null;    // Last refresh time

  createdAt: string;          // ISO date
  updatedAt: string;          // ISO date
}

interface DataColumn {
  id: string;                 // Stable column id (used as the binding key)
  name: string;               // Column header / display name
  type: 'text' | 'image' | 'video' | 'boolean' | 'select';
}

Rows and cells

A row is a set of cells keyed by column id. Each row has a stable id so individual rows can be updated or deleted without resending the whole table.

{
  "id": "f1e2d3c4-...",
  "cells": {
    "title": "Summer Sale",
    "price": "19.99",
    "photo": { "source": { "assetId": "a1b2c3d4-..." } },
    "on-sale": true
  }
}

Binding a dataset to a design

A dataset only produces output once it is bound to a design. The binding lives on the design (not the dataset), so the same dataset can be reused across designs while each design keeps its own mapping and overrides.

A binding stores:

datasetId — the dataset that feeds the design.
mapping — { controlId → columnId }, connecting template controls to dataset columns. The mapping is keyed by control, so reordering columns never breaks it.
rowSelection (optional) — the ordered list of row ids to include; omit to use all rows.
rowOverrides (optional) — per-record, per-size value overrides for fine-tuning individual records without changing the dataset.
namingColumnId (optional) — a column whose values are used to name the generated export files.

At export time the platform renders one record per selected row, applying the mapping and any overrides. Each design has at most one active binding.

API connectors

An API connector turns an external JSON API into a refreshable dataset (origin: 'api'). A connector describes, in configuration only:

the request (base URL, static headers/query params),
optional authentication (an API key injected as a header or query param — the key itself is stored encrypted and never returned by the API),
the path to the list of records in the response, and how to paginate it,
a field map that picks response fields (by path) into typed dataset columns, and
optional filters the content creator fills in at fetch time (e.g. a category or season).

Fetching a connector creates a dataset from the current API response. Connector-backed datasets can be refreshed later to pull the latest data, replaying the same filter values. Connectors have built-in safety limits (e.g. a maximum number of pages) so a misconfiguration can never hammer the upstream provider.

Managing datasets programmatically

Datasets can be managed two ways:

Workspace REST API — …/organizations/{organizationId}/datasets endpoints to create, read, update and delete datasets, replace or save rows, and refresh connector-backed datasets. Bindings are managed under …/posts/{postId}/data-binding. See the Workspace API reference.
MCP tools — for AI assistants, the dataset MCP tools expose the same operations with a simplified, column-name-keyed row format.

Mutating a dataset or a binding requires the design.create permission; creating or editing a connector configuration requires organization settings access (it handles secrets).

How it works​

Column types​

Dataset origins​

The dataset object​

Rows and cells​

Binding a dataset to a design​

API connectors​

Managing datasets programmatically​

See also​