Amazon S3

Operations on this page

Operation	Method and path	Python	Node.js
List selectable prefixes	`GET …/{connection_id}/s3/available-prefixes`	`connections.s3.available_prefixes`	`connections.s3.availablePrefixes`
List selected prefixes	`GET …/{connection_id}/s3/prefixes`	`connections.s3.prefixes`	`connections.s3.prefixes`
Select prefixes	`POST …/{connection_id}/s3/prefixes`	`connections.s3.add_prefixes`	`connections.s3.addPrefixes`
Revoke one prefix	`DELETE …/{connection_id}/s3/prefixes`	`connections.s3.remove_prefix`	`connections.s3.removePrefix`
Read the exclusion policy	`GET …/{connection_id}/s3/exclusion-policy`	`connections.s3.exclusion_policy`	`connections.s3.exclusionPolicy`
Replace the exclusion policy	`PUT …/{connection_id}/s3/exclusion-policy`	`connections.s3.set_exclusion_policy`	`connections.s3.setExclusionPolicy`
Read effective settings	`GET …/{connection_id}/s3/settings`	`connections.s3.settings`	`connections.s3.settings`

Authentication and scope

Requirement	Contract
Credential	An API key sent as `X-API-Key`. Connector operations are not end-user scoped.
Read scope	`integrations:read` for every `GET`.
Write scope	`integrations:write` for every `POST`, `PUT`, `PATCH` and `DELETE`.
Tenant	Derived from the authenticated key. There is no tenant parameter to pass or to get wrong.
`X-End-User-ID`	Not used. A connection belongs to the organization, not to one end user.

Before you start

S3 is the credential-based connector: create it with create_with_credentials on Connection Lifecycle, passing access_key_id, secret_access_key, region and bucket. There is no OAuth flow.

1. See what the credentials can reach

Lists prefixes visible in the bound bucket, annotated with whether each is already approved.

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
)

available = client.connections.s3.available_prefixes("conn_8f21a4")
print(available["bucket"], available["total"])
for entry in available["prefixes"]:
    print(entry["prefix"] or "(root)", entry["kind"], entry["approved"])

GET/api/v2/integrations/connections/{connection_id}/s3/available-prefixes

200 OK

Response field	Meaning
`bucket`	The bucket this connection is bound to.
`prefixes`	Each with `prefix`, `kind`, and `approved`.
`total`	How many were found.

2. Approve the prefixes to read

Bare strings are accepted for the common case, and objects when you want to carry a label. Approving a prefix starts the first sync straight away if the connection is healthy.

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
)

result = client.connections.s3.add_prefixes(
    "conn_8f21a4",
    ["handbook/", "policies/2026/"],
)
print(result["sync_triggered"])
for approved in result["approved"]:
    print(approved["prefix"], approved["state"])
for rejected in result["rejected"]:
    print("rejected:", rejected)

POST/api/v2/integrations/connections/{connection_id}/s3/prefixes

200 OK

Request field	Contract
`prefixes`	Required. A list of objects, each with `prefix`, and optionally `bucket` and `label`. Both SDKs widen a bare string to `{"prefix": "…"}` for you.

Response field	Meaning
`approved`	The prefix records that were stored.
`rejected`	Entries that were refused, each with a `prefix` and a `reason`. Show these — a silent partial success is how half a bucket goes missing.
`sync_triggered`	Whether approving started a sync immediately. It does when the connection is already connected.

3. Read back what is approved

Another of the bare-array responses: iterate the result itself rather than looking for a prefixes key.

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
)

for row in client.connections.s3.prefixes("conn_8f21a4"):
    print(row["prefix"] or "(root)", row["state"], row["is_active"])
    print("  synced:", row["objects_synced"], "indexed:", row["objects_indexed"])
    print("  skipped:", row["skipped"])

GET/api/v2/integrations/connections/{connection_id}/s3/prefixes

200 OK

Field	Meaning
`id`	The prefix approval record.
`bucket`, `prefix`, `label`	What is approved.
`state`, `state_detail`	Approval state and why.
`is_active`	Whether future syncs read it.
`objects_synced`	Lifetime tally of keys read across every run.
`objects_indexed`	Distinct objects currently stored. This is the one that answers "how much is in there".
`skipped`	A map of reason to count — the first place to look when a prefix produced less than expected.
`last_modified_at`, `last_synced_at`, `authorized_at`	Timestamps.

