Assets and folders API

Upload durable Assets, manage hierarchy and metadata, synchronize cloud folders, and create Data Groups.

Outcome: Upload durable Assets, manage hierarchy and metadata, synchronize cloud folders, and create Data Groups.

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

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

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.

Do not infer undocumented private routes. After a timeout, inspect remote state before repeating a mutation.

---

Continue with Unitlab: training-data curation workflows