Run a pipeline

Session-authenticated portal API — authenticate with a portal Bearer token (session JWT), not an API key. It also requires the relevant organization permissions (DATA_STUDIO_ACCESS / DATA_STUDIO_CREATE / DATA_STUDIO_EXECUTE) and the Data Studio add-on on the organization.

A Data Studio project can run a pipeline, an ordered set of processing steps applied over its layers to produce a result. The pipeline turns the datasets you have added into the dataset you want.

How pipelines are defined

The pipeline is part of the project's workspace configuration, set through PUT .../projects/:projectId. It has three parts:

• layers, the datasets brought into the workspace (see Add a layer).
• transformers, the ordered processing steps.
• output, how the result is shaped (see Export output).

Each transformer has an id, a type, an order, and a config whose shape depends on the type. Transformer types include geographic intersection, deduplication, field mapping, merging, attribute and radius filtering, sort/limit, clustering, and data-quality checks.

Example

Configure a two-step pipeline: filter on an attribute, then deduplicate by proximity. Steps run in order:

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": {} }
      ],
      "transformers": [
        {
          "id": "step-filter",
          "type": "attribute_filter",
          "order": 1,
          "config": { "conditions": [ { "field": "stars", "operator": "in", "value": ["4", "5"] } ], "logic": "and" }
        },
        {
          "id": "step-dedupe",
          "type": "deduplicate",
          "order": 2,
          "config": { "strategy": "proximity", "proximityMeters": 50, "keepStrategy": "most_complete" }
        }
      ],
      "output": { "format": "geojson", "includeCoordinates": true, "fields": { "mappings": [] } }
    }
  }' \
  "https://api.topolab.nl/v1/organization/8f0c2e1a-4b6d-4c2a-9e3f-1a2b3c4d5e6f/data-studio/projects/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"

The response is the updated project with the stored pipeline.

Preview (dry run)

Preview runs the pipeline without materializing a stored result, useful to check the output before committing compute:

curl -X POST \
  -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/organization/8f0c2e1a-4b6d-4c2a-9e3f-1a2b3c4d5e6f/data-studio/projects/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/preview"

Execute

Execute runs the transformers in order over the layers and materializes an output dataset shaped by output:

curl -X POST \
  -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/organization/8f0c2e1a-4b6d-4c2a-9e3f-1a2b3c4d5e6f/data-studio/projects/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/execute"

The response identifies the generated result; retrieve it via Export output. Execution is compute-heavy, so it is gated behind the DATA_STUDIO_EXECUTE permission and more tightly rate limited, see Rate limits & credits.

Authentication

A Bearer JWT (see Authentication), organization membership, the data-studio addon, and DATA_STUDIO_CREATE to edit the pipeline / DATA_STUDIO_EXECUTE to run it.

Next

• Export output, shape and retrieve the result.
• Add a layer, the inputs a pipeline runs over.
• Want Data Studio enabled? Contact us.