> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/api-sdk-cli/sdks/attach-and-detach-project-sources.md).

# Attach and detach project sources

Preview source attachment, attach folders or dataset versions, and detach only after impact review.

{% hint style="info" %}
**Outcome:** Preview source attachment, attach folders or dataset versions, and detach only after impact review.
{% endhint %}

```python
preview = project.attach_preview(
    dataset_versions=[{
        "dataset_id": "DATASET_ID",
        "version_number": 3,
    }]
)
print(preview.resolved_asset_count, preview.requires_fps)

result = project.attach(
    dataset_versions=[{
        "dataset_id": "DATASET_ID",
        "version_number": 3,
    }],
    fps=2.0,
)

for source in project.attached_sources():
    print(source.id, source.name)
    print(source.detach_preview())

# After reviewing a preview, detach that source by its ID.
project.detach_source("SOURCE_ID")
```

`AttachResult` reports created, already-attached, resolved, and unassigned counts; created datasource and Data Group IDs; attachment IDs; the project dataset version; and an optional Batch Queue ID. If a Batch Queue ID is present, monitor it before assigning work.

After reviewing the impact preview, detach one source with `project.detach_source(source)`, which takes an attached-source handle or its ID, or with `source.detach()` on the handle. `project.detach_source(source, preview=True)` returns the same preview as `source.detach_preview()` without detaching.

`attach_preview()` and `attach()` also take `dataset_ids`, which select the latest published version of each dataset, and `publish_unpublished` (default `False`). A dataset in `dataset_ids` that has no published version is listed in `preview.unpublished_datasets` and left out of `attach()`, which reports it in `result.skipped_datasets` with a `reason` of `unpublished` or `publish_failed`. With `publish_unpublished=True`, `attach()` publishes each such dataset as version 1, attaches it, and lists it in `result.published_datasets`. `attach_preview()` never publishes; there the flag only makes videos in those datasets count toward `requires_fps`.

`preview.skipped_files` and `result.skipped_files` count the files an attach leaves out, as `{"in_trash": n, "missing_in_bucket": n}`: files in library Trash, and cloud files that the last sync of their folder did not find in the bucket.

### Operating contract

| Concern           | Required behavior                                                                |
| ----------------- | -------------------------------------------------------------------------------- |
| Execution surface | Pinned `unitlab==3.1.6` application environment on Python 3.10+.                 |
| Identity          | Least-privilege API key supplied through approved configuration.                 |
| Target resolution | Stable resource IDs and an explicitly bounded target set.                        |
| Success evidence  | Typed return fields, server-side state, and downstream acceptance of the result. |

### Failure and recovery boundary

| Condition                                       | Response                                                                                                                      |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Authentication or authorization fails           | Stop, correct the service identity or access model, rotate exposed credentials, and rerun a read-only check.                  |
| Validation or entitlement rejects the operation | Correct the input or entitlement; do not retry an unchanged request.                                                          |
| Another attach into the same project is running | `attach()` raises `ConflictError` and attaches nothing. Retry after the running attach finishes.                              |
| Nothing is left to attach                       | `attach()` raises `ValidationError` naming the datasets it could not attach. Publish them or pass `publish_unpublished=True`. |
| A request times out                             | Inspect remote state before repeating a mutation because the server may have accepted it.                                     |
| Asynchronous processing exceeds its deadline    | Preserve the Batch Queue or release ID, continue bounded monitoring, and inspect item-level failures.                         |
| Only part of a batch succeeds                   | Keep successful identifiers, isolate failed rows, and retry only the corrected subset.                                        |

{% hint style="warning" %}
Pin and test the production SDK version. Use stable IDs, keep secrets out of logs and command history, and record the correlation ID, target IDs, counts, final state, and redacted error details for material state changes.
{% endhint %}

***

> **Related Unitlab capability guides:** [enterprise data annotation workflows](https://unitlab.ai/en/data-annotation)
