Understanding shared pipeline artifacts🔗

The Shared Pipeline Artifacts API lets you publish, list, inspect, and manage versioned shared pipeline artifacts programmatically. Use it to automate shared pipeline deployments from CI/CD, control version availability, and discover shared pipelines across your account.

Note

These endpoints require an Admin or Super Admin account role.

For background on shared pipelines in Designer, read Shared pipelines.

Key concepts🔗

Shared pipelines and artifacts🔗

In Designer, you can share individual pipelines from a project for reuse across your account. When the project is published, all of its shared pipelines are bundled into a single versioned artifact.

The API operates on these artifacts, not on individual shared pipelines. A single artifact version contains all shared pipelines from the source project at the time of publishing.

Terminology🔗

The API uses field names that correspond to concepts you already know from Designer:

API field	What it represents	Example
`sharedPipelineIdPrefix`	The group identifier for related shared pipelines. When publishing from Designer, this is the project name. When publishing via the API, this can also be a custom group name.	`etl-core`
`sharedPipelineId`	The Pipeline ID of an individual shared pipeline. This is the identifier set in the Share Pipeline dialog. This may differ from the pipeline file name if the Pipeline ID was customized in the Share Pipeline dialog.	`load-customers`
`versionName`	The version label for the artifact, set at publish time. Version names are immutable and cannot be overwritten.	`2.1.0`
`enabled`	Whether an artifact version is available to consumers. Disabled versions are excluded when consumers select [Latest].	`true`

Endpoints🔗

Method	Path	Description
`GET`	`/v1/shared-pipelines`	List all published shared pipelines across the account.
`GET`	`/v1/shared-pipelines/artifacts`	List published artifact versions with optional filters.
`GET`	`/v1/shared-pipelines/artifacts/details`	Get artifact metadata and the pipelines inside a version.
`POST`	`/v1/shared-pipelines/artifacts`	Publish a new artifact version.
`PATCH`	`/v1/shared-pipelines/artifacts`	Enable or disable a specific artifact version.

Choosing the right endpoint🔗

I want to...	Endpoint
See all shared pipelines available to run.	`GET /v1/shared-pipelines`
See all published versions for a given prefix.	`GET /v1/shared-pipelines/artifacts?sharedPipelineIdPrefix=etl-core`
See what pipelines are inside a specific version.	`GET /v1/shared-pipelines/artifacts/details?sharedPipelineIdPrefix=etl-core&versionName=2.1.0`
See what [Latest] resolves to.	`GET /v1/shared-pipelines/artifacts/details?sharedPipelineIdPrefix=etl-core` (omit `versionName`—returns the most recent enabled version)
Publish a new version from CI/CD.	`POST /v1/shared-pipelines/artifacts`
Roll back a broken version.	`PATCH /v1/shared-pipelines/artifacts` with `enabled: false`

Examples🔗

List all shared pipelines🔗

GET /v1/shared-pipelines?page=0&size=50

Response:

{
  "results": [
    {
      "sharedPipelineIdPrefix": "etl-core",
      "sharedPipelineId": "load-customers",
      "description": "Loads customer data from source systems",
      "latestVersionName": "2.1.0"
    },
    {
      "sharedPipelineIdPrefix": "etl-core",
      "sharedPipelineId": "transform-orders",
      "description": "Transforms raw order data",
      "latestVersionName": "2.1.0"
    }
  ],
  "page": 0,
  "size": 50,
  "total": 2
}

Inspect artifact contents🔗

Omit versionName to retrieve the latest enabled version:

GET /v1/shared-pipelines/artifacts/details?sharedPipelineIdPrefix=etl-core

Response:

{
  "artifactDetails": {
    "sharedPipelineIdPrefix": "etl-core",
    "versionName": "2.1.0",
    "enabled": true,
    "createdAt": "2025-01-15T10:30:00Z",
    "provider": "public-api",
    "commitHash": "a1b2c3d4e5f6",
    "branch": "main"
  },
  "sharedPipelines": [
    {
      "sharedPipelineId": "load-customers",
      "sourcePipeline": "pipelines/etl/load-customers",
      "description": "Loads customer data from source systems"
    },
    {
      "sharedPipelineId": "transform-orders",
      "sourcePipeline": "pipelines/etl/transform-orders",
      "description": "Transforms raw order data"
    }
  ]
}

Enable and disable🔗

The enable/disable operation (PATCH) works at the artifact version level. It affects all shared pipelines within that version, not individual pipelines.

Scenario	Action
A published version has breaking changes.	Disable it — consumers on [Latest] fall back to the previous enabled version.
The issue is fixed in a new version.	Optionally re-enable the old version, or leave it disabled.
You need to remove a single pipeline.	Update the configuration file and publish a new version — existing versions are unchanged.

Example request — disable🔗

PATCH /v1/shared-pipelines/artifacts
Content-Type: application/json

{
  "sharedPipelineIdPrefix": "etl-core",
  "versionName": "3.0.0",
  "enabled": false
}

Consumers using [Latest] automatically fall back to the most recent enabled version.

Warning

Ensure at least one known-good version remains enabled at all times. Disabling every version leaves consumers with no available version to run.

Note

Disabling an artifact version is different from unsharing a pipeline. Disabling affects an already-published version immediately. Unsharing affects future publishes only — existing versions remain unchanged.

Common mistakes🔗

Mistake	Impact	Resolution
Confusing `sharedPipelineIdPrefix` with `sharedPipelineId`.	Wrong parameter sent; unexpected results or errors.	The prefix is the group identifier (project name from Designer or custom name). The Pipeline ID is the individual pipeline name.
Expecting enable/disable to target a single pipeline.	All pipelines in the version are affected.	To remove one pipeline, update the configuration file and publish a new version.
Re-publishing an existing version name.	`409 Conflict` error.	Version names are immutable. Use a new version name instead.
Not checking `ignoredResources` after publishing.	Incomplete artifact published without notice.	Always inspect the publish response. Fail the CI/CD build if unexpected pipelines are listed.
Disabling all versions.	Consumer pipelines fail at runtime.	Keep at least one known-good version enabled.
Passing `versionName=latest` instead of omitting the parameter.	404 error—the API looks for a version literally named "latest".	Omit the `versionName` parameter entirely to get the latest enabled version.

Best practices🔗

Use consistent version naming — Semantic versioning (for example, 1.0.0) or date-based schemes help communicate the nature of changes.
Include git metadata — Pass commitHash and branch headers when publishing for traceability.
Verify after publishing — Call the details endpoint to confirm the artifact contents and enabled status.
Keep Pipeline IDs stable — Renaming a sharedPipelineId breaks consumer references.
Write clear descriptions — The description set in the Share Pipeline dialog is what consumers see when selecting a shared pipeline.
Understand [Latest] — [Latest] resolves to the most recent enabled version, not the most recently published version.

Troubleshooting🔗

A published pipeline doesn't appear in the list🔗

Confirm the pipeline was enabled in the configuration file at the time of publish.
Check if the artifact version is enabled.
Check the ignoredResources in the publish response for that pipeline.
Verify the querying user has an Admin or Super Admin account role.

Consumers see an old version after publishing🔗

Consumers using [Latest] get the most recent enabled version. Verify with GET /v1/shared-pipelines/artifacts/details?sharedPipelineIdPrefix=X (omit versionName) to see what [Latest] currently resolves to.

409 Conflict when publishing🔗

The sharedPipelineIdPrefix and versionName combination already exists. Version names are immutable. Use a new version name.

403 Forbidden🔗

The API requires an Admin or Super Admin account role. Contact your account administrator.