Skip to main content
Manage cloud storage configurations that connect your AWS S3 or Google Cloud Storage buckets to Avala. Storage configs allow datasets to read and write data directly from your own buckets.
Credentials (access keys, service account JSON) are validated on creation and never returned in API responses. Only bucket metadata and verification status are exposed.

​
List Storage Configs

GET /api/v1/storage-configs/
Returns all storage configurations for the authenticated user’s organization, ordered by most recent first.

​
Parameters

NameTypeRequiredDescription
cursorstringNoCursor for pagination (query parameter)
limitintegerNoNumber of results per page (query parameter)
organizationstringNoOrganization slug. Required if you belong to multiple organizations.

​
Request

curl "https://api.avala.ai/api/v1/storage-configs/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

{
  "next": null,
  "previous": null,
  "results": [
    {
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Production S3 Bucket",
      "provider": "aws_s3",
      "s3_bucket_name": "acme-datasets",
      "s3_bucket_region": "us-west-2",
      "s3_bucket_prefix": "annotations/",
      "s3_is_accelerated": false,
      "gc_storage_bucket_name": null,
      "gc_storage_prefix": null,
      "is_verified": true,
      "last_verified_at": "2025-01-15T09:30:00Z",
      "created_at": "2025-01-15T09:30:00Z",
      "updated_at": "2025-01-15T09:30:00Z"
    }
  ]
}

​
Fields

FieldTypeDescription
uidstring (UUID)Unique identifier for the storage config
namestringDisplay name of the storage configuration
providerstringStorage provider: aws_s3 or gc_storage
s3_bucket_namestring | nullS3 bucket name (AWS S3 only)
s3_bucket_regionstring | nullAWS region of the bucket (AWS S3 only)
s3_bucket_prefixstring | nullKey prefix within the bucket (AWS S3 only)
s3_is_acceleratedbooleanWhether S3 Transfer Acceleration is enabled (AWS S3 only)
gc_storage_bucket_namestring | nullGCS bucket name (Google Cloud Storage only)
gc_storage_prefixstring | nullObject prefix within the bucket (Google Cloud Storage only)
is_verifiedbooleanWhether the last connection test succeeded
last_verified_atstring (datetime) | nullWhen the connection was last tested
created_atstring (datetime)ISO 8601 timestamp of creation
updated_atstring (datetime)ISO 8601 timestamp of the last update

​
Create Storage Config

POST /api/v1/storage-configs/
Creates a new storage configuration. Cloud credentials are validated during creation — the request will fail if Avala cannot connect to the bucket. Credentials are stored securely and are never returned in API responses.

​
Parameters (AWS S3)

NameTypeRequiredDescription
organizationstringNoOrganization slug (query parameter). Required if you belong to multiple organizations.
namestringYesDisplay name for this storage config
providerstringYesMust be aws_s3
s3_bucket_namestringYesS3 bucket name
s3_bucket_regionstringYesAWS region (e.g., us-west-2)
s3_bucket_prefixstringNoKey prefix for objects in the bucket
s3_access_key_idstringYesAWS access key ID (write-only)
s3_secret_access_keystringYesAWS secret access key (write-only)
s3_is_acceleratedbooleanNoEnable S3 Transfer Acceleration (default: false)
s3_cloudfront_domainstringNoCloudFront distribution domain
s3_cloudfront_public_key_idstringNoCloudFront public key ID for signed URLs

​
Parameters (Google Cloud Storage)

NameTypeRequiredDescription
organizationstringNoOrganization slug (query parameter). Required if you belong to multiple organizations.
namestringYesDisplay name for this storage config
providerstringYesMust be gc_storage
gc_storage_bucket_namestringYesGCS bucket name
gc_storage_prefixstringNoObject prefix within the bucket
gc_storage_auth_json_contentstringYesService account JSON key content (write-only)

​
Request (AWS S3)

curl -X POST "https://api.avala.ai/api/v1/storage-configs/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production S3 Bucket",
    "provider": "aws_s3",
    "s3_bucket_name": "acme-datasets",
    "s3_bucket_region": "us-west-2",
    "s3_bucket_prefix": "annotations/",
    "s3_access_key_id": "YOUR_AWS_ACCESS_KEY_ID",
    "s3_secret_access_key": "YOUR_AWS_SECRET_ACCESS_KEY"
  }'

​
Response

{
  "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Production S3 Bucket",
  "provider": "aws_s3",
  "s3_bucket_name": "acme-datasets",
  "s3_bucket_region": "us-west-2",
  "s3_bucket_prefix": "annotations/",
  "s3_is_accelerated": false,
  "gc_storage_bucket_name": null,
  "gc_storage_prefix": null,
  "is_verified": true,
  "last_verified_at": "2025-01-15T09:30:00Z",
  "created_at": "2025-01-15T09:30:00Z",
  "updated_at": "2025-01-15T09:30:00Z"
}
Credentials (s3_access_key_id, s3_secret_access_key, gc_storage_auth_json_content) are write-only. They are never included in API responses.

​
Test Connection

POST /api/v1/storage-configs/{uid}/test/
Re-runs credential validation and connectivity checks on an existing storage configuration. Updates the is_verified and last_verified_at fields.

​
Parameters

NameTypeRequiredDescription
uidstring (UUID)YesStorage config UID (path parameter)

​
Request

curl -X POST "https://api.avala.ai/api/v1/storage-configs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/test/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response (Success)

{
  "verified": true
}

​
Response (Failure)

{
  "verified": false,
  "errors": {
    "s3_bucket_name": ["Bucket not found or access denied."]
  }
}

​
Get Setup Info

GET /api/v1/storage-configs/setup-info/
Returns the Avala AWS Account ID and your organization’s external ID, needed to configure IAM trust policies for cross-account S3 access.

​
Parameters

NameTypeRequiredDescription
organizationstringNoOrganization slug. Required if you belong to multiple organizations.

​
Request

curl "https://api.avala.ai/api/v1/storage-configs/setup-info/?organization=my-org" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

{
  "avala_aws_account_id": "014424401899",
  "external_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

​
Delete Storage Config

DELETE /api/v1/storage-configs/{uid}/
Permanently deletes a storage configuration. Datasets that reference this configuration will no longer be able to access the bucket.

​
Parameters

NameTypeRequiredDescription
uidstring (UUID)YesStorage config UID (path parameter)

​
Request

curl -X DELETE "https://api.avala.ai/api/v1/storage-configs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

Returns 204 No Content on success.

​
Supported Providers

ProviderValueDescription
AWS S3aws_s3Amazon Simple Storage Service
Google Cloud Storagegc_storageGoogle Cloud Storage

​
Error Responses

​
Validation Error (400)

{
  "s3_bucket_name": ["Bucket not found or access denied."],
  "provider": ["Unsupported provider: azure_blob"]
}
Returned when credentials are invalid, the bucket is unreachable, or the provider is not supported.

​
Unauthorized (401)

{
  "detail": "Invalid API key."
}
Returned when the X-Avala-Api-Key header is missing or contains an invalid key.

​
Permission Denied (403)

{
  "detail": "You do not have permission to perform this action."
}
Returned when the authenticated user does not have access to the requested storage config.

​
Not Found (404)

{
  "detail": "Not found."
}
Returned when the specified storage config UID does not exist.