Pipeline Configuration

Export a pipeline’s configuration as a JSON file for backup or version control, import a file into a pipeline, or promote one pipeline’s configuration to another, such as staging to production.

In the Management UI, open the pipeline and choose Settings, then Configuration. Export downloads the file. Import… and Promote to… show the changes and create the draft.

What a file carries

{
  "format": "datafly-pipeline-config",
  "version": 1,
  "exported_at": "2026-09-28T10:00:00Z",
  "source": {
    "pipeline_id": "pip_staging",
    "pipeline_name": "Shop (staging)",
    "version_number": 12,
    "version_status": "published"
  },
  "pipeline": {
    "name": "Shop (staging)",
    "type": "web",
    "settings": { "consent_mode": "implicit", "bot_filter_rules": { "enabled": true }, "config": {} },
    "environment": { "domain_allowlist": ["staging.example.com"], "rate_limit_rps": 1000 },
    "collector": { "script_filename": "d.js" },
    "parameters": { "measurement_id": "G-STAGING" }
  },
  "integrations": [
    {
      "name": "Meta",
      "vendor": "meta_capi",
      "enabled": true,
      "consent_category": "marketing",
      "delivery_mode": "server_side",
      "event_blueprint": { "events": {} },
      "connection": { "pixel_id": "123456789" },
      "secrets": ["access_token"]
    }
  ]
}

A file holds the whole configuration of one version of the pipeline, published by default. When you import it, you choose which parts to apply.

What an import applies

The defaults suit a promotion from staging to production: behaviour moves, while each environment keeps its own domains, credentials and IDs.

How integrations are matched

For each integration in the file, the import looks for the target’s integration to update:

1. the integration whose ID integration_map gives for it, when you supply one. This can be an integration of the organisation that the pipeline does not have yet, which the import then attaches (attach);
2. otherwise the target’s only integration of the same vendor;
3. otherwise, where the target has several of that vendor, the one with the same name.

If none of these decides it, the import reports an error and asks for integration_map.

When the target has no integration of that vendor, the import adds one. If the name is already taken in the organisation, the target pipeline’s name is added to it, for example Meta (Shop). A new integration needs its secret settings: supply them in secrets, or it is added disabled until you set its credentials and enable it.

The target’s integrations that are not in the file are kept, unless you set remove_missing.

Settings are applied at publish

Pipeline settings take effect when the draft is published, not when it is created. If someone changes one of those settings on the target after the import, publishing is refused with 409, so an import never overwrites a newer edit. Discard the draft and import again.

Export

GET /v1/admin/pipelines/{id}/config/export

Downloads the pipeline’s configuration as <slug>-v<version>.json.

curl -X GET "http://localhost:8084/v1/admin/pipelines/pip_staging/config/export" \
  -H "Authorization: Bearer {access_token}" \
  -o shop-staging.json

Import

POST /v1/admin/pipelines/{id}/config/import

Imports a file into this pipeline. Send "dry_run": true first to see the changes; nothing is written.

curl -X POST "http://localhost:8084/v1/admin/pipelines/pip_new/config/import" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"config": '"$(cat shop-staging.json)"', "dry_run": true}'

Response: a dry run returns 200 with "dry_run": true and the plan. An import returns 201 with the draft it created and the plan:

{
  "draft_version_id": "ver_abc",
  "draft_version": 1,
  "plan": {
    "valid": true,
    "sections": ["integrations", "settings"],
    "settings": [
      { "section": "settings", "field": "consent_mode", "from": "explicit", "to": "implicit" }
    ],
    "integrations": [
      { "name": "Meta", "vendor": "meta_capi", "action": "add", "target_name": "Meta (Shop)", "secrets_missing": ["access_token"], "disabled_until_secrets": true }
    ]
  }
}

Errors:

Promote

POST /v1/admin/pipelines/{id}/config/promote

Imports this pipeline’s configuration into another pipeline in the same organisation, without a file. It takes the same fields as an import, except config, plus:

curl -X POST "http://localhost:8084/v1/admin/pipelines/pip_staging/config/promote" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"target_pipeline_id": "pip_production", "dry_run": true}'

The response and errors are those of an import.

Permissions and audit

Exporting needs read access to pipelines and integrations. Importing and promoting need permission to create pipeline versions and integrations: org_admin, source_admin and source_editor have it. Publishing the draft follows the pipeline’s normal rules, including approval where the organisation requires it.

Each export, import and promotion is recorded in the audit log as pipeline_config.exported, pipeline_config.imported or pipeline_config.promoted, with what changed. Secret values are never recorded.