# Storages

Cloud storage configuration

## Get Storages

> Retrieves all storage configurations for your organization

```json
{"openapi":"3.0.3","info":{"title":"Ango Hub API v2","version":"2.0.0"},"tags":[{"name":"Storages","description":"Cloud storage configuration"}],"servers":[{"url":"https://imeritapi.ango.ai/v2","description":"EU Production Server"},{"url":"https://us-api.ango.ai/v2","description":"US Production Server"},{"url":"https://in-api.ango.ai/v2","description":"India Production Server"},{"url":"https://testapi.ango.ai/v2","description":"Test Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication. Format - apikey YOUR_API_KEY"}},"parameters":{"PageParam":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number (1-indexed)"},"LimitParam":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"description":"Items per page (max 100)"}},"schemas":{"StorageListResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"storages":{"type":"array","items":{"$ref":"#/components/schemas/Storage"}}}}}},"Storage":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["aws","gcs","azure"]},"bucket":{"type":"string"},"region":{"type":"string"},"organization":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}},"paths":{"/storages":{"get":{"tags":["Storages"],"summary":"Get Storages","description":"Retrieves all storage configurations for your organization","operationId":"getStorages","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Storages retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageListResponse"}}}}}}}}}
```

## Create Storage

> Creates a new cloud storage configuration

```json
{"openapi":"3.0.3","info":{"title":"Ango Hub API v2","version":"2.0.0"},"tags":[{"name":"Storages","description":"Cloud storage configuration"}],"servers":[{"url":"https://imeritapi.ango.ai/v2","description":"EU Production Server"},{"url":"https://us-api.ango.ai/v2","description":"US Production Server"},{"url":"https://in-api.ango.ai/v2","description":"India Production Server"},{"url":"https://testapi.ango.ai/v2","description":"Test Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication. Format - apikey YOUR_API_KEY"}},"schemas":{"StorageCreateRequest":{"type":"object","required":["name","type","bucket","credentials"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["aws","gcs","azure"]},"bucket":{"type":"string"},"region":{"type":"string"},"credentials":{"type":"object","description":"Storage provider credentials"},"privateKey":{"type":"string","description":"Private key (for GCS)"}}},"StorageResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"storage":{"$ref":"#/components/schemas/Storage"}}}}},"Storage":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["aws","gcs","azure"]},"bucket":{"type":"string"},"region":{"type":"string"},"organization":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["fail","error"]},"message":{"type":"string"}}}},"responses":{"BadRequestError":{"description":"Bad request - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/storages":{"post":{"tags":["Storages"],"summary":"Create Storage","description":"Creates a new cloud storage configuration","operationId":"createStorage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageCreateRequest"}}}},"responses":{"200":{"description":"Storage created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"}}}}}}
```

## Delete Storage

> Deletes a storage configuration

```json
{"openapi":"3.0.3","info":{"title":"Ango Hub API v2","version":"2.0.0"},"tags":[{"name":"Storages","description":"Cloud storage configuration"}],"servers":[{"url":"https://imeritapi.ango.ai/v2","description":"EU Production Server"},{"url":"https://us-api.ango.ai/v2","description":"US Production Server"},{"url":"https://in-api.ango.ai/v2","description":"India Production Server"},{"url":"https://testapi.ango.ai/v2","description":"Test Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication. Format - apikey YOUR_API_KEY"}},"schemas":{"StorageResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"storage":{"$ref":"#/components/schemas/Storage"}}}}},"Storage":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["aws","gcs","azure"]},"bucket":{"type":"string"},"region":{"type":"string"},"organization":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}},"paths":{"/storages/{storageId}":{"delete":{"tags":["Storages"],"summary":"Delete Storage","description":"Deletes a storage configuration","operationId":"deleteStorage","parameters":[{"name":"storageId","in":"path","required":true,"schema":{"type":"string"},"description":"Storage ID"}],"responses":{"200":{"description":"Storage deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageResponse"}}}}}}}}}
```

## List Storage Files

> Lists files recursively in a cloud storage bucket. This endpoint allows you to browse and retrieve file listings from your configured storage integrations (AWS S3, Google Cloud Storage, Azure Blob Storage, or Custom S3-compatible storage).\
> \
> \*\*Features:\*\*\
> \- Recursive directory listing\
> \- Optional signed URL generation for direct file access\
> \- Automatic retry mechanism for S3 rate limit errors\
> \- Support for path-based filtering\
> \
> \*\*Use Cases:\*\*\
> \- Browse storage bucket contents before importing\
> \- Generate signed URLs for batch asset uploads\
> \- Validate storage configuration and access\
> \- List available datasets for annotation projects<br>

```json
{"openapi":"3.0.3","info":{"title":"Ango Hub API v2","version":"2.0.0"},"tags":[{"name":"Storages","description":"Cloud storage configuration"}],"servers":[{"url":"https://imeritapi.ango.ai/v2","description":"EU Production Server"},{"url":"https://us-api.ango.ai/v2","description":"US Production Server"},{"url":"https://in-api.ango.ai/v2","description":"India Production Server"},{"url":"https://testapi.ango.ai/v2","description":"Test Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication. Format - apikey YOUR_API_KEY"}},"schemas":{"StorageFilesResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/StorageFile"}}}}}},"StorageFile":{"type":"object","properties":{"Key":{"type":"string","description":"File path/key in the storage bucket"},"Size":{"type":"integer","description":"File size in bytes"},"LastModified":{"type":"string","format":"date-time","description":"Last modification timestamp"},"ETag":{"type":"string","description":"Entity tag (checksum) for the file"},"SignedUrl":{"type":"string","description":"Pre-signed URL for direct file access (only present when getSignedUrls=true)"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["fail","error"]},"message":{"type":"string"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ForbiddenError":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/storages/{storageId}/files":{"get":{"tags":["Storages"],"summary":"List Storage Files","description":"Lists files recursively in a cloud storage bucket. This endpoint allows you to browse and retrieve file listings from your configured storage integrations (AWS S3, Google Cloud Storage, Azure Blob Storage, or Custom S3-compatible storage).\n\n**Features:**\n- Recursive directory listing\n- Optional signed URL generation for direct file access\n- Automatic retry mechanism for S3 rate limit errors\n- Support for path-based filtering\n\n**Use Cases:**\n- Browse storage bucket contents before importing\n- Generate signed URLs for batch asset uploads\n- Validate storage configuration and access\n- List available datasets for annotation projects\n","operationId":"listStorageFiles","parameters":[{"name":"storageId","in":"path","required":true,"schema":{"type":"string"},"description":"Storage configuration ID"},{"name":"bucketName","in":"query","required":true,"schema":{"type":"string"},"description":"Name of the bucket/container to list files from"},{"name":"path","in":"query","required":false,"schema":{"type":"string","default":""},"description":"Directory path to list files from. Defaults to root directory if not specified."},{"name":"getSignedUrls","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"Whether to generate signed URLs for each file. Signed URLs provide temporary authenticated access to private files.\n- `true`: Returns signed URLs (24-hour expiry)\n- `false`: Returns file metadata only (default)\n"},{"name":"retryOnSlowDown","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"true"},"description":"Enable automatic retry mechanism for S3 SlowDown errors (rate limiting). When enabled, the API will automatically retry with exponential backoff.\n- `true`: Retry on rate limit errors (default)\n- `false`: Fail immediately on rate limit errors\n"}],"responses":{"200":{"description":"Files retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageFilesResponse"}}}},"400":{"description":"Bad Request - Missing required parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Storage not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```