Object Storage API

Manage S3-compatible object storage buckets and access keys programmatically through the DanubeData API.

Endpoints Overview

Storage Buckets

Method	Endpoint	Description	Scope Required
GET	`/api/v1/storage/buckets`	List all buckets	`storage:read`
POST	`/api/v1/storage/buckets`	Create a new bucket	`storage:write`
GET	`/api/v1/storage/buckets/{id}`	Get bucket details	`storage:read`
PUT	`/api/v1/storage/buckets/{id}`	Update bucket settings	`storage:write`
DELETE	`/api/v1/storage/buckets/{id}`	Delete a bucket	`storage:delete`
GET	`/api/v1/storage/buckets/{id}/metrics`	Get bucket metrics	`storage:read`

Storage Access Keys

Method	Endpoint	Description	Scope Required
GET	`/api/v1/storage/access-keys`	List all access keys	`storage:read`
POST	`/api/v1/storage/access-keys`	Create a new access key	`storage:write`
GET	`/api/v1/storage/access-keys/{id}`	Get access key details	`storage:read`
DELETE	`/api/v1/storage/access-keys/{id}`	Revoke an access key	`storage:delete`

Storage Buckets

List All Buckets

Bash

curl -X GET 'https://danubedata.ro/api/v1/storage/buckets' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Response:

JSON

{
  "data": [
    {
      "id": "9c8b7a6e-5d4c-3b2a-1098-76543210fedc",
      "name": "my-bucket",
      "display_name": "My Application Bucket",
      "status": "active",
      "status_label": "Active",
      "region": "fsn1",
      "endpoint_url": "https://s3.danubedata.ro",
      "public_access": false,
      "versioning_enabled": false,
      "encryption_enabled": true,
      "size_bytes": 1073741824,
      "size_human": "1.00 GB",
      "object_count": 150,
      "monthly_cost_cents": 500,
      "monthly_cost_dollars": 5.00,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 15,
    "total": 1
  }
}

Create a Bucket

Bash

curl -X POST 'https://danubedata.ro/api/v1/storage/buckets' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "name": "my-new-bucket",
    "display_name": "My New Bucket",
    "region": "fsn1",
    "versioning_enabled": false,
    "public_access": false,
    "encryption_enabled": true,
    "tags": {
      "environment": "production",
      "project": "webapp"
    }
  }'

Parameters:

Parameter	Type	Required	Description
`name`	string	Yes	Bucket name (3-63 chars, lowercase, alphanumeric and hyphens)
`display_name`	string	No	Human-readable display name
`region`	string	Yes	Region code (e.g., `fsn1`)
`versioning_enabled`	boolean	No	Enable object versioning (default: false)
`public_access`	boolean	No	Allow public read access (default: false)
`encryption_enabled`	boolean	No	Enable server-side encryption (default: true)
`encryption_type`	string	No	Encryption type: `sse-s3` or `sse-kms`
`cors_configuration`	array	No	CORS rules for the bucket
`lifecycle_rules`	array	No	Object lifecycle rules
`tags`	object	No	Key-value tags for the bucket

Response (201 Created):

JSON

{
  "message": "Storage bucket created successfully",
  "bucket": {
    "id": "9c8b7a6e-5d4c-3b2a-1098-76543210fedc",
    "name": "my-new-bucket",
    "status": "pending",
    "status_label": "Pending"
  }
}

Get Bucket Details

Bash

curl -X GET 'https://danubedata.ro/api/v1/storage/buckets/{bucket_id}' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Response:

JSON

{
  "bucket": {
    "id": "9c8b7a6e-5d4c-3b2a-1098-76543210fedc",
    "name": "my-bucket",
    "display_name": "My Application Bucket",
    "status": "active",
    "region": "fsn1",
    "endpoint_url": "https://s3.danubedata.ro",
    "public_url": null,
    "public_access": false,
    "versioning_enabled": false,
    "encryption_enabled": true,
    "encryption_type": "sse-s3",
    "size_bytes": 1073741824,
    "object_count": 150,
    "tags": {
      "environment": "production"
    },
    "monthly_cost_cents": 500,
    "monthly_cost_dollars": 5.00,
    "can_be_modified": true,
    "can_be_destroyed": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "endpoint": "https://s3.danubedata.ro"
}

Update Bucket Settings

Bash

curl -X PUT 'https://danubedata.ro/api/v1/storage/buckets/{bucket_id}' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "display_name": "Updated Bucket Name",
    "versioning_enabled": true,
    "public_access": false,
    "tags": {
      "environment": "staging"
    }
  }'

Response:

JSON

{
  "message": "Bucket settings updated successfully",
  "bucket": {
    "id": "9c8b7a6e-5d4c-3b2a-1098-76543210fedc",
    "name": "my-bucket",
    "display_name": "Updated Bucket Name",
    "versioning_enabled": true
  }
}

Delete a Bucket

Bash

curl -X DELETE 'https://danubedata.ro/api/v1/storage/buckets/{bucket_id}' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Response:

JSON

{
  "message": "Bucket deletion initiated",
  "status": "destroying"
}

Note: Bucket deletion is asynchronous. The bucket and all its objects will be permanently deleted.

Get Bucket Metrics

