How do I add dataset layers to a Data Studio project?

A Bearer JWT, organization membership, the DATA_STUDIO_CREATE permission, and the data-studio add-on.

1. What a layer is

A layer references one or more datasets and carries display and filter settings. A layer entry has an id (stable within the project), a name, a datasetIds array, a color, a visible boolean, and an optional filters object (search, categories, cities, countries, postal codes and more).

2. Layers live in the project configuration

There is no separate "add layer" REST route. Layers live inside the project's pipeline configuration, which you set by sending the configuration object on PUT .../projects/:projectId. To add a layer, fetch the project, add an entry to the layer list, and write the whole configuration back.

curl -X PUT \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{ "pipeline": { "version": 1, "layers": [ { "id": "layer-hotels", "name": "Hotels (NL)", "datasetIds": ["nl-hotels-poi"], "color": "#2563eb", "visible": true, "filters": { "countries": ["nl"] } } ], "transformers": [], "output": { "format": "csv", "includeCoordinates": true, "fields": { "mappings": [] } } } }' \
  "https://api.topolab.nl/v1/organization/{organizationId}/data-studio/projects/{projectId}"

The response is the updated project including the stored configuration.

Send the full list every time

To add more layers, send the complete layer list on each PUT — the configuration is replaced, not merged, so any layer you omit is dropped.