Datasets API

Datasets are the reference data behind your Droplet forms. They power lookups, dropdown options, autofill, and validation, so the people filling out a form always see the right products, locations, price lists, or account records. Each dataset is versioned: you build up a new version, publish it when it is ready, and forms pick up the published data. This API lets you find datasets, read their metadata and rows, create and edit them, manage versions and publishing, tag and archive them in bulk, and see which forms depend on a given dataset.

The base URL for every request is https://api.droplet.io, and the paths below are appended to it. Authenticate each request with a bearer token (a JWT) in the Authorization header:

Authorization: Bearer <token>

Every response is wrapped in a standard envelope. A successful call returns success: true with the payload under data; a failed call returns success: false with an error object holding a code and message. Both carry a requestId you can quote when contacting support. Examples show the fields you will most commonly use; a record may include more, so ignore any you do not recognize.

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": { /* ... */ }
}

Listing and lookup

List dataset IDs

GET /v1/datasets/ids

Returns the IDs of datasets that match your filters, along with a total count. This is the entry point for discovery: search by name, narrow by tag or status, sort the results, then hydrate the IDs you care about with POST /v1/datasets/entities.

curl https://api.droplet.io/v1/datasets/ids?search=products&status=active&sort=name \
  -H "Authorization: Bearer <token>"

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": {
    "count": 3,
    "ids": ["id1", "id2", "id3"]
  }
}

Fetch records for multiple datasets

POST /v1/datasets/entities

Returns full dataset records for a list of IDs in a single call. Pair this with GET /v1/datasets/ids to turn a filtered ID list into hydrated dataset objects. IDs may be strings or integers.

curl -X POST https://api.droplet.io/v1/datasets/entities?include=name,description \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["id1", "id2", "id3"] }'

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": [
    {
      "id": "id1",
      "created": "2026-01-04T12:00:00Z",
      "modified": "2026-05-18T09:30:00Z",
      "archived": false,
      "name": "Products",
      "description": "Active product catalog",
      "metadata": { "owner": "ops" },
      "tags": { "region": "us" },
      "publishedVersionId": 42,
      "publishedVersion": "v3",
      "permissions": { "read": true, "write": true }
    }
    // ...
  ]
}

Get a dataset

GET /v1/datasets/:id

Returns a single dataset by its ID, including its metadata, tags, permissions, and the currently published version reference.

curl https://api.droplet.io/v1/datasets/:id \
  -H "Authorization: Bearer <token>"

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": {
    "id": "id1",
    "created": "2026-01-04T12:00:00Z",
    "modified": "2026-05-18T09:30:00Z",
    "archived": false,
    "name": "Products",
    "description": "Active product catalog",
    "metadata": {},
    "tags": { "region": "us" },
    "publishedVersionId": 42,
    "publishedVersion": "v3",
    "permissions": { "read": true, "write": true }
  }
}

List forms that depend on a dataset

GET /v1/datasets/:id/forms

Returns the forms that reference a given dataset, so you can see what will be affected before you edit, archive, or republish. Each entry tells you the form's current version and the dataset version it is pinned to.

curl https://api.droplet.io/v1/datasets/:id/forms?show=active \
  -H "Authorization: Bearer <token>"

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": {
    "forms": [
      {
        "id": "form_1",
        "name": "Order Intake",
        "version": "v2",
        "currentVersion": "v5"
      }
      // ...
    ]
  }
}

Creating and updating datasets

Create a dataset

POST /v1/datasets

Creates a new dataset shell with a name and description. Both fields are required. Once created, add data by creating a version (see below) and then publishing it.

curl -X POST https://api.droplet.io/v1/datasets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Products", "description": "Active product catalog" }'

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": {
    "id": "id1",
    "created": "2026-06-21T10:00:00Z",
    "modified": "2026-06-21T10:00:00Z",
    "archived": false,
    "name": "Products",
    "description": "Active product catalog",
    "metadata": {},
    "tags": {},
    "publishedVersionId": null,
    "publishedVersion": null,
    "permissions": { "read": true, "write": true }
  }
}

Update dataset metadata

PUT /v1/datasets/:id

Updates a dataset's name or description. Send only the fields you want to change. This edits metadata only; to change rows or columns, work with versions.

curl -X PUT https://api.droplet.io/v1/datasets/:id \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Updated product catalog" }'

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": {
    "id": "id1",
    "name": "Products",
    "description": "Updated product catalog",
    "archived": false,
    "publishedVersionId": 42,
    "publishedVersion": "v3"
    // ...
  }
}

Versions, rows, and columns

A dataset's actual rows and column schema live in versions. You create a version with the data and a configuration that describes the columns, edit it while it is in draft, then publish it to make it live for forms. The configuration object carries fileSize, rowCount, and a required columnConfigurations array, where each column declares a name, an identifier, whether to include it, and its columnType. The single-version endpoint returns the rows in data by default; use its include parameter to choose which fields come back. The list-versions endpoint omits row data (it comes back null) to stay lightweight, and configuration may be null for a version that has none.

List versions of a dataset

GET /v1/datasets/:id/versions

Returns every version of a dataset with its column configuration, row count, lock state, and who last modified it. Use this to review history or find the version ID you want to publish or delete.

