Data Sets API

Manage collections of related CSV files (data sets) for complex document generation with multiple tables.

---

Base URL

https://app.datapublisher.io/api/data-sets

---

Authentication

All endpoints require JWT authentication via Authorization: Bearer header.

---

Overview

The Data Sets API allows you to:

Group related CSV files into data sets

Define relationships between tables

Configure auto-join settings

Clone domain templates with data

Manage multi-table document generation

Use Cases:

Real estate listings (Properties + Agents + Photos)

Product catalogs (Products + Categories + Specifications)

Employee directories (Employees + Departments + Locations)

Invoice generation (Invoices + LineItems + Customers)

---

Data Set Management

Create Data Set

Create a new data set container.

Endpoint: POST /

Headers:

Authorization: Bearer

Content-Type: application/json

Request Body:

{ "name": "Real Estate Listings", "description": "Property listings with agent and photo data", "domain": "real-estate", "csvFiles": [ { "fileId": "csv-uuid-1", "tableName": "Properties", "primaryKey": "PropertyID" }, { "fileId": "csv-uuid-2", "tableName": "Agents", "primaryKey": "AgentID" }, { "fileId": "csv-uuid-3", "tableName": "PropertyPhotos", "primaryKey": "PhotoID" } ], "relationships": [ { "from": "Properties", "to": "Agents", "type": "many-to-one", "fromKey": "AgentID", "toKey": "AgentID" }, { "from": "PropertyPhotos", "to": "Properties", "type": "many-to-one", "fromKey": "PropertyID", "toKey": "PropertyID" } ]

}

Response (200 OK):

}

---

List Data Sets

Get all data sets for the user.

Endpoint: GET /

Headers:

Authorization: Bearer

Query Parameters:

domain (optional): Filter by domain

Response (200 OK):

{ "success": true, "dataSets": [ { "id": "dataset-uuid-1", "name": "Real Estate Listings", "description": "Property listings with agent and photo data", "domain": "real-estate", "fileCount": 3, "totalRows": 45, "createdAt": "2026-02-12T10:30:00Z", "updatedAt": "2026-02-12T11:00:00Z" }, { "id": "dataset-uuid-2", "name": "Product Catalog", "description": "Products with categories and specs", "domain": "ecommerce", "fileCount": 4, "totalRows": 125, "createdAt": "2026-01-15T09:00:00Z", "updatedAt": "2026-02-10T14:30:00Z" } ], "totalCount": 2

}

---

Get Data Set Details

Get detailed information about a specific data set.

Endpoint: GET /:dataSetId

Headers:

Authorization: Bearer

Path Parameters:

dataSetId: Data set UUID

Response (200 OK):

{ "success": true, "dataSet": { "id": "dataset-uuid", "name": "Real Estate Listings", "description": "Property listings with agent and photo data", "domain": "real-estate", "csvFiles": [ { "id": "csv-uuid-1", "tableName": "Properties", "fileName": "properties.csv", "rowCount": 10, "columnCount": 12, "primaryKey": "PropertyID", "columns": [ { "name": "PropertyID", "type": "string" }, { "name": "Address", "type": "string" }, { "name": "City", "type": "string" }, { "name": "Price", "type": "currency" }, { "name": "AgentID", "type": "string" } ] }, { "id": "csv-uuid-2", "tableName": "Agents", "fileName": "agents.csv", "rowCount": 5, "columnCount": 7, "primaryKey": "AgentID", "columns": [ { "name": "AgentID", "type": "string" }, { "name": "AgentName", "type": "string" }, { "name": "Phone", "type": "string" }, { "name": "Email", "type": "email" } ] } ], "relationships": [ { "id": "rel-uuid-1", "from": "Properties", "to": "Agents", "type": "many-to-one", "fromKey": "AgentID", "toKey": "AgentID", "description": "Each property has one agent" } ], "createdAt": "2026-02-12T10:30:00Z", "updatedAt": "2026-02-12T11:00:00Z" }

}

---

Update Data Set

Update data set configuration.

Endpoint: PUT /:dataSetId

Headers:

Authorization: Bearer

Content-Type: application/json

Request Body:

{ "name": "Updated Data Set Name", "description": "Updated description", "relationships": [ { "from": "Properties", "to": "Agents", "type": "many-to-one", "fromKey": "AgentID", "toKey": "AgentID" } ]

}

Response (200 OK):

