> 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/assets-and-folders-api.md).

# Assets and folders API

{% hint style="info" %}
**Outcome:** Upload durable Assets, manage hierarchy and metadata, synchronize cloud folders, and create Data Groups.
{% endhint %}

### Endpoints

| Method | Endpoint                                                           | Purpose                                   |
| ------ | ------------------------------------------------------------------ | ----------------------------------------- |
| GET    | `/api/sdk/data-assets/folders/`                                    | List folders using `parent_id` or `all=1` |
| POST   | `/api/sdk/data-assets/folders/`                                    | Create a local or cloud-backed folder     |
| GET    | `/api/sdk/data-assets/folders/{folder_id}/`                        | Retrieve one folder                       |
| GET    | `/api/sdk/data-assets/folders/{folder_id}/items/`                  | List Assets inside a folder               |
| POST   | `/api/sdk/data-assets/upload/`                                     | Upload one multipart Asset                |
| PATCH  | `/api/sdk/data-assets/assets/{asset_id}/custom-metadata/`          | Replace or clear custom metadata          |
| POST   | `/api/sdk/data-assets/folders/{folder_id}/sync-cloud/`             | Synchronize a connected folder            |
| GET    | `/api/sdk/data-assets/folders/{folder_id}/auto-grouping/suggest/`  | Suggest filename grouping                 |
| POST   | `/api/sdk/data-assets/folders/{folder_id}/auto-grouping/estimate/` | Estimate groups                           |
| POST   | `/api/sdk/data-assets/folders/{folder_id}/auto-groups/`            | Create Data Groups                        |

### Create and upload

```bash
curl --fail-with-body --silent --show-error \
  -X POST "$UNITLAB_API_URL/api/sdk/data-assets/folders/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"Raw data","parent_id":"PARENT_FOLDER_ID"}'

curl --fail-with-body --silent --show-error \
  -X POST "$UNITLAB_API_URL/api/sdk/data-assets/upload/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -F "folder_id=FOLDER_ID" \
  -F "path=2026-07" \
  -F "tags=incoming" \
  -F 'custom_metadata={"source":"camera-7","shift":"night"}' \
  -F "file=@./frame-001.jpg"
```

If no folder ID exists, the first upload can send `folder_name`. Preserve the returned `folder_id` for remaining files. Custom metadata updates replace the complete object.

### Create Auto-Groups safely

1. Request a suggestion and inspect confidence and proposed keys.
2. Send the explicit configuration to estimate.
3. Review valid, incomplete, ambiguous, and skipped counts.
4. Send the approved configuration to `auto-groups/`.
5. Preserve `grouped_folder_id` and inspect the result before attaching it.

![Auto-Groups custom layout editor](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2F8eyEMKLe8RbL8q4uIsNW%2Fauto-groups-custom-layout.png?alt=media\&token=810552ad-bdf3-44b8-b959-3f3afe77847d)

*The API configuration represents grouping keys, tile rules, incomplete-group policy, and Grid, List, or Custom layouts.*

### 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 %}