Bash

curl -X GET 'https://danubedata.ro/api/v1/storage/buckets/{bucket_id}/metrics' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Response:

JSON

{
  "size_bytes": 1073741824,
  "size_human": "1.00 GB",
  "object_count": 150,
  "monthly_cost_cents": 500,
  "monthly_cost_dollars": 5.00,
  "last_sync_at": "2024-01-15T12:00:00Z"
}

Storage Access Keys

Access keys provide S3-compatible credentials for accessing your storage buckets programmatically.

List All Access Keys

Bash

curl -X GET 'https://danubedata.ro/api/v1/storage/access-keys' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Response:

JSON

{
  "data": [
    {
      "id": "abc12345-6789-0abc-def1-234567890abc",
      "name": "Production API Key",
      "access_key_id": "DDAK1234567890EXAMPLE",
      "access_key_id_masked": "DDAK****XAMPLE",
      "status": "active",
      "status_label": "Active",
      "permissions": null,
      "expires_at": null,
      "last_used_at": "2024-01-15T11:30:00Z",
      "is_expired": false,
      "created_at": "2024-01-10T09:00:00Z",
      "updated_at": "2024-01-15T11:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 15,
    "total": 1
  }
}

Create an Access Key

Bash

curl -X POST 'https://danubedata.ro/api/v1/storage/access-keys' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "name": "My Application Key",
    "expires_at": "2025-01-15T00:00:00Z"
  }'

Parameters:

Parameter	Type	Required	Description
`name`	string	Yes	A descriptive name for the access key
`expires_at`	datetime	No	Expiration date (ISO 8601 format)

Response (201 Created):

JSON

{
  "id": "abc12345-6789-0abc-def1-234567890abc",
  "name": "My Application Key",
  "access_key_id": "DDAK1234567890EXAMPLE",
  "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "expires_at": "2025-01-15T00:00:00Z",
  "message": "Access key created. Make sure to save the secret key - it will not be shown again."
}

Important: The secret_access_key is only returned once during creation. Store it securely as it cannot be retrieved later.

Get Access Key Details

Bash

curl -X GET 'https://danubedata.ro/api/v1/storage/access-keys/{access_key_id}' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Response:

JSON

{
  "access_key": {
    "id": "abc12345-6789-0abc-def1-234567890abc",
    "name": "My Application Key",
    "access_key_id": "DDAK1234567890EXAMPLE",
    "access_key_id_masked": "DDAK****XAMPLE",
    "status": "active",
    "status_label": "Active",
    "expires_at": "2025-01-15T00:00:00Z",
    "last_used_at": "2024-01-15T11:30:00Z",
    "is_expired": false,
    "created_at": "2024-01-10T09:00:00Z"
  }
}

Note: The secret_access_key is never returned after initial creation.

Revoke an Access Key

Bash

curl -X DELETE 'https://danubedata.ro/api/v1/storage/access-keys/{access_key_id}' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Response:

JSON

{
  "message": "Access key has been revoked"
}

Warning: Revoking an access key immediately invalidates it. Any applications using this key will lose access.

Using Access Keys with S3 Clients

Once you have created an access key, you can use it with any S3-compatible client.

AWS CLI

Bash

aws configure --profile danubedata

# Enter your credentials when prompted:
# AWS Access Key ID: DDAK1234567890EXAMPLE
# AWS Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# Default region name: fsn1

# Use with custom endpoint
aws s3 ls s3://my-bucket \
  --endpoint-url https://s3.danubedata.ro \
  --profile danubedata

Python (boto3)

Python

import boto3

s3 = boto3.client(
    's3',
    endpoint_url='https://s3.danubedata.ro',
    aws_access_key_id='DDAK1234567890EXAMPLE',
    aws_secret_access_key='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
    region_name='fsn1'
)

# List objects in a bucket
response = s3.list_objects_v2(Bucket='my-bucket')
for obj in response.get('Contents', []):
    print(obj['Key'])

JavaScript (AWS SDK v3)

JavaScript

import { S3Client, ListObjectsV2Command } from '@aws-sdk/client-s3';

const s3 = new S3Client({
  endpoint: 'https://s3.danubedata.ro',
  region: 'fsn1',
  credentials: {
    accessKeyId: 'DDAK1234567890EXAMPLE',
    secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
  },
  forcePathStyle: true
});

const command = new ListObjectsV2Command({ Bucket: 'my-bucket' });
const response = await s3.send(command);
console.log(response.Contents);

Error Responses

422 Unprocessable Entity

JSON

{
  "error": "You have reached the maximum number of buckets (10). Please delete a bucket to create a new one."
}

JSON

{
  "error": "Bucket cannot be modified in its current state",
  "status": "creating"
}

404 Not Found

JSON

{
  "error": "Bucket not found"
}

403 Forbidden

Returned when your API token lacks the required storage:* scope.

JSON

{
  "message": "Insufficient permissions"
}

Rate Limits

Storage API endpoints have specific rate limits:

Endpoint	Limit
Create bucket	20/min, 100/hour, 1000/day
Create access key	10/min, 50/hour, 500/day
Get metrics	2x standard limits
Other endpoints	Standard tier limits

See Rate Limits for more details.