Create a dataset – POST /v1/datasets

POST/v1/datasets

betaapiKeyworkspace

When to use

Create or retrieve a keyed custom dataset, or create a file dataset with a signed upload target.

For agents

For files, PUT bytes with every returned upload header; S3 starts processing automatically. For tables, reuse the same key.

Example

typescript

import { PermuteClient } from '@permute/sdk';

const orgClient = new PermuteClient({
  apiKey: process.env.PERMUTE_API_KEY!,
});

const client = orgClient.withWorkspace(process.env.PERMUTE_WORKSPACE_ID!);

const result = await client.datasets.create({
  "type": "custom",
  "key": "quickbooks",
  "name": "QuickBooks",
  "context": [
    "quickbooks"
  ]
});

Request body

json

{
  "type": "custom",
  "key": "quickbooks",
  "name": "QuickBooks",
  "context": [
    "quickbooks"
  ]
}

Response

json

{
  "data": {
    "type": "custom",
    "id": "data_quickbooks123",
    "sourceId": "data_quickbooks123",
    "key": "quickbooks",
    "name": "QuickBooks",
    "context": [
      "quickbooks"
    ],
    "status": "completed",
    "version": 3,
    "tables": [
      {
        "name": "orders",
        "rowCount": 250,
        "columnCount": 3
      },
      {
        "name": "customers",
        "rowCount": 80,
        "columnCount": 2
      }
    ],
    "createdAt": "2026-06-27T12:00:00.000Z",
    "updatedAt": "2026-06-27T12:05:00.000Z"
  }
}