---
url: /orchestration/reference/operations/InvokeMergeStepTemplate.md
description: 'POST /v2/consumer/recipes/merge — Merge'
---

> Documentation index: https://developer.civitai.com/llms.txt — every page on this site has a markdown version at its URL + `.md`.

# Merge

`POST https://orchestration.civitai.com/v2/consumer/recipes/merge`

Operation `InvokeMergeStepTemplate` · Recipes · Civitai Orchestration API, generated from the published OpenAPI spec ([v2-consumers.json](https://developer.civitai.com/openapi/v2-consumers.json)); the interactive HTML page is this URL without `.md`.

Also waits for every step the referenced steps generate, such as each iteration of a repeat.

## Authentication

Send `Authorization: Bearer <token>` (the spec's `ApiKey` scheme); this operation documents `401 Unauthorized` for a missing or invalid token. See [Authentication](https://developer.civitai.com/orchestration/guide/authentication.md).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `experimental` | query | boolean | no |  |
| `allowMatureContent` | query | boolean | no |  |
| `whatif` | query | boolean | no |  |
| `ephemeral` | query | boolean | no |  |
| `tier` | query | `WorkflowTier` (one of `paid`, `free`) | no | How a workflow is paid for. |

## Request body

Optional. Content types: `application/json`, `text/json`, `application/*+json`.

Schema `MergeInput`.

| Field | Type | Required | Description |
|---|---|---|---|
| `onMissing` | `MergeMissingBehavior` (one of `fail`, `partial`) | yes | What to do when a source item selected by a `[*]` has no output, e.g. a repeat iteration that failed. |
| `fields` | map of `MergeField` | yes | The fields of the merged result, keyed by the name each appears under in the output. |

### Types used by the request body

#### MergeField

Schema `MergeField` — One field of a merge: where its values come from and how they are combined.

| Field | Type | Required | Description |
|---|---|---|---|
| `$ref` | string | yes | The name of the step to read from, or `$arguments` for the workflow's arguments. |
| `path` | string | yes | The path to the values, e.g. `output.steps[*].output.nsfwLevel`. `[*]` selects the rest of the path from every item of a list; nested `[*]` flatten into one list. |
| `reduce` | `MergeReducer` (one of `max`, `min`, `sum`, `avg`, `count`, `any`, `all`, `first`, `last`, `push`, `addToSet`, `top`, `group`) | yes | How a merge field combines its values. Null values are skipped, except by `any` and `all`, which count them as false. |
| `by` | string, nullable | no | For `group`: the property of each item to group by. |
| `sortBy` | map of integer (int32), nullable | no | For `top` and `group`: the properties to rank items by, in order, each 1 (ascending) or -1 (descending). |
| `includeIndex` | boolean | yes | For `max`, `min`, `top` and `push`: wrap each result as `{ value, index }`, where index is the position of its source item in the first `[*]` of the path. |

## Responses

### 200 OK

Content type: `application/json`.

Schema `MergeOutput`.

| Field | Type | Required | Description |
|---|---|---|---|
| `fields` | object | yes | The merged values, keyed by the field names of the input. Their shape follows the requested reducers. |
| `sourceCount` | integer (int32) | yes | The number of source items selected by the first `[*]` of the fields' paths. |
| `mergedCount` | integer (int32) | yes | The number of source items whose values were merged. |
| `failedCount` | integer (int32) | yes | The number of source items left out because they had no output. |

### 400 Bad Request

Content type: `application/json`.

Schema `ProblemDetails`.

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string, nullable | no |  |
| `title` | string, nullable | no |  |
| `status` | integer (int32), nullable | no |  |
| `detail` | string, nullable | no |  |
| `instance` | string, nullable | no |  |

### 401 Unauthorized

Content type: `application/json`.

Schema `ProblemDetails` — fields as listed above.

### 403 Forbidden

Content type: `application/json`.

Schema `ProblemDetails` — fields as listed above.