S3 Connector

Connect Amazon S3 buckets or S3-compatible storage services (MinIO, DigitalOcean Spaces, Cloudflare R2, Tigris) to sync files into your Supermemory knowledge base.

The S3 connector requires a Scale Plan or higher. You can also create S3 connections directly from the Supermemory Console.

Quick Setup

TypeScript
Python
cURL

import Supermemory from 'supermemory';

const client = new Supermemory({
  apiKey: process.env.SUPERMEMORY_API_KEY!
});

const connection = await client.connections.create('s3', {
  metadata: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    bucket: 'my-documents-bucket',
    region: 'us-east-1'
  },
  containerTag: 'org-123'
});

from supermemory import Supermemory
import os

client = Supermemory(api_key=os.environ["SUPERMEMORY_API_KEY"])

connection = client.connections.create(
    's3',
    metadata={
        'accessKeyId': os.environ["AWS_ACCESS_KEY_ID"],
        'secretAccessKey': os.environ["AWS_SECRET_ACCESS_KEY"],
        'bucket': 'my-documents-bucket',
        'region': 'us-east-1'
    },
    container_tag='org-123'
)

curl -X POST "https://api.supermemory.ai/v3/connections/s3" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
      "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "bucket": "my-documents-bucket",
      "region": "us-east-1"
    },
    "containerTag": "org-123"
  }'

Configuration Options

For S3, provider-specific connection fields are passed inside the top-level metadata object. General connection options stay top-level.

Parameter	Location	Required	Description
`accessKeyId`	`metadata.accessKeyId`	Yes	AWS access key ID or S3-compatible service key
`secretAccessKey`	`metadata.secretAccessKey`	Yes	AWS secret access key
`bucket`	`metadata.bucket`	Yes	S3 bucket name
`region`	`metadata.region`	Yes	AWS region (e.g., `us-east-1`). Use `auto` for S3-compatible providers that don’t expose AWS-style regions (MinIO, R2, Tigris).
`endpoint`	`metadata.endpoint`	No	Custom endpoint for S3-compatible services
`prefix`	`metadata.prefix`	No	Key prefix filter (e.g., `documents/`)
`containerTagRegex`	`metadata.containerTagRegex`	No	Regex to extract container tags from file paths
`containerTag`	top-level	No	Tag for organizing this connection
`documentLimit`	top-level	No	Maximum documents to sync (default: 10,000)

In the Python SDK, use container_tags for the top-level option, but keep S3 metadata keys in camelCase: accessKeyId, secretAccessKey, and containerTagRegex.

S3-Compatible Services

Use metadata.endpoint to connect to S3-compatible storage. These services don’t use AWS-style regions, so set metadata.region to auto — the value is still required for request signing but the service ignores it.

// MinIO
const connection = await client.connections.create('s3', {
  metadata: {
    accessKeyId: 'minio-key',
    secretAccessKey: 'minio-secret',
    bucket: 'my-bucket',
    region: 'auto',
    endpoint: 'https://minio.example.com'
  },
  containerTag: 'minio-sync'
});

Common S3-compatible endpoint values:

Service	`metadata.endpoint`	`metadata.region`
DigitalOcean Spaces	`https://nyc3.digitaloceanspaces.com`	`nyc3`
Cloudflare R2	`https://<account-id>.r2.cloudflarestorage.com`	`auto`
Tigris	`https://t3.storage.dev`	`auto`

Cloudflare R2 example:

const connection = await client.connections.create('s3', {
  metadata: {
    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
    bucket: 'my-bucket',
    region: 'auto',
    endpoint: 'https://<account-id>.r2.cloudflarestorage.com'
  },
  containerTag: 'r2-sync'
});

For S3-compatible services, metadata.endpoint is the base S3 endpoint. Do not include the bucket name in the endpoint URL; pass the bucket separately as metadata.bucket.

Prefix Filtering

Sync only files within a specific path:

const connection = await client.connections.create('s3', {
  metadata: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    bucket: 'company-data',
    region: 'us-east-1',
    prefix: 'documents/engineering/' // Only syncs files under this path
  },
  containerTag: 'engineering-docs'
});

Dynamic Container Tags

Extract container tags from S3 key paths for multi-tenant setups:

const connection = await client.connections.create('s3', {
  metadata: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    bucket: 'user-files',
    region: 'us-east-1',
    containerTagRegex: 'users/(?<userId>[^/]+)/'
  },
  containerTag: 'user-files'
});

// File: users/user-123/documents/notes.md → container tag: user-123
// File: users/user-456/reports/q4.pdf → container tag: user-456

The regex must contain a named capture group (?<userId>...) and be less than 200 characters.

Connection Management

Delete Connection

TypeScript
cURL

await client.connections.deleteByID('conn_s3_abc123');

curl -X DELETE "https://api.supermemory.ai/v3/connections/conn_s3_abc123" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

By default, deleting a connection removes all synced documents from Supermemory. To keep documents, pass deleteDocuments=false as a query parameter: DELETE /v3/connections/:id?deleteDocuments=false

Manual Sync

TypeScript
cURL

await client.connections.import('s3', {
  containerTags: ['org-123']
});

curl -X POST "https://api.supermemory.ai/v3/connections/s3/import" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"containerTags": ["org-123"]}'

Sync Behavior

Feature	Behavior
Initial sync	Fetches all files matching prefix filter
Incremental sync	Only files modified since last sync
Sync schedule	Every 4 hours + manual triggers
Document limit	10,000 files per connection (default)

IAM Permissions

Minimum required permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    }
  ]
}

Error Codes

Code	Message	Solution
401	Authentication failed	Verify access key and secret
403	Access denied	Check IAM permissions and bucket policy
404	Bucket not found	Verify bucket name and region

Getting Started

Concepts

Using supermemory

Deployment

Other resources

Migration Guides

Quick Setup

Configuration Options

S3-Compatible Services

Prefix Filtering

Dynamic Container Tags

Connection Management

Delete Connection

Manual Sync

Sync Behavior

IAM Permissions

Error Codes

​Quick Setup

​Configuration Options

​S3-Compatible Services

​Prefix Filtering

​Dynamic Container Tags

​Connection Management

​Delete Connection

​Manual Sync

​Sync Behavior

​IAM Permissions

​Error Codes

Quick Setup

Configuration Options

S3-Compatible Services

Prefix Filtering

Dynamic Container Tags

Connection Management

Delete Connection

Manual Sync

Sync Behavior

IAM Permissions

Error Codes