4. Block keys by pattern

The exclusion policy is a list of glob patterns matched against keys. A pattern blocks matching keys inside every approved prefix, which is how you keep a useful prefix without importing its build artifacts or backups.

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
)

client.connections.s3.set_exclusion_policy(
    "conn_8f21a4",
    tenant_patterns=["*.log", "backups/*", "*/tmp/*"],
)
policy = client.connections.s3.exclusion_policy("conn_8f21a4")
print(policy["effective_patterns"])
print("removed:", policy["purged_objects"], "objects,", policy["purged_memories"], "memories")

PUT/api/v2/integrations/connections/{connection_id}/s3/exclusion-policy

200 OK

GET/api/v2/integrations/connections/{connection_id}/s3/exclusion-policy

200 OK

Field	Meaning
`tenant_patterns`	Request and response. The patterns you set — the only field `PUT` reads, and the only list it replaces.
`deployment_patterns`	Response only. The operator-set floor, which you cannot remove here.
`effective_patterns`	Response only. Both lists combined, deduped — what actually applies.
`purged_objects`, `purged_memories`	Response only. How much already-indexed content the new policy removed.

5. Read the limits that decide what is parsed

Effective settings, including the ceilings that quietly exclude objects. An object over the size limit or with an unlisted extension produces no memories and no error, so this is the endpoint that explains an unexpectedly empty prefix.

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
)

settings = client.connections.s3.settings("conn_8f21a4")
print(settings["bucket"], settings["region"], settings["endpoint"])
print("max object MB:", settings["max_object_mb"])
print("max objects per sync:", settings["max_objects_per_sync"])
print("allowed extensions:", settings["allowed_extensions"])

GET/api/v2/integrations/connections/{connection_id}/s3/settings

200 OK

Field	Meaning
`bucket`, `region`, `endpoint`	What the connection points at. `endpoint` is set for S3-compatible storage.
`prefix`	A connection-level prefix, when one was configured with the credentials.
`max_object_mb`	Objects larger than this are skipped.
`max_objects_per_sync`	The ceiling on one run. A prefix larger than this needs several syncs.
`allowed_extensions`	Only these are parsed. Anything else is skipped without an error.

6. Revoke one prefix

Removes a single approval. The prefix travels as a query parameter, not in the body and not as a path segment, because prefixes contain slashes.

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
)

# Stop reading it, keep what it already produced.
client.connections.s3.remove_prefix("conn_8f21a4", "policies/2026/")

# Stop reading it and delete the memories it produced.
client.connections.s3.remove_prefix("conn_8f21a4", "policies/2026/", purge=True)

DELETE/api/v2/integrations/connections/{connection_id}/s3/prefixes

204 No Content

Parameter	Contract
`prefix`	The approved prefix. Defaults to `""`, which is the bucket root — so omitting it targets the root, not "all prefixes".
`bucket`	Optional. Defaults to the bucket the connection is bound to.
`purge`	Optional, default `false`. When true, also deletes the memories already derived from the prefix.

Errors and next action

Status	Meaning	Next action
`401`	Missing, malformed or inactive API key.	Check server configuration without printing the key.
`403`	The key lacks `integrations:read` or `integrations:write`.	Grant the scope on the key, or use a key that has it.
`404`	The connection, object or job is not visible to this tenant.	Confirm the identifier belongs to this organization.
`409`	The connection is in a state that forbids the operation.	Read the connection status first and act on it.
`429`	Rate limited, either by MemorySync or by the upstream provider.	Back off; do not tighten a polling loop in response.
`5xx`	Service failure.	Treat a write outcome as uncertain and reconcile by reading the connection back.

Connection Lifecycle

Create the credential-based connection.

Sync & Jobs

Follow the sync that approving started.

Synced Objects

Find out why a key produced nothing.

Operations on this page

Authentication and scope

Before you start

1. See what the credentials can reach

2. Approve the prefixes to read

3. Read back what is approved

4. Block keys by pattern

5. Read the limits that decide what is parsed

6. Revoke one prefix

Errors and next action

Related reference