Write dataset tables – POST /v1/datasets/{datasetId}/tables

POST/v1/datasets/{datasetId}/tables

betaapiKeyworkspace

When to use

Write named JSON tables within an existing keyed dataset.

For agents

Use replace when rows can change or disappear. Append only for additive sources where the caller knows every row is new, and reuse the required batchId when retrying the same append.

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 (await client.datasets.create({ type: 'custom', key: 'quickbooks' })).replace({
  orders: [{ id: 1 }, { id: 2 }],
  customers: [{ id: 10 }, { id: 20 }],
});

Request body

json

{
  "mode": "replace",
  "tables": [
    {
      "name": "orders",
      "rowCount": 2
    },
    {
      "name": "customers",
      "rowCount": 2
    }
  ],
  "sizeBytes": 238,
  "contentHash": "d6d0ca8f6f15abca704f06170b14abecc0b18edb88685a9f0ffb844a1ebf2902"
}

Response

json

{
  "data": {
    "dataset": {
      "type": "custom",
      "id": "data_quickbooks123",
      "sourceId": "data_quickbooks123",
      "key": "quickbooks",
      "name": "QuickBooks",
      "context": [
        "quickbooks"
      ],
      "status": "pending",
      "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",
      "write": {
        "id": "dwrt_abc123",
        "status": "pending"
      }
    },
    "write": {
      "id": "dwrt_abc123",
      "status": "pending"
    },
    "upload": {
      "method": "PUT",
      "url": "https://datasets.example.com/signed-upload",
      "headers": {
        "Content-Type": "application/x-ndjson"
      },
      "expiresAt": "2026-06-27T12:20:00.000Z"
    },
    "pollAfterMs": 1000
  }
}