Project data and Batch Queues API
Upload local files and folders through the HTTP API, monitor Batch Queues, and attach workspace data to projects.
Upload each media file with an authenticated HTTP request, collect the returned item IDs, and wait for processing before importing labels or starting annotation. A local folder is a client-side loop of file uploads using one shared Batch Queue ID.
For a ready-made uploader, use CLI media uploads or Python project uploads. For existing labels, use the separate annotation import API.
Before you start
Use an existing project and a workspace API key. Complete authentication and load UNITLAB_API_KEY into your environment. The examples require Bash, curl, and Python 3.
Set the API origin and replace YOUR_PROJECT_UUID with your project's ID:
export UNITLAB_API_URL="https://api.unitlab.ai"
export PROJECT_ID="YOUR_PROJECT_UUID"Prepare two valid images and run the commands from road-scenes/:
road-scenes/
└── images/
├── road.jpg
└── crossing.jpgChoose either the single-file example or the folder example below. Running both uploads road.jpg twice. Send Authorization: Api-Key ... on Unitlab API requests.
Read the project's upload configuration before sending files:
curl --fail-with-body --silent --show-error \
"$UNITLAB_API_URL/api/sdk/projects/$PROJECT_ID/upload-info/" \
-H "Authorization: Api-Key $UNITLAB_API_KEY"accepted_formats
Extensions accepted by the ordinary media uploader.
max_file_sizes
Per-family limits for multipart form uploads, in bytes.
direct_max_file_sizes
Per-family limits for direct multipart uploads where supported.
max_file_size
Largest ordinary limit; do not apply this value to every family.
pointcloud
Separate LiDAR capability and limits, including enabled, accepted formats, and maximum size.
Use the limit for the file's family and upload transport. Format availability and limits depend on the deployment and workspace plan.
Upload one media file
Send multipart/form-data to POST /api/sdk/projects/{project_id}/upload-data/. Let your HTTP client set the multipart boundary.
file
Yes
One nonempty file.
session_id
Recommended; required for DICOM
A UUID shared by every file in the same upload batch. If omitted, the server creates a separate queue.
fps
No
Video sampling rate, at least 0.25; defaults to 1.0.
generic_type
No
Explicit geospatial, pathology, timeseries, or tabular family. Other ordinary file types are detected from the upload.
primary_column
No
CSV row mode only: the column used as the main text field. Use with generic_type=tabular.
thumbnail
No
Optional image thumbnail.
For this single-image example, expect one new item. Save the returned datasource_id and upload_session_id; the latter should match your SESSION_ID. Depending on the family, the response can be 201 Created or 202 Accepted, and may also include generic_type, upload_status, or task_id.
For video, add -F "fps=2.0". For CSV row mode, add -F "generic_type=tabular" and optionally -F "primary_column=text". A CSV uploaded without an explicit family can require configuration in the platform before processing can finish.
Upload a local folder or file list
The ordinary upload endpoint accepts one file per request. It does not accept a local directory path, a JSON list of local paths, or a JSON list of URLs as a media manifest. Read your folder or list locally and upload each selected file with the same session_id.
This Bash example uploads both images and recursively includes JPG, JPEG, and PNG files in any subfolders. It saves each response in upload-responses/:
With the example folder, expect road.jpg.json and crossing.jpg.json in upload-responses/, each containing its item ID. Keep these responses so you can associate local filenames with datasource_id. The shared UUID creates a Batch Queue, not a Data Group. Ordinary project uploads do not recreate your local subfolder hierarchy. Use unique basenames when you intend to match imported labels by filename, or match by the returned item IDs.
For grouped annotation views, upload to workspace Assets, create groups and layouts, and attach them to the project. See Assets and folders API and Grouped files and layouts. For connected cloud paths, use the Cloud storage API.
Monitor processing and inspect failures
Start polling after all files in your batch have been sent. Transfer success does not mean that video extraction, medical processing, or other preparation has completed.
For the two-image folder, a successful final response looks like this:
Poll with backoff and a deadline until processing is 0. The final status is completed, partial_failure, or failed. Check failed even when processing has stopped. Counts represent server-side data items and can differ from local file counts, for example when DICOM slices become one volume or CSV rows become separate items.
Inspect the paginated item results:
Verify that the results contain road.jpg and crossing.jpg, with no failed item. Each result contains datasource_id, file_name, generic_type, and upload_status. Follow the response's next link to read all pages. Preserve these IDs for label imports. After a request timeout, inspect the queue and item list before retrying the upload to avoid duplicate items.
Finalize medical form uploads
When sending DICOM files through upload-data/, reuse one session_id for the series and finalize once all files have transferred:
Finalization groups DICOM slices into volume items while their frame preparation completes. Then poll the Batch Queue. The SDK also finalizes medical batches sent through the ordinary form uploader; for NIfTI and NRRD files this grouping step is a no-op. Medical volumes uploaded through the direct multipart lifecycle below are already complete volumes and do not require this finalization call.
Upload large media directly
Supported geospatial and pathology files, plus video, medical, audio, and PDF files, can use direct multipart upload. The endpoint retains the name tiled-uploads. Use it when required by the ordinary upload limit and only when the server supports it.
POST
/api/sdk/projects/{project_id}/tiled-uploads/initiate/
Reserve an upload and receive signed part URLs.
POST
/api/sdk/projects/{project_id}/tiled-uploads/refresh/
Renew the upload token and selected part URLs.
POST
/api/sdk/projects/{project_id}/tiled-uploads/complete/
Confirm uploaded parts and start processing.
POST
/api/sdk/projects/{project_id}/tiled-uploads/abort/
Cancel an unfinished upload.
Send JSON to
initiate/withfile_name,file_sizein bytes, and the sharedsession_id. Optionalgeneric_typedisambiguates the supported family; optionalfpscontrols video sampling.Read
upload_token,datasource_id,part_size,part_urls, andexpires_in. Each part URL includes itspart_number.Split the file using the returned
part_size, thenPUTeach raw chunk to its signed URL. Do not send the Unitlab API key to storage URLs. Save each response'sETag.If needed, send
{"upload_token":"...","part_numbers":[1,2]}torefresh/and use the refreshed token and URLs.Send the token and every part's number and ETag to
complete/:
Completion returns 202 Accepted; poll the Batch Queue. To abandon an unfinished transfer, send {"upload_token":"..."} to abort/. The SDK handles splitting, retries, URL renewal, and completion for you.
LiDAR scenes have their own pointcloud-uploads/ and pointcloud-folder-uploads/ routes. Do not send a scene ZIP to the ordinary media endpoint or use a LiDAR token with tiled-uploads/. See LiDAR data preparation and the SDK project upload guide for supported scene input.
To check one LiDAR scene, send GET /api/sdk/projects/{project_id}/pointcloud-scenes/{datasource_id}/status/ with the item ID from the upload result or the Batch Queue's item results. The response contains datasource_id, generic_type, upload_status, status (processing, completed, or failed), the total, completed, processing, and failed counts, error for a failed scene, and frame_count. To process a failed scene again, send an empty POST to the same path ending in retry/. A queued retry returns 202 with task_id and status: "processing"; 200 with status: "completed" means a finished scene with the same content was reused and nothing had to run; 400 gives the reason a scene cannot be retried now.
Data Unit and Batch Queue endpoints
GET
/api/sdk/projects/{project_id}/data-units/
List loose 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 upload limits.
POST
/api/sdk/projects/{project_id}/upload-data/
Upload one multipart form file.
POST
/api/sdk/projects/{project_id}/medical-upload-sessions/{session_id}/finalize/
Finalize medical files sent through the form uploader.
GET
/api/sdk/projects/{project_id}/upload-sessions/
List Batch Queues.
GET
/api/sdk/projects/{project_id}/upload-sessions/{session_id}/
Read queue details and processing counts.
GET
/api/sdk/projects/{project_id}/upload-sessions/{session_id}/status/
Read processing counts.
GET
/api/sdk/projects/{project_id}/upload-sessions/{session_id}/data/
Inspect item results.
GET
/api/sdk/projects/{project_id}/pointcloud-scenes/{datasource_id}/status/
Read one LiDAR scene's processing status.
POST
/api/sdk/projects/{project_id}/pointcloud-scenes/{datasource_id}/retry/
Process a failed LiDAR scene again.
Data Unit filters are search, data_type, status, batch_queue, and kind. Paginated lists accept limit and offset; follow next until it is empty.
Attach governed workspace data
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
Replace DATASET_ID below with the dataset UUID and 3 with the published version you want to attach. The preview and commit must use the same 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.
Next steps
When processing succeeds, import existing labels or open the project to annotate the images. Use Assets and folders when you need reusable files or grouped views.
Related Unitlab capability guides: multimodal data curation