{ "success": true, "dataSet": { "id": "dataset-uuid", "name": "Updated Data Set Name", "updatedAt": "2026-02-12T11:30:00Z" }, "message": "Data set updated successfully"

}

---

Delete Data Set

Remove a data set (does not delete CSV files).

Endpoint: DELETE /:dataSetId

Headers:

Authorization: Bearer

Response (200 OK):

{
  "success": true,

  "message": "Data set deleted successfully"

}

Note: CSV files remain in your account, only the data set container is deleted.

---

Data Set Files

Add CSV to Data Set

Add a CSV file to an existing data set.

Endpoint: POST /:dataSetId/files

Headers:

Authorization: Bearer

Content-Type: application/json

Request Body:

{ "fileId": "csv-uuid-4", "tableName": "PropertyFeatures", "primaryKey": "FeatureID"

}

Response (200 OK):

{
  "success": true,

  "dataSet": {

    "id": "dataset-uuid",

    "fileCount": 4

  },

  "message": "CSV file added to data set"

}

---

Remove CSV from Data Set

Remove a CSV file from a data set.

Endpoint: DELETE /:dataSetId/files/:fileId

Headers:

Authorization: Bearer

Path Parameters:

dataSetId: Data set UUID

fileId: CSV file UUID

Response (200 OK):

{
  "success": true,

  "message": "CSV file removed from data set"

}

---

Replace CSV File

Replace a CSV file in a data set with a new version.

Endpoint: PUT /:dataSetId/files/:fileId

Headers:

Authorization: Bearer

Content-Type: application/json

Request Body:

{
  "newFileId": "csv-uuid-new",

  "tableName": "Properties"

}

Response (200 OK):

{
  "success": true,

  "dataSet": {

    "id": "dataset-uuid",

    "updatedAt": "2026-02-12T12:00:00Z"

  },

  "message": "CSV file replaced successfully"

}

---

Clone Domain Data Set

Create a data set from a domain template.

Endpoint: POST /clone-domain/:domainId

Headers:

Authorization: Bearer

Content-Type: application/json

Path Parameters:

domainId: Domain ID (e.g., "real-estate")

Request Body:

{ "name": "My Real Estate Data", "description": "Cloned from Real Estate domain", "includeSampleData": true, "customPrefix": "My"

}

Response (200 OK):

{ "success": true, "dataSet": { "id": "dataset-uuid", "name": "My Real Estate Data", "domain": "real-estate", "csvFiles": [ { "id": "csv-uuid-1", "tableName": "Properties", "fileName": "My-Properties.csv", "rowCount": 10 }, { "id": "csv-uuid-2", "tableName": "Agents", "fileName": "My-Agents.csv", "rowCount": 5 } ], "relationships": [ { "from": "Properties", "to": "Agents", "type": "many-to-one", "fromKey": "AgentID", "toKey": "AgentID" } ] }, "message": "Domain data set cloned successfully"

}

---

Data Set CSV Info

Get CSV file information for linking wizard.

Endpoint: GET /:dataSetId/csv-info

Headers:

Authorization: Bearer

Response (200 OK):

{
  "success": true,

  "dataSetId": "dataset-uuid",

  "dataSetName": "Real Estate Listings",

  "csvFiles": [

    {

      "fileId": "csv-uuid-1",

      "tableName": "Properties",

      "fileName": "properties.csv",

      "columns": [

        { "name": "PropertyID", "type": "string", "isPrimaryKey": true },

        { "name": "Address", "type": "string" },

        { "name": "City", "type": "string" },

        { "name": "AgentID", "type": "string", "isForeignKey": true }

      ],

      "rowCount": 10

    },

    {

      "fileId": "csv-uuid-2",

      "tableName": "Agents",

      "fileName": "agents.csv",

      "columns": [

        { "name": "AgentID", "type": "string", "isPrimaryKey": true },

        { "name": "AgentName", "type": "string" },

        { "name": "Phone", "type": "string" }

      ],

      "rowCount": 5

    }

  ],

  "relationships": [

    {

      "from": "Properties",

      "to": "Agents",

      "fromKey": "AgentID",

      "toKey": "AgentID"

    }

  ]

}

Use Case: Powers the linking wizard in the Office Add-in for selecting files and columns.

---

Relationship Types

Many-to-One

One record in the "from" table relates to one record in the "to" table.

Example: Many properties → one agent

