> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neptune.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Storage Buckets

> S3-compatible object storage for files and assets

Neptune provides S3-compatible storage buckets for storing files, images, and other assets. Under the hood, these are AWS S3 buckets that your application can access using standard AWS SDKs.

## Quick Start

Ask your AI assistant:

> "Add an S3 bucket called 'uploads' to my project"

Or add it directly to your `neptune.json`:

```json neptune.json theme={"dark"}
{
  "kind": "Service",
  "name": "my-app",
  "resources": [
    {
      "kind": "StorageBucket",
      "name": "uploads"
    }
  ]
}
```

Then ask your AI assistant to provision and deploy:

> "Provision my resources and deploy"

## How It Works

When you provision a storage bucket, Neptune:

1. Creates an S3 bucket with a **physical name** (e.g., `neptune-abc123-uploads`) for global uniqueness
2. Configures all necessary IAM permissions so your running service can access it
3. Returns the physical bucket name to your AI assistant

> [!NOTE]
>
> The physical bucket name is different from the logical name you define in `neptune.json`. For example, if you name your bucket `uploads`, the actual AWS bucket might be called `neptune-abc123-uploads`.

## Getting the Bucket Name

After provisioning, ask your AI assistant for the bucket name:

> "What's the bucket name for my uploads bucket?"

Or:

> "Show me the deployment status"

Your AI assistant will call `get_deployment_status` which returns the resource details including the physical `aws_id`:

```json theme={"dark"}
{
  "kind": "StorageBucket",
  "name": "uploads",
  "status": "Available",
  "aws_id": "neptune-abc123-uploads"  // This is your physical bucket name
}
```

> [!WARNING]
>
> Always use the **physical bucket name** (`aws_id`) in your code, not the logical name from your `neptune.json`.

## Using in Your Application

All permissions are pre-configured, so you can use `boto3` (or other AWS SDKs) out of the box without any credential configuration.

> [tab] Python
>
> ```python theme={"dark"}
> import boto3
>
> # Your AI assistant will provide this physical bucket name
> BUCKET_NAME = "neptune-abc123-uploads"
>
> s3 = boto3.client("s3")
>
> # Upload a file
> s3.put_object(
>     Bucket=BUCKET_NAME,
>     Key="images/photo.jpg",
>     Body=file_data
> )
>
> # Download a file
> response = s3.get_object(Bucket=BUCKET_NAME, Key="images/photo.jpg")
> data = response['Body'].read()
>
> # List files
> response = s3.list_objects_v2(Bucket=BUCKET_NAME)
> for obj in response.get('Contents', []):
>     print(obj['Key'])
> ```

> [tab] Node.js
>
> ```typescript theme={"dark"}
> import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';
>
> // Your AI assistant will provide this physical bucket name
> const BUCKET_NAME = 'neptune-abc123-uploads';
>
> // No credentials needed - permissions are pre-configured
> const s3 = new S3Client({ region: 'eu-west-2' });
>
> // Upload a file
> await s3.send(new PutObjectCommand({
>   Bucket: BUCKET_NAME,
>   Key: 'images/photo.jpg',
>   Body: fileBuffer,
>   ContentType: 'image/jpeg',
> }));
>
> // Download a file
> const response = await s3.send(new GetObjectCommand({
>   Bucket: BUCKET_NAME,
>   Key: 'images/photo.jpg',
> }));
> ```

> [tab] Rust
>
> ```rust theme={"dark"}
> use aws_sdk_s3::Client;
>
> // Your AI assistant will provide this physical bucket name
> let bucket_name = "neptune-abc123-uploads";
>
> // Load config from environment (credentials pre-configured)
> let config = aws_config::load_from_env().await;
> let client = Client::new(&config);
>
> // Upload
> client.put_object()
>     .bucket(bucket_name)
>     .key("images/photo.jpg")
>     .body(data.into())
>     .send()
>     .await?;
> ```

> [!TIP]
>
> Your AI assistant knows the physical bucket name after provisioning and can write the code for you with the correct bucket name already filled in.

## Configuration Options

```json theme={"dark"}
{
  "kind": "StorageBucket",
  "name": "uploads"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `kind` | string | Yes | Must be `"StorageBucket"` |
| `name` | string | Yes | Logical name for this bucket (Neptune generates a unique physical name) |

## Managing Files

You can ask your AI assistant to help manage bucket contents:

| Task | Example Request |
| - | - |
| List files | "List the files in my uploads bucket" |
| Get a file | "Show me the contents of config.json in my bucket" |
| Check status | "Is my storage bucket ready?" |

## Presigned URLs

For user uploads or temporary access, generate presigned URLs:

```python theme={"dark"}
import boto3
from botocore.config import Config

BUCKET_NAME = "neptune-abc123-uploads"

s3 = boto3.client('s3', config=Config(signature_version='s3v4'))

# Presigned download URL (1 hour)
download_url = s3.generate_presigned_url(
    'get_object',
    Params={'Bucket': BUCKET_NAME, 'Key': 'images/photo.jpg'},
    ExpiresIn=3600
)

# Presigned upload URL (5 minutes)
upload_url = s3.generate_presigned_url(
    'put_object',
    Params={'Bucket': BUCKET_NAME, 'Key': f'uploads/{user_id}/{filename}'},
    ExpiresIn=300
)
```

## Best Practices

> [accordion] Organize with prefixes
>
> Use prefixes (folders) to organize your files:
>
> ```
> your-bucket/
> ├── images/
> │   ├── avatars/
> │   └── posts/
> ├── documents/
> └── temp/
> ```

> [accordion] Set content types
>
> Always set the `ContentType` when uploading to ensure proper handling:
>
> ```python theme={"dark"}
> s3.put_object(
>     Bucket=BUCKET_NAME,
>     Key='document.pdf',
>     Body=buffer,
>     ContentType='application/pdf'
> )
> ```

> [accordion] Use presigned URLs for direct uploads
>
> For user uploads, generate presigned URLs to upload directly to S3 from the browser. This avoids passing large files through your server.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.