# AWS S3 Integration via LowCodeAPI

**Last Updated**: February 11, 2026

## Overview
Amazon Simple Storage Service (S3) is an object storage service that offers industry-leading scalability, data availability, security, and performance. Through LowCodeAPI, you can generate signed URLs for secure file uploads and downloads without exposing your AWS credentials to clients.

**Key Features**:
- Generate signed URLs for secure file uploads (PUT)
- Generate signed URLs for secure file downloads (GET)
- Support for various ACL (Access Control List) options
- Configurable URL expiration times
- No need to manage AWS credentials in your application

## Base Endpoint
https://api.lowcodeapi.com/awss3

**Important**: Always include the provider name in the URL path after `api.lowcodeapi.com/`

## Authentication
AWS S3 uses AWS Access Key authentication with the following credentials:

### Setup Instructions
1. Create an AWS account if you don't have one
2. Navigate to the IAM Console
3. Create a user with S3 permissions
4. Generate Access Key ID and Secret Access Key
5. Note your AWS region (e.g., us-east-1, us-west-2)
6. Create or identify your S3 bucket name
7. Add credentials to LowCodeAPI for the `awss3` provider

### Get Credentials
- **AWS Access Keys**: [AWS Documentation](https://aws.amazon.com/)
- **AWS Console**: https://console.aws.amazon.com/

**Required Credentials**:
- `accessKeyId` - Your AWS Access Key ID
- `secretAccessKey` - Your AWS Secret Access Key
- `region` - Your AWS region (e.g., us-east-1, us-east-2)

### S3 Bucket Requirements
- You must have an existing S3 bucket
- The bucket must be in the same region as your AWS credentials
- Your AWS credentials must have appropriate permissions (PutObject, GetObject, etc.)

## URL Format (Important)

LowCodeAPI supports **two URL formats** for endpoints with path parameters. Always try the **New Format first**, and only fall back to the **Old Format** if it doesn't work.

### New Format (Priority) - Dynamic Path Parameters
Path parameters stay in the URL path - do NOT convert to query parameters.

Pattern: `https://api.lowcodeapi.com/awss3/{path_with_params}?api_token={api_token}`

**Example**:
```bash
# New Format - Query parameters only (no path parameters for S3 endpoints)
https://api.lowcodeapi.com/awss3/signed-url?bucket=my-bucket&key_name=myfile.pdf&api_token=YOUR_API_TOKEN
```

### Old Format (Fallback) - Sanitized Path + Query Parameters
For S3 endpoints, the format is similar as they primarily use query parameters.

Pattern: `https://api.lowcodeapi.com/awss3/{sanitized_path}?{params}&api_token={api_token}`

**Example**:
```bash
# Old Format
https://api.lowcodeapi.com/awss3/signed-url?bucket=my-bucket&key_name=myfile.pdf&api_token=YOUR_API_TOKEN
```

### Decision Flow for AI Agents
1. Always use New Format first
2. If you get a 404 or error, try Old Format
3. Log which format worked for future requests to AWS S3

## API Categories
- **Signed URL** - Generate signed URLs for upload and download operations

## Common Endpoints

### Generate Signed URL
Generate an AWS S3 signed URL for uploading or downloading a file. This endpoint supports both operations via the `type` parameter.

**Method**: GET | **LowCodeAPI Path**: `/awss3/signed-url`

**New Format URL**:
```
https://api.lowcodeapi.com/awss3/signed-url?bucket={bucket}&key_name={key_name}&api_token={api_token}
```

**Old Format URL**:
```
https://api.lowcodeapi.com/awss3/signed-url?bucket={bucket}&key_name={key_name}&api_token={api_token}
```

**Path Parameters**: None

**Query Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| bucket | string | Yes | User's AWS S3 bucket name |
| key_name | string | Yes | File name to be signed (the S3 object key) |
| type | enum | No | Request type: `upload` or `get` (default) |
| acl | enum | No | ACL of the file object, only applicable for upload. Default: `private` |
| expires_in | number | No | Expire the signed URL after this duration (in seconds). Default: 300 seconds |

**ACL Options** (for uploads only):
- `private` - Only the bucket owner can access
- `public-read` - Anyone can read
- `public-read-write` - Anyone can read and write
- `authenticated-read` - Authenticated AWS users can read
- `aws-exec-read` - EC2 instances can read
- `bucket-owner-read` - Bucket owner can read
- `bucket-owner-full-control` - Bucket owner has full control

**Example Request** - Generate Upload URL (New Format):
```bash
curl -X GET "https://api.lowcodeapi.com/awss3/signed-url?bucket=my-audio-files&key_name=recordings/interview.mp3&type=upload&acl=private&expires_in=600&api_token=YOUR_API_TOKEN"
```

**Example Request** - Generate Download URL (New Format):
```bash
curl -X GET "https://api.lowcodeapi.com/awss3/signed-url?bucket=my-audio-files&key_name=recordings/interview.mp3&type=get&expires_in=3600&api_token=YOUR_API_TOKEN"
```

**Example Response**:
```json
{
  "data": {
    "signedUrl": "https://my-bucket.s3.us-east-1.amazonaws.com/recordings/interview.mp3?AWSAccessKeyId=...&Expires=...&Signature=...",
    "expiresAt": "2026-02-11T07:00:00Z",
    "bucket": "my-audio-files",
    "key": "recordings/interview.mp3"
  }
}
```

---

### Generate Signed URL for Fetch
Generate an AWS S3 signed URL specifically for downloading/fetching a file from an S3 bucket.

**Method**: GET | **LowCodeAPI Path**: `/awss3/signed-url/for-fetch`

**New Format URL**:
```
https://api.lowcodeapi.com/awss3/signed-url/for-fetch?bucket={bucket}&key_name={key_name}&expires_in={expires_in}&api_token={api_token}
```

**Old Format URL**:
```
https://api.lowcodeapi.com/awss3/signed-url/for-fetch?bucket={bucket}&key_name={key_name}&expires_in={expires_in}&api_token={api_token}
```

**Path Parameters**: None

**Query Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| bucket | string | Yes | User's AWS S3 bucket name |
| key_name | string | Yes | File name to be signed (the S3 object key) |
| expires_in | number | Yes | Expire the signed URL after this duration (in seconds). Default: 300 seconds |

**Example Request** (New Format):
```bash
curl -X GET "https://api.lowcodeapi.com/awss3/signed-url/for-fetch?bucket=my-images&key_name=photos/profile.png&expires_in=1800&api_token=YOUR_API_TOKEN"
```

**Example Response**:
```json
{
  "data": {
    "signedUrl": "https://my-images.s3.us-east-1.amazonaws.com/photos/profile.png?AWSAccessKeyId=...&Expires=...&Signature=...",
    "expiresAt": "2026-02-11T06:30:00Z"
  }
}
```

---

### Generate Signed URL for Upload
Generate an AWS S3 signed URL specifically for uploading a file to an S3 bucket.

**Method**: GET | **LowCodeAPI Path**: `/awss3/signed-url/for-upload`

**New Format URL**:
```
https://api.lowcodeapi.com/awss3/signed-url/for-upload?bucket={bucket}&key_name={key_name}&api_token={api_token}
```

**Old Format URL**:
```
https://api.lowcodeapi.com/awss3/signed-url/for-upload?bucket={bucket}&key_name={key_name}&api_token={api_token}
```

**Path Parameters**: None

**Query Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| bucket | string | Yes | User's AWS S3 bucket name |
| key_name | string | Yes | File name to be signed (the S3 object key) |
| acl | enum | No | ACL of the file object, only applicable for upload. Default: `private` |
| expires_in | number | No | Expire the signed URL after this duration (in seconds). Default: 300 seconds |

**Example Request** (New Format):
```bash
curl -X GET "https://api.lowcodeapi.com/awss3/signed-url/for-upload?bucket=my-documents&key_name/pdfs/report.pdf&acl=private&expires_in=600&api_token=YOUR_API_TOKEN"
```

**Example Response**:
```json
{
  "data": {
    "signedUrl": "https://my-documents.s3.us-east-1.amazonaws.com/pdfs/report.pdf?AWSAccessKeyId=...&Expires=...&Signature=...",
    "expiresAt": "2026-02-11T06:10:00Z"
  }
}
```

## Complete Endpoint Reference

| Method | Category | New Format Path | Description |
|--------|----------|-----------------|-------------|
| GET | Signed URL | `/awss3/signed-url` | Generate signed URL (upload or get) |
| GET | Signed URL | `/awss3/signed-url/for-fetch` | Generate signed URL for fetching/downloading |
| GET | Signed URL | `/awss3/signed-url/for-upload` | Generate signed URL for uploading |

## API Definition Endpoints

To discover all available endpoints programmatically:

```bash
# New Format - OpenAPI spec with dynamic path parameters
curl -X GET "https://backend.lowcodeapi.com/awss3/openapi"

# Old Format - API definition with sanitized paths
curl -X GET "https://backend.lowcodeapi.com/awss3/definition"
```

## Usage Examples

### Example 1: Upload a File to S3

```bash
# Step 1: Generate a signed URL for upload
# No ID needed - just provide bucket and key name
curl -X GET "https://api.lowcodeapi.com/awss3/signed-url/for-upload?bucket=my-uploads&key_name=videos/interview.mp4&acl=private&expires_in=600&api_token=YOUR_API_TOKEN"

# Response: { "data": { "signedUrl": "https://my-uploads.s3.us-east-1.amazonaws.com/videos/interview.mp4?..." } }
# Note: Use the returned signedUrl to upload the file

# Step 2: Use the signed URL to upload the file
curl -X PUT "https://my-uploads.s3.us-east-1.amazonaws.com/videos/interview.mp4?AWSAccessKeyId=...&Expires=...&Signature=..." \
  -H "Content-Type: video/mp4" \
  --data-binary @local-interview.mp4
```

### Example 2: Download a File from S3

```bash
# Step 1: Generate a signed URL for download/fetch
# No ID needed - just provide bucket and key name
curl -X GET "https://api.lowcodeapi.com/awss3/signed-url/for-fetch?bucket=my-files&key_name/documents/contract.pdf&expires_in=3600&api_token=YOUR_API_TOKEN"

# Response: { "data": { "signedUrl": "https://my-files.s3.us-east-1.amazonaws.com/documents/contract.pdf?..." } }
# Note: Use the returned signedUrl to download the file

# Step 2: Use the signed URL to download the file
curl -O "https://my-files.s3.us-east-1.amazonaws.com/documents/contract.pdf?AWSAccessKeyId=...&Expires=...&Signature=..."
```

### Example 3: Using the Generic Signed URL Endpoint

```bash
# Upload using generic endpoint with type parameter
curl -X GET "https://api.lowcodeapi.com/awss3/signed-url?bucket=my-bucket&key_name=test.txt&type=upload&expires_in=300&api_token=YOUR_API_TOKEN"
# Then use the returned signedUrl for PUT upload

# Download using generic endpoint with type parameter
curl -X GET "https://api.lowcodeapi.com/awss3/signed-url?bucket=my-bucket&key_name=test.txt&type=get&expires_in=300&api_token=YOUR_API_TOKEN"
# Then use the returned signedUrl for GET download
```

### Example 4: Public File Upload

```bash
# Generate a signed URL for uploading a file that will be publicly accessible
# No ID needed
curl -X GET "https://api.lowcodeapi.com/awss3/signed-url/for-upload?bucket=public-assets&key_name/images/logo.png&acl=public-read&expires_in=600&api_token=YOUR_API_TOKEN"

# Response: { "data": { "signedUrl": "https://public-assets.s3.us-east-1.amazonaws.com/images/logo.png?..." } }

# Upload the file
curl -X PUT "https://public-assets.s3.us-east-1.amazonaws.com/images/logo.png?AWSAccessKeyId=...&Expires=...&Signature=..." \
  -H "Content-Type: image/png" \
  --data-binary @logo.png

# After upload, the file will be publicly accessible at:
# https://public-assets.s3.us-east-1.amazonaws.com/images/logo.png
```

### Example 5: Organized Uploads with Folder Paths

```bash
# Generate signed URLs for files in organized folder structures
# No ID needed for any of these - just unique key names

# File 1: Documents
curl -X GET "https://api.lowcodeapi.com/awss3/signed-url/for-upload?bucket=company-docs&key_name=2026/q1/quarterly-report.pdf&expires_in=600&api_token=YOUR_API_TOKEN"

# File 2: Images
curl -X GET "https://api.lowcodeapi.com/awss3/signed-url/for-upload?bucket=company-assets&key_name=employees/avatars/john-doe.jpg&expires_in=600&api_token=YOUR_API_TOKEN"

# File 3: Audio
curl -X GET "https://api.lowcodeapi.com/awss3/signed-url/for-upload?bucket=podcasts&key_name/episodes/ep-001.mp3&expires_in=600&api_token=YOUR_API_TOKEN"
```

## Important Notes

### Security Considerations
1. **Signed URLs expire**: Always set an appropriate `expires_in` value based on your use case
2. **ACL selection**: Use `private` for sensitive files, `public-read` for public assets
3. **HTTPS only**: Always use HTTPS when transferring files
4. **Bucket permissions**: Ensure your AWS credentials have the right S3 permissions

### S3 Key Names (key_name)
- The `key_name` is the full path and filename in S3 (e.g., `folder/subfolder/file.pdf`)
- Use forward slashes (/) for folder separation
- S3 doesn't actually have folders, but you can use key prefixes for organization
- Key names must be unique within a bucket

### Common Use Cases
- **File uploads from browsers**: Generate upload URLs on your server, then use in frontend
- **Direct to S3 uploads**: Bypass your server for large files
- **Secure downloads**: Generate time-limited URLs for file downloads
- **Temporary access**: Share files with time-limited access tokens

### Error Handling

| Status Code | Description |
|-------------|-------------|
| 200 | Success - Signed URL generated |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid or missing LowCodeAPI token |
| 403 | Forbidden - AWS credentials don't have permission |
| 404 | Not Found - Bucket doesn't exist |
| 429 | Rate Limit Exceeded |
| 500 | Internal Server Error |

### Signed URL Expiration
- Default: 300 seconds (5 minutes)
- Maximum: 7 days (604800 seconds) - AWS limit
- Recommended: Set based on your upload/download time requirements

### Using Signed URLs

**For Uploads**:
```bash
# Use PUT method with the signed URL
curl -X PUT "{signedUrl}" \
  -H "Content-Type: {your-content-type}" \
  --data-binary @local-file
```

**For Downloads**:
```bash
# Use GET method with the signed URL
curl -O "{signedUrl}"
# Or download to specific filename
curl -o output.txt "{signedUrl}"
```

### Response Format

All responses are wrapped in a `data` key:

```json
{
  "data": {
    "signedUrl": "https://...",
    "expiresAt": "2026-02-11T06:00:00Z",
    "bucket": "bucket-name",
    "key": "file/path/to/file.ext"
  }
}
```

## AWS S3 Best Practices

1. **Organize with prefixes**: Use key prefixes (folders) to organize files
2. **Use appropriate ACLs**: Default to `private`, only use `public` when necessary
3. **Set reasonable expiration**: Don't set URLs to expire too far in the future
4. **Monitor bucket size**: Keep track of storage usage
5. **Enable versioning**: Consider enabling versioning for important buckets
6. **Use lifecycle policies**: Auto-delete old files when appropriate

## Links
- **Official Documentation**: https://docs.aws.amazon.com/AmazonS3/latest/API/Type_API_Reference.html
- **AWS Console**: https://console.aws.amazon.com/s3/
- **AWS Website**: https://aws.amazon.com/
- **LowCodeAPI Integration**: This wrapper provides secure, token-based access to AWS S3