> 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/cloud-storage-api.md).

# Cloud storage API

{% hint style="info" %}
**Outcome:** List approved integrations, browse provider content, and import selected paths into a Project.
{% endhint %}

Cloud credentials are configured in Unitlab and are never returned by the API.

![Add Cloud Storage dialog](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FEceeKlJexxGEUrAINYfa%2Fcloud-storage-add.png?alt=media\&token=7f2c7aff-bb2a-476f-87cb-a8bd3a70540f)

*Create and validate the provider connection in Workspace Settings before using these endpoints.*

| Method | Endpoint                                                             | Purpose                        |
| ------ | -------------------------------------------------------------------- | ------------------------------ |
| GET    | `/api/sdk/cloud-storages/`                                           | List safe integration metadata |
| GET    | `/api/sdk/cloud-storages/{storage_id}/browse/`                       | Browse a provider prefix       |
| POST   | `/api/sdk/projects/{project_id}/cloud-storages/{storage_id}/import/` | Import selected paths          |

### Browse every page

```bash
curl --fail-with-body --silent --show-error \
  "$UNITLAB_API_URL/api/sdk/cloud-storages/STORAGE_ID/browse/?prefix=incoming%2F&page_size=500&project=PROJECT_ID" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY"
```

The response contains safe object metadata in `content` and a provider cursor in `next`. Repeat with that cursor as `next_token` until empty. Folder paths end in a slash.

### Import approved paths

```bash
curl --fail-with-body --silent --show-error \
  -X POST "$UNITLAB_API_URL/api/sdk/projects/PROJECT_ID/cloud-storages/STORAGE_ID/import/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"server_files":["incoming/study-001/"],"fps":2.0}'
```

Preserve `upload_session_id` and monitor the Project Batch Queue. Browse is a preflight; the queue is the authoritative ingestion result.

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