---
title: "Copy or move images to a dataset"
method: POST
path: "/api/datasets/{owner}/{dataset}/images/adopt"
tags: ["Datasets"]
---

# Copy or move images to a dataset

`POST /api/datasets/{owner}/{dataset}/images/adopt`

## Request

- Base URL: `https://platform.ultralytics.com`
- URL: `https://platform.ultralytics.com/api/datasets/{owner}/{dataset}/images/adopt`
- Auth: HTTP bearer

Copies hosted images as content-addressed references without moving bytes. Omit release and classMapping for unlabeled train images. Set release to false (copy) or true (move), or supply classMapping, to preserve annotations, metadata, depth targets, and splits from editable sources; classes match by name. Other readable sources remain unlabeled train images. Moves delete only inserted source rows in the same transaction. Existing images are skipped.

## Path parameters

- `owner` string, required
- `dataset` string, required

## Request body

- object: Copy or move images into a dataset
  - `imageIds` string[], required
  - `release` boolean: Set false to copy editable-source annotations, metadata, depth targets, and splits; true also deletes source rows atomically. Omit both release and classMapping to adopt unlabeled train images.
  - `classMapping` object: Mapping from source class names to this dataset

## Response `200`

Images added

- AdoptImagesResponse
  - `adopted` integer, required: Images inserted; duplicates already held are skipped

## Other responses

- `400`: Invalid owner, dataset, image IDs, or class mapping
- `401`: Missing or invalid authentication
- `403`: Dataset editor access required
- `404`: Dataset not found
- `409`: Dataset is connected to external storage, or tasks, image channels, pose metadata, or depth scale do not match
- `422`: `unmatchedClasses` lists source classes with no match here; retry with classMapping
- `429`: Rate limit exceeded

## Changes

- **2026-09-21** `b7d3ee8a35a3`: 3 info
  - added the new optional request property `classMapping`
  - added the new optional request property `release`
  - added the non-success response with the status `422`
- **2026-09-03** `1279bde3d7c9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ultralytics/apis/ultralytics-platform-api/changes/api/datasets/:owner/:dataset/images/adopt/post.md)

---

[API](https://skmtc.dev/ultralytics/apis/ultralytics-platform-api.md) - [All operations](https://skmtc.dev/ultralytics/apis/ultralytics-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ultralytics/apis/ultralytics-platform-api/revisions/9c562e23b0e4?raw)