> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.toloka.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# client.pipelines.replaceGraph()

> Replace the pipeline graph.

Send the complete graph, up to 2 MiB, and optionally `expectedVersion`. Returns the updated pipeline metadata. Invalid configuration or missing secrets returns 400; failed checks and lint findings do not block this write. An attached dataset cannot be removed. A stale version, concurrent edit, or active run returns 409; read the graph again before retrying.

## Signature

Method signature on `client.pipelines`:

```ts theme={null}
replaceGraph(args: {
  pipelineId: string;
  graph: PipelineGraphV1;
  expectedVersion?: string;
} | {
  pipelineId: string;
  graph: PipelineGraphV1;
  version: string;
  invalidFieldSchemas: InvalidFieldSchema[];
}): Promise<Pipeline>;
```

## Parameters

Pass one of the argument shapes shown in the signature.

**pipelineId** `string` *required*

Pipeline ID with prefix `pl.`.

**graph** `PipelineGraphV1` *required*

Complete pipeline graph in version 1 of the public graph format.

**Fields**

**version** `1` *required*

Graph format version; always 1.

**fields** `object[]` *required*

Fields used by the pipeline, with names and JSON Schemas.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/pipeline-graph/replace-pipeline-graph.md) for the complete schema.

**nodes** `(RootNode | CodeNode | GenerationNode | MatchNode | QuorumNode)[]` *required*

Nodes that make up the pipeline.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/pipeline-graph/replace-pipeline-graph.md) for the complete schema.

**connections** `object[]` *required*

Directed connections between node handles.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/pipeline-graph/replace-pipeline-graph.md) for the complete schema.

**layout** `object`

Optional node positions for the visual editor, keyed by node ID and block group; each position is an \[x, y] pair.

**Fields**

**\[key: string]** `object`

**expectedVersion** `string`

The snapshot version expected to still be active. A stale version is rejected with HTTP 409.

**version** `string`

The snapshot version. The SDK sends it as `expectedVersion` when you pass a graph snapshot.

**invalidFieldSchemas** `InvalidFieldSchema[]`

Snapshot diagnostics accepted when passing a complete graph snapshot. The SDK sends only `graph` and `version` (as `expectedVersion`); these diagnostics are not submitted.

**Fields**

**fieldId** `string` *required*

The id of the field in `graph.fields`.

**text** `string` *required*

The stored JSON Schema text, exactly as saved.

**reason** `string` *required*

Why the stored text is not a usable JSON Schema.

## Returns

`Promise<Pipeline>`

A pipeline within a project.

**id** `PipelineId` *required*

Pipeline ID with prefix `pl.`.

**projectId** `ProjectId` *required*

Project ID with prefix `pp.`.

**name** `string` *required*

Name of the pipeline.

**version** `number` *required*

Pipeline version number; copying a pipeline increments the source version.

**createdAt** `string` *required*

Time the pipeline was created, as an ISO 8601 timestamp.

**updatedAt** `string` *required*

Time the pipeline was last updated, as an ISO 8601 timestamp.

## Errors

HTTP errors throw [`PotatoApiError`](https://docs.platform.toloka.ai/docs/sdk/errors). The endpoint documents these error responses:

| Status | Description |
| - | - |
| 400 | Pipeline graph is too large, invalid, or references missing secrets |
| 404 | Pipeline not found |
| 409 | The expected graph version is stale, the graph changed while the request was processed, or the pipeline has an active run and cannot be changed |
| 429 | Rate limit exceeded |

HTTP endpoint: [`PUT /pipelines/{pipelineId}/graph`](https://docs.platform.toloka.ai/docs/api-reference/pipeline-graph/replace-pipeline-graph).

```ts replaceGraph() theme={null}
import assert from "node:assert/strict";
import { createClient } from "@toloka-platform/sdk";

const client = createClient({
  baseUrl: "https://platform.toloka.ai",
  apiKey: process.env.TOLOKA_API_KEY!,
});

const snapshot = await client.pipelines.getGraph({ pipelineId: "pl.019a0000-0000-7000-8000-000000000001" });
const graph = structuredClone(snapshot.graph);
const root = graph.nodes.find((node) => node.type === "root");
assert(root, "The pipeline has no Start node.");
root.settings.itemLimit = 100;

const pipeline = await client.pipelines.replaceGraph({
  pipelineId: "pl.019a0000-0000-7000-8000-000000000001",
  graph: graph,
  expectedVersion: snapshot.version
});
console.log(pipeline);
```

```json replaceGraph() theme={null}
{
  "id": "pl.019a0000-0000-7000-8000-000000000001",
  "projectId": "pp.019a0000-0000-7000-8000-000000000001",
  "name": "<string>",
  "version": 0,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.