---
title: "Combine multiple Datasets into a single new merged Dataset"
method: POST
path: "/api/v1/datasets/combine"
tags: ["Dataset"]
---

# Combine multiple Datasets into a single new merged Dataset

`POST /api/v1/datasets/combine`

## Request

- The document declares no server URL.
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/adaptionlabs/apis/adaption-api/docs/api/v1/datasets/combine/post.ts> (a function with typed inputs; its response is checked against the schema)

Accepts an optional Idempotency-Key header to dedupe double-submits; when omitted, the server generates a unique key for this request. Returns the newly merged Dataset.

## Headers

- `Idempotency-Key` string

## Request body

- CombineRequestDto
  - `dataset_ids` string[], required: Source Dataset IDs to combine. Must all belong to the caller’s org and be in a combinable state.
  - `name` string, required: User-supplied name for the merged Dataset. Surfaced in the dataset list.

## Response `200`

Merged Dataset result.

- CombineResponseDto
  - `dataset_id` string, required: The newly created merged Dataset’s ID. Returns existing ID on idempotent replay.

## Other responses

- `400`: One of: (a) request shape rejected by class-validator (e.g. non-UUID id, fewer than 2 ids, name missing, or array longer than the DTO cap); (b) caller has no team; (c) compatibility validation failed. See `/combine/validate` for the structural issue codes. Warning-level issues are non-blocking and do not fail this endpoint.
- `401`: Missing or invalid credentials.
- `500`: Server-side failure while creating the merged Dataset.

## Changes

- **2026-09-15** `f4d1edd8f3d1`: 2 breaking, 3 info
  - the response's body type changed from no type to `object` for status `200`
  - removed the success response with the status `202`
  - added the new optional `header` request parameter `Idempotency-Key`
  - removed `#/components/schemas/CombineResponseDto, #/components/schemas/CombineJobResponseDto` from the response body `oneOf` list for the response status `200`
  - …1 more

[Operation history](https://skmtc.dev/adaptionlabs/apis/adaption-api/changes/api/v1/datasets/combine/post.md)

---

[API](https://skmtc.dev/adaptionlabs/apis/adaption-api.md) - [All operations](https://skmtc.dev/adaptionlabs/apis/adaption-api/llms.txt) - [OpenAPI document](https://skmtc.dev/adaptionlabs/apis/adaption-api/revisions/d4cf908c19a0?raw)