{ "from": "Properties", "to": "Agents", "type": "many-to-one", "fromKey": "AgentID", "toKey": "AgentID"

}

One-to-Many

One record in the "from" table relates to many records in the "to" table.

Example: One property → many photos

{ "from": "Properties", "to": "PropertyPhotos", "type": "one-to-many", "fromKey": "PropertyID", "toKey": "PropertyID"

}

Many-to-Many

Records in both tables can relate to multiple records in the other table (requires junction table).

Example: Products ↔ Categories (via ProductCategories)

---

Rate Limiting

Create/Update operations: 100 per 15 minutes

List/Get operations: 1000 per 15 minutes

Delete operations: 50 per 15 minutes

---

Common Error Codes

| Status Code | Description |

|-------------|-------------|

| 400 | Invalid data set configuration or relationships |

| 401 | Unauthorized - invalid JWT |

| 404 | Data set or CSV file not found |

| 409 | Duplicate table name or relationship |

| 500 | Data set operation failed |

---

Usage Examples

JavaScript

// Create data set
async function createDataSet(name, csvFiles, relationships) {

  const response = await fetch('https://app.datapublisher.io/api/data-sets', {

    method: 'POST',

    headers: {

      'Authorization': Bearer ${jwtToken},

      'Content-Type': 'application/json'

    },

    body: JSON.stringify({

      name: name,

      description: 'My data set',

      csvFiles: csvFiles,

      relationships: relationships

    })

  });

  return await response.json();

}


// List data sets

async function listDataSets() {

  const response = await fetch('https://app.datapublisher.io/api/data-sets', {

    headers: { 'Authorization': Bearer ${jwtToken} }

  });

  const { dataSets } = await response.json();

  return dataSets;

}


// Get data set details

async function getDataSetDetails(dataSetId) {

  const response = await fetch(https://app.datapublisher.io/api/data-sets/${dataSetId}, {

    headers: { 'Authorization': Bearer ${jwtToken} }

  });

  const { dataSet } = await response.json();

  return dataSet;

}


// Add CSV to data set

async function addCsvToDataSet(dataSetId, fileId, tableName, primaryKey) {

  const response = await fetch(https://app.datapublisher.io/api/data-sets/${dataSetId}/files, {

    method: 'POST',

    headers: {

      'Authorization': Bearer ${jwtToken},

      'Content-Type': 'application/json'

    },

    body: JSON.stringify({

      fileId: fileId,

      tableName: tableName,

      primaryKey: primaryKey

    })

  });

  return await response.json();

}


// Clone domain data set

async function cloneDomainDataSet(domainId, name) {

  const response = await fetch(https://app.datapublisher.io/api/data-sets/clone-domain/${domainId}, {

    method: 'POST',

    headers: {

      'Authorization': Bearer ${jwtToken},

      'Content-Type': 'application/json'

    },

    body: JSON.stringify({

      name: name,

      includeSampleData: true

    })

  });

  const { dataSet } = await response.json();

  return dataSet;

}


// Get CSV info for linking wizard

async function getDataSetCsvInfo(dataSetId) {

  const response = await fetch(https://app.datapublisher.io/api/data-sets/${dataSetId}/csv-info, {

    headers: { 'Authorization': Bearer ${jwtToken} }

  });

  const { csvFiles, relationships } = await response.json();

  return { csvFiles, relationships };

}


// Delete data set

async function deleteDataSet(dataSetId) {

  const response = await fetch(https://app.datapublisher.io/api/data-sets/${dataSetId}, {

    method: 'DELETE',

    headers: { 'Authorization': Bearer ${jwtToken} }

  });

  return await response.json();

}

---

Best Practices

Primary Keys: Always define primary keys for each table

Relationships: Define all relationships upfront

Table Names: Use clear, descriptive table names

Domain Templates: Start with domain templates when possible

Sample Data: Test with sample data before using real data

CSV Updates: Replace CSV files rather than modifying tables

Documentation: Document your data structure for team members

---

Data Sets API

Base URL

Authentication

Overview

Data Set Management

Create Data Set

List Data Sets

Get Data Set Details

Update Data Set

Delete Data Set

Data Set Files

Add CSV to Data Set

Remove CSV from Data Set

Replace CSV File

Clone Domain Data Set

Data Set CSV Info

Relationship Types

Many-to-One

One-to-Many

Many-to-Many

Rate Limiting

Common Error Codes

Usage Examples

JavaScript

Best Practices

Related Documentation