S3 API
Every filesystem is also an S3 bucket at https://s3.mountable.io/FS_ID/, for the AWS CLI, boto3, rclone, DuckDB and other S3 clients, with the same files mounts and the files API see.
Tools that speak S3 read and write a filesystem directly: the AWS CLI and
SDKs, rclone, DuckDB, pandas through fsspec, backup tools. An object is a
file. A file written through S3 is in every mount and in the
files API, and a file written there is an object.
The same quotas, spending caps, change feed and webhooks apply.
Endpoint and credentials
| Endpoint | https://s3.mountable.io |
| Bucket | the filesystem ID: https://s3.mountable.io/FS_ID/path/to/file |
| Addressing | path-style only; set it in every client |
| Region | any; use auto |
| Credentials | an S3 key: an access key ID MTBL… and its secret |
An S3 key works for exactly one filesystem, read-only or read-write, until it expires (at most 365 days) or is revoked. An owner or admin creates one on the filesystem's page in the console, or a provisioning service creates one with a management key. The secret is shown once.
Keep S3 keys on a trusted backend or your own machine. Never put one in a sandbox: mount the filesystem there instead, or hand it a pre-signed URL for one object.
The AWS CLI, boto3 and rclone examples below read the key from the environment; in the DuckDB example, replace the placeholders:
export AWS_ACCESS_KEY_ID=MTBL… # the S3 key's access key ID
export AWS_SECRET_ACCESS_KEY=… # its secret
export FS_ID=… # the filesystem ID, which is the bucketAWS CLI
export AWS_ENDPOINT_URL=https://s3.mountable.io
export AWS_DEFAULT_REGION=auto
aws configure set default.s3.addressing_style path
aws s3 sync ./results "s3://$FS_ID/results/"
aws s3 ls "s3://$FS_ID/results/" --recursive
aws s3 cp "s3://$FS_ID/results/summary.json" -boto3
import os
import boto3
from botocore.config import Config
s3 = boto3.client(
"s3",
endpoint_url="https://s3.mountable.io",
region_name="auto",
config=Config(s3={"addressing_style": "path"}),
) # reads AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
bucket = os.environ["FS_ID"]
# Create only if absent: a second writer gets 412 PreconditionFailed.
s3.put_object(Bucket=bucket, Key="reports/2026-11.json", Body=b"{}", IfNoneMatch="*")
body = s3.get_object(Bucket=bucket, Key="reports/2026-11.json")["Body"].read()
# Multipart for large files, handled by boto3.
s3.upload_file("model.safetensors", bucket, "models/model.safetensors")
for page in s3.get_paginator("list_objects_v2").paginate(Bucket=bucket, Prefix="reports/"):
for item in page.get("Contents", []):
print(item["Key"], item["Size"])rclone
export RCLONE_CONFIG_MOUNTABLE_TYPE=s3
export RCLONE_CONFIG_MOUNTABLE_PROVIDER=Other
export RCLONE_CONFIG_MOUNTABLE_ENDPOINT=https://s3.mountable.io
export RCLONE_CONFIG_MOUNTABLE_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID"
export RCLONE_CONFIG_MOUNTABLE_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY"
export RCLONE_CONFIG_MOUNTABLE_FORCE_PATH_STYLE=true
export RCLONE_CONFIG_MOUNTABLE_LIST_VERSION=2
rclone copy ./dataset "mountable:$FS_ID/dataset"
rclone lsf -R "mountable:$FS_ID/dataset"LIST_VERSION=2 is required: with PROVIDER=Other, rclone lists with the
older ListObjects v1, which is not served.
DuckDB
INSTALL httpfs;
LOAD httpfs;
CREATE SECRET mountable (
TYPE s3,
KEY_ID 'MTBL…',
SECRET '…',
ENDPOINT 's3.mountable.io',
URL_STYLE 'path',
REGION 'auto'
);
COPY (SELECT * FROM 'events.csv') TO 's3://FS_ID/tables/events.parquet';
SELECT count(*) FROM 's3://FS_ID/tables/*.parquet';Operations
| Served | Notes |
|---|---|
GetObject, HeadObject | with Range |
PutObject | If-None-Match: * writes only if nothing exists; If-Match only if the ETag matches |
DeleteObject, DeleteObjects | |
ListObjectsV2 | prefix, delimiter /, max-keys up to 1,000, continuation tokens |
CopyObject | within the same filesystem |
| Multipart upload | create, upload part, complete, abort, list parts |
Pre-signed GET and PUT URLs | expiry at most 7 days, never beyond the S3 key's own |
HeadBucket, ListBuckets | ListBuckets lists the key's one filesystem |
Current AWS SDKs send flexible checksums (x-amz-checksum-crc32 and
others) and may stream bodies as aws-chunked; both are accepted, and any
checksum sent is verified.
Not served: CreateBucket and DeleteBucket (create and delete
filesystems through the API or the console), versioning, ACLs,
bucket policies, lifecycle rules, object lock, tagging, public or anonymous
access, server-side encryption options, ListObjects v1, and requests
across filesystems. Most answer 501 NotImplemented; an unsigned request
or another filesystem's bucket answers 403 AccessDenied.
Objects are files
- Keys are paths.
a/b/c.txtis the filec.txtin the foldera/b; missing folders are created. An empty folder lists asa/. - Keys that cannot be paths are refused with
400 InvalidArgument:.or..segments, empty segments (//), a segment over 255 bytes, a key over 1,024 bytes, or a NUL. - The files API's guards apply. A parent that is a file is never turned
into a folder, and a symlink or a file with several hard links is never
overwritten or deleted through S3. These answer
409with the files API's code (not_a_directory,not_a_regular_file) in the error body. - No rename. Copy, then delete. Mounts keep real, atomic rename.
- Overwrites are atomic: a reader sees the old or the new file, never a mix.
- Freshness: S3 reads always see the latest write. A mount may show an S3 write only once its metadata cache expires, within seconds.
- ETags are never an MD5. An object's ETag is the files API's ETag with
-1appended, so the same file has the same identity in both APIs.If-Matchaccepts either form. Integrity on upload comes from the checksums above. - Multipart uploads stay invisible to mounts, listings and the change feed until they complete. Their parts count toward quota and spending, and are deleted on abort or 7 days after the upload began.
- Object size: at most 5 GiB (
413 EntityTooLarge). - Mode bits: files created through S3 get
0644, folders0755.
Limits, billing and events
- Quotas and spending caps apply to every S3 write, with the same status and code as for the files API.
- Bytes read through S3 are billed as downloads; storage and file count as for any file. There is no per-request price.
- S3 writes and deletes appear in the filesystem's change feed and trigger its webhooks.
- A signed request whose clock is more than 15 minutes off is refused with
403 RequestTimeTooSkewed, as in AWS; a pre-signed URL works until it expires.