> 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/apis/project-data-and-batch-queues-api.md).

# Project data and Batch Queues API

{% hint style="info" %}
**Outcome:** List Data Units, upload files, attach governed sources, and monitor ingestion.
{% endhint %}

### Data Unit and Batch Queue endpoints

| Method | Endpoint                                                                        | Purpose                                      |
| ------ | ------------------------------------------------------------------------------- | -------------------------------------------- |
| GET    | `/api/sdk/projects/{project_id}/data-units/`                                    | List loose datasource and grouped work units |
| GET    | `/api/sdk/projects/{project_id}/data-units/{unit_id}/`                          | Retrieve one Data Unit                       |
| GET    | `/api/sdk/projects/{project_id}/upload-info/`                                   | Read accepted formats and size limits        |
| POST   | `/api/sdk/projects/{project_id}/upload-data/`                                   | Upload one multipart file                    |
| POST   | `/api/sdk/projects/{project_id}/medical-upload-sessions/{session_id}/finalize/` | Finalize medical uploads                     |
| GET    | `/api/sdk/projects/{project_id}/upload-sessions/`                               | List Batch Queues                            |
| GET    | `/api/sdk/projects/{project_id}/upload-sessions/{queue_id}/`                    | Read one queue                               |
| GET    | `/api/sdk/projects/{project_id}/upload-sessions/{queue_id}/status/`             | Read processing counts                       |
| GET    | `/api/sdk/projects/{project_id}/upload-sessions/{queue_id}/data/`               | Inspect normalized item results              |

Data Unit filters are `search`, `data_type`, `status`, `batch_queue`, and `kind`.

```bash
curl --fail-with-body --silent --show-error \
  "$UNITLAB_API_URL/api/sdk/projects/PROJECT_ID/data-units/?data_type=image&status=annotate&kind=group" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY"
```

### Upload one file

Read upload-info first. Generate one UUID as `session_id` and reuse it for every file in the same batch.

```bash
SESSION_ID="YOUR_UUID"
curl --fail-with-body --silent --show-error \
  -X POST "$UNITLAB_API_URL/api/sdk/projects/PROJECT_ID/upload-data/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -F "session_id=$SESSION_ID" \
  -F "fps=2.0" \
  -F "file=@./clip.mp4"
```

The response must include `datasource_id`. Video uploads accept `fps`. Finalize a medical session after all medical files transfer successfully.

### Attach governed workspace data

| Method | Endpoint                                                                      | Purpose                                     |
| ------ | ----------------------------------------------------------------------------- | ------------------------------------------- |
| POST   | `/api/sdk/projects/{project_id}/attach-data/preview/`                         | Validate selection without mutation         |
| POST   | `/api/sdk/projects/{project_id}/attach-data/commit/`                          | Attach reviewed folders or Dataset versions |
| GET    | `/api/sdk/projects/{project_id}/attached-sources/`                            | List source links                           |
| GET    | `/api/sdk/projects/{project_id}/attached-sources/{source_id}/detach-preview/` | Preview detach impact                       |
| POST   | `/api/sdk/projects/{project_id}/attached-sources/{source_id}/detach/`         | Detach one source link                      |

```bash
ATTACH_BODY='{"folder_ids":[],"dataset_ids":[],"dataset_versions":[{"dataset_id":"DATASET_ID","version_number":3}],"fps":2.0}'
curl --fail-with-body --silent --show-error \
  -X POST "$UNITLAB_API_URL/api/sdk/projects/PROJECT_ID/attach-data/preview/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$ATTACH_BODY"
```

Commit the same body only after preview resolves the intended asset count. If commit returns a queue ID, poll until `processing` is zero, then inspect `failed` and queue data.

### Request operating contract

| Concern           | Required behavior                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| Execution surface | TLS-verified client using the reviewed current public `/api/sdk/...` route contract.                  |
| Identity          | Least-privilege workspace service identity; secrets remain outside code and logs.                     |
| Request boundary  | URL-encoded stable IDs, explicit deadlines, structured errors, and complete pagination.               |
| Success evidence  | Response identifiers, read-after-write verification, and separate processing status for Batch Queues. |

{% hint style="warning" %}
Do not infer undocumented private routes. After a timeout, inspect remote state before repeating a mutation.
{% endhint %}