curl https://api.droplet.io/v1/datasets/:id/versions \
  -H "Authorization: Bearer <token>"

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": {
    "count": 3,
    "versions": [
      {
        "id": 42,
        "version": "v3",
        "modified": "2026-05-18T09:30:00Z",
        "archived": false,
        "publishedAt": "2026-05-18T10:00:00Z",
        "modifiedBy": { "name": "Ada Lovelace", "email": "ada@example.com" },
        "datasetVersionDataId": 901,
        "data": null,
        "locked": true,
        "formVersionsCount": 3,
        "configuration": {
          "fileSize": 20480,
          "rowCount": 120,
          "columnConfigurations": [
            { "name": "SKU", "identifier": "sku", "include": true, "columnType": "string" }
            // ...
          ]
        }
      }
      // ...
    ]
  }
}

Create a version

POST /v1/datasets/:id/versions

Creates a new version for a dataset, supplying the row data and a configuration describing its columns. The new version starts unpublished; publish it separately when ready.

curl -X POST https://api.droplet.io/v1/datasets/:id/versions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "data": [{ "sku": "A-100", "name": "Widget" }],
        "configuration": {
          "fileSize": 2048,
          "rowCount": 1,
          "columnConfigurations": [
            { "name": "SKU", "identifier": "sku", "include": true, "columnType": "string" },
            { "name": "Name", "identifier": "name", "include": true, "columnType": "string" }
          ]
        }
      }'

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": {
    "id": 43,
    "version": "v4",
    "archived": false,
    "publishedAt": null,
    "locked": false,
    "datasetVersionDataId": 902,
    "data": null,
    "formVersionsCount": 0,
    "configuration": {
      "rowCount": 1,
      "columnConfigurations": [ /* ... */ ]
    }
  }
}

Get a specific version

GET /v1/datasets/:id/versions/:version

Returns a single dataset version, including its rows and configuration. Use the include query parameter to narrow the response to specific fields; valid values are archived, locked, configuration, modified, data, and version. For example, include=data returns just the rows.

curl https://api.droplet.io/v1/datasets/:id/versions/:version?include=version,data \
  -H "Authorization: Bearer <token>"

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": {
    "id": 42,
    "version": "v3",
    "archived": false,
    "publishedAt": "2026-05-18T10:00:00Z",
    "locked": true,
    "datasetVersionDataId": 901,
    "data": [ /* ... */ ],
    "formVersionsCount": 3,
    "configuration": {
      "rowCount": 120,
      "columnConfigurations": [ /* ... */ ]
    }
  }
}

Update a version

PUT /v1/datasets/:id/versions/:version

Updates the row data or column configuration of an existing version. This is how you edit rows and adjust the schema before publishing.

curl -X PUT https://api.droplet.io/v1/datasets/:id/versions/:version \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "data": [{ "sku": "A-100", "name": "Widget Pro" }],
        "configuration": {
          "rowCount": 1,
          "columnConfigurations": [
            { "name": "SKU", "identifier": "sku", "include": true, "columnType": "string" },
            { "name": "Name", "identifier": "name", "include": true, "columnType": "string" }
          ]
        }
      }'

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": {
    "id": 43,
    "version": "v4",
    "locked": false,
    "archived": false,
    "configuration": {
      "rowCount": 1,
      "columnConfigurations": [ /* ... */ ]
    }
    // ...
  }
}

Publish a version

POST /v1/datasets/:id/versions/:version/publish

Publishes a version, making its data the live source for forms that use the dataset. The published version becomes the dataset's publishedVersion.

curl -X POST https://api.droplet.io/v1/datasets/:id/versions/:version/publish \
  -H "Authorization: Bearer <token>"

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": {
    "id": 43,
    "version": "v4",
    "archived": false,
    "publishedAt": "2026-06-21T11:00:00Z",
    "locked": true,
    "formVersionsCount": 0,
    "configuration": {
      "columnConfigurations": [ /* ... */ ]
    }
    // ...
  }
}

Delete a version

DELETE /v1/datasets/:id/:version

Deletes a specific version of a dataset. On success, data is null.

curl -X DELETE https://api.droplet.io/v1/datasets/:id/:version \
  -H "Authorization: Bearer <token>"

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": null
}

Bulk archive, restore, and tagging

These endpoints act on many datasets at once. Each takes an ids array and returns the number of datasets affected as count.

Archive datasets

POST /v1/datasets/archive

Archives one or more datasets. Archived datasets are hidden from active listings but can be brought back with restore.

curl -X POST https://api.droplet.io/v1/datasets/archive \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["id1", "id2", "id3"] }'

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": { "count": 3 }
}

Restore datasets

POST /v1/datasets/restore

Restores previously archived datasets, returning them to the active list.

curl -X POST https://api.droplet.io/v1/datasets/restore \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["id1", "id2", "id3"] }'

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": { "count": 3 }
}

Add a managed tag value

PUT /v1/datasets/tags/:key/add

Adds a managed tag value under a given key to the specified datasets. Managed tags are the same keys you can filter on with tagKey and tagValue when listing.

curl -X PUT https://api.droplet.io/v1/datasets/tags/:key/add \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["id1", "id2", "id3"], "value": "us" }'

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": { "count": 3 }
}

Remove a managed tag

PUT /v1/datasets/tags/:key/remove

Removes the managed tag identified by key from the specified datasets.

curl -X PUT https://api.droplet.io/v1/datasets/tags/:key/remove \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["id1", "id2", "id3"] }'

{
  "requestId": "req_8f2c...",
  "success": true,
  "data": { "count": 3 }
}