# Combine

## Combine multiple Datasets into a single new merged Dataset

**post** `/api/v1/datasets/combine`

Requires an Idempotency-Key header to dedupe double-submits. Returns the merged Dataset synchronously by default. When async combine is enabled, clients may send `Prefer: respond-async` to receive a background job handle.

### Body Parameters

- `dataset_ids: array of string`

  Source Dataset IDs to combine. Must all belong to the caller’s org and be in a combinable state.

- `name: string`

  User-supplied name for the merged Dataset. Surfaced in the dataset list.

### Returns

- `CombineResponseDto object { dataset_id }`

  - `dataset_id: string`

    The newly created merged Dataset’s ID. Returns existing ID on idempotent replay.

- `CombineJobResponseDto object { combine_job_id, status, dataset_id, error_message }`

  - `combine_job_id: string`

    Background combine job ID. Poll the combine job status endpoint until it succeeds or fails.

  - `status: "queued" or "running" or "succeeded" or "failed"`

    Current background combine job status.

    - `"queued"`

    - `"running"`

    - `"succeeded"`

    - `"failed"`

  - `dataset_id: unknown`

    The merged Dataset ID. Null until the background combine succeeds.

  - `error_message: unknown`

    Customer-safe failure message when the background combine fails.

### Example

```http
curl https://api.prod.adaptionlabs.ai/api/v1/datasets/combine \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ADAPTION_API_KEY" \
    -d '{
          "dataset_ids": [
            "string",
            "string"
          ],
          "name": "name"
        }'
```

#### Response

```json
{
  "dataset_id": "dataset_id"
}
```

## Validate that a set of Datasets can be combined

**post** `/api/v1/datasets/combine/validate`

Synchronous compatibility check. Returns a single `issues` array containing both blockers (`level: "error"`) and reconcilable concerns (`level: "warning"`). `compatible: false` means at least one error-level issue is present (cardinality, ownership, status, run_id). Warning-level entries — column-type mismatches, DPO sources missing ranked generations — are non-blocking; the merge resolves them automatically (mixed types downgrade to instruction_dataset, type mismatches CAST to a common type, etc.). Nothing is written.

### Body Parameters

- `dataset_ids: array of string`

  Source Dataset IDs to combine. Must all belong to the caller’s org and be in a combinable state.

### Example

```http
curl https://api.prod.adaptionlabs.ai/api/v1/datasets/combine/validate \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ADAPTION_API_KEY" \
    -d '{
          "dataset_ids": [
            "string",
            "string"
          ]
        }'
```

## Domain Types

### Combine Create Response

- `CombineCreateResponse = object { dataset_id }  or object { combine_job_id, status, dataset_id, error_message }`

  - `CombineResponseDto object { dataset_id }`

    - `dataset_id: string`

      The newly created merged Dataset’s ID. Returns existing ID on idempotent replay.

  - `CombineJobResponseDto object { combine_job_id, status, dataset_id, error_message }`

    - `combine_job_id: string`

      Background combine job ID. Poll the combine job status endpoint until it succeeds or fails.

    - `status: "queued" or "running" or "succeeded" or "failed"`

      Current background combine job status.

      - `"queued"`

      - `"running"`

      - `"succeeded"`

      - `"failed"`

    - `dataset_id: unknown`

      The merged Dataset ID. Null until the background combine succeeds.

    - `error_message: unknown`

      Customer-safe failure message when the background combine fails.

# Jobs

## Get the status of a background dataset combine job

**get** `/api/v1/datasets/combine/jobs/{combine_job_id}`

Returns the lifecycle state for an async combine request. This state is separate from Dataset.status; `dataset_id` is populated only after the output Dataset has been created.

### Path Parameters

- `combine_job_id: string`

### Returns

- `combine_job_id: string`

  Background combine job ID. Poll the combine job status endpoint until it succeeds or fails.

- `status: "queued" or "running" or "succeeded" or "failed"`

  Current background combine job status.

  - `"queued"`

  - `"running"`

  - `"succeeded"`

  - `"failed"`

- `dataset_id: unknown`

  The merged Dataset ID. Null until the background combine succeeds.

- `error_message: unknown`

  Customer-safe failure message when the background combine fails.

### Example

```http
curl https://api.prod.adaptionlabs.ai/api/v1/datasets/combine/jobs/$COMBINE_JOB_ID \
    -H "Authorization: Bearer $ADAPTION_API_KEY"
```

#### Response

```json
{
  "combine_job_id": "combine_job_id",
  "status": "queued",
  "dataset_id": {},
  "error_message": {}
}
```

## Domain Types

### Job Get Response

- `JobGetResponse object { combine_job_id, status, dataset_id, error_message }`

  - `combine_job_id: string`

    Background combine job ID. Poll the combine job status endpoint until it succeeds or fails.

  - `status: "queued" or "running" or "succeeded" or "failed"`

    Current background combine job status.

    - `"queued"`

    - `"running"`

    - `"succeeded"`

    - `"failed"`

  - `dataset_id: unknown`

    The merged Dataset ID. Null until the background combine succeeds.

  - `error_message: unknown`

    Customer-safe failure message when the background combine fails.