Skip to main content

AWS S3 Integration — Quick Reference

Get started with ValkyrAI's S3-backed file storage in under a minute. This guide covers health checks, upload flow, and the major classes you’ll interact with.

Quick Health Check​

curl http://localhost:8080/actuator/health/s3StorageHealth | jq .

Expect a healthy JSON response (status UP) when S3 is configured.

Upload Flow (presigned multipart)​

  1. Create an upload session
curl -X POST http://localhost:8080/v1/files/uploads/init \
  -H "Content-Type: application/json" \
  -d '{"fileName":"test.pdf","mimeType":"application/pdf","fileSize":1024}'

  1. Upload parts to the provided presigned URLs (from step 1)

  2. Complete the upload

curl -X POST http://localhost:8080/v1/files/uploads/complete \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"...","parts":[{"partNumber":1,"eTag":"..."}]}'

Key Classes (where to look in code)​

  • AwsS3IntegrationUtil — access default bucket, region, role ARN and configuration
  • InternalAwsS3IntegrationInitializer — sets up the internal account and permissions
  • S3StorageDriver — actual S3 storage implementation
  • FileUploadService — orchestrates upload sessions and completion
  • FileController — REST endpoints to initiate/upload/complete

Quick Troubleshooting​

  • Missing permissions / 403 → verify role and bucket policy
  • Presigned URL errors → check clocks (time sync) and region values
  • Multipart completion fails → verify parts and ETags match

See also: S3 File Storage Quick Reference