API reference

S3 API

Use S3 tools with an API key: the endpoint, the signing region, path-style addressing, and the S3 operations that storage supports.

Connection

Storage speaks S3 at the storage host. An API key is the S3 credential. Any S3 tool that signs with Signature Version 4 works.

Setting	Value
Endpoint	`https://g4.beta.graphon.ai`
Region	`us-east-1`
Addressing	Path style: /{bucket}/{key}
Access key ID	The part of the API key between the _ and the .
Secret access key	The whole API key

us-east-1 is only the signing region. Your data stays in the location that you chose for the bucket. A key covers every bucket in its workspace, and each request needs the role in the table below. See Authentication & keys for how to get the credentials.

Set up a client

~/.aws/config

# ~/.aws/config
[profile graphon]
credential_process = graphon s3-credentials --format process
endpoint_url = https://g4.beta.graphon.ai
region = us-east-1
s3 =
  addressing_style = path

aws CLI

aws s3 ls --profile graphon
aws s3 cp ./checkout-timeout.json s3://support-tickets/incidents/ --profile graphon

boto3

import os

import boto3
from botocore.config import Config

api_key = os.environ["GRAPHON_API_KEY"]
access_key_id = api_key.split("_", 1)[1].split(".")[0]

s3 = boto3.client(
    "s3",
    endpoint_url="https://g4.beta.graphon.ai",
    region_name="us-east-1",
    aws_access_key_id=access_key_id,
    aws_secret_access_key=api_key,
    config=Config(signature_version="s3v4", s3={"addressing_style": "path"}),
)
print(s3.list_objects_v2(Bucket="support-tickets", Prefix="incidents/"))

rclone

# ~/.config/rclone/rclone.conf
[graphon]
type = s3
provider = Other
endpoint = https://g4.beta.graphon.ai
region = us-east-1
force_path_style = true
env_auth = true

# Then, with GRAPHON_API_KEY set, this sets AWS_ACCESS_KEY_ID and
# AWS_SECRET_ACCESS_KEY for rclone:
# eval "$(graphon s3-credentials)"
# rclone ls graphon:support-tickets

Operations

Each row is one S3 operation. Role is the lowest role whose key can send it. A request for an operation that is not supported returns 501 NotImplemented.

Operation	Request	Role	Supported	Notes
`ListBuckets`	`GET /`	Viewer	Yes	Lists the buckets in the key's workspace, in name order. `aws s3 ls`
`CreateBucket`	`PUT /{bucket}`	Editor	Yes	Send LocationConstraint as provider:location, for example gcp:us-central1. A new bucket is private and standard class. `aws s3api create-bucket --bucket support-tickets --create-bucket-configuration LocationConstraint=gcp:us-central1`
`HeadBucket`	`HEAD /{bucket}`	Viewer	Yes	Finds an active or offline bucket, and returns the signing region. `aws s3api head-bucket --bucket support-tickets`
`DeleteBucket`	`DELETE /{bucket}`	Editor	Yes	The bucket must be empty. It stays restorable for seven days. `aws s3 rb s3://support-tickets`
`GetBucketLocation`	`GET /{bucket}?location`	Viewer	Yes	Returns us-east-1, the signing region. The JSON API reports the real location. `aws s3api get-bucket-location --bucket support-tickets`
`GetBucketVersioning`	`GET /{bucket}?versioning`	Viewer	Yes	Returns empty, Enabled, or Suspended. `aws s3api get-bucket-versioning --bucket support-tickets`
`PutBucketVersioning`	`PUT /{bucket}?versioning`	Editor	Partial	Enabled or Suspended. MFA delete is rejected. `aws s3api put-bucket-versioning --bucket support-tickets --versioning-configuration Status=Enabled`
`ListMultipartUploads`	`GET /{bucket}?uploads`	Viewer	Yes	Lists uploads that are not complete yet. `aws s3api list-multipart-uploads --bucket support-tickets`
`GetObjectLockConfiguration`	`GET /{bucket}?object-lock`	Viewer	Yes	Returns the default retention for new versions. `aws s3api get-object-lock-configuration --bucket support-tickets`
`PutObjectLockConfiguration`	`PUT /{bucket}?object-lock`	Editor	Partial	COMPLIANCE mode with a default in days. Years, GOVERNANCE, and legal hold return 501. `aws s3api put-object-lock-configuration --bucket support-tickets --object-lock-configuration '{"ObjectLockEnabled":"Enabled","Rule":{"DefaultRetention":{"Mode":"COMPLIANCE","Days":30}}}'`
`DeleteObjects`	`POST /{bucket}?delete`	Editor	Yes	Up to 1,000 keys. Each key gets its own result. Quiet mode works. `aws s3api delete-objects --bucket support-tickets --delete '{"Objects":[{"Key":"a.json"},{"Key":"b.json"}]}'`
`ListObjectVersions`	`GET /{bucket}?versions`	Viewer	Yes	Lists live versions and delete markers, with key and version markers. `aws s3api list-object-versions --bucket support-tickets`
`ListObjectsV2`	`GET /{bucket}?list-type=2`	Viewer	Yes	prefix, delimiter, continuation-token, start-after, max-keys, and encoding-type. `aws s3 ls s3://support-tickets/incidents/`
`ListObjects`	`GET /{bucket}`	Viewer	Yes	The legacy listing, with marker pagination. `aws s3api list-objects --bucket support-tickets`
`GetObjectRetention`	`GET /{bucket}/{key}?retention`	Viewer	Yes	Returns the retention of the selected version. `aws s3api get-object-retention --bucket support-tickets --key a.json`
`PutObjectRetention`	`PUT /{bucket}/{key}?retention`	Editor	Partial	COMPLIANCE only. Retention can be added or extended, never shortened. `aws s3api put-object-retention --bucket support-tickets --key a.json --retention Mode=COMPLIANCE,RetainUntilDate=2027-01-01T00:00:00Z`
`GetObjectTagging`	`GET /{bucket}/{key}?tagging`	Viewer	Yes	Returns the tags of the live version. `aws s3api get-object-tagging --bucket support-tickets --key a.json`
`PutObjectTagging`	`PUT /{bucket}/{key}?tagging`	Editor	Yes	Replaces the whole tag set. `aws s3api put-object-tagging --bucket support-tickets --key a.json --tagging 'TagSet=[{Key=team,Value=support}]'`
`DeleteObjectTagging`	`DELETE /{bucket}/{key}?tagging`	Editor	Yes	Empties the tag set. `aws s3api delete-object-tagging --bucket support-tickets --key a.json`
`CreateMultipartUpload`	`POST /{bucket}/{key}?uploads`	Editor	Yes	Starts an upload. aws s3 cp uses multipart for large files. `aws s3 cp ./big.bin s3://support-tickets/big.bin`
`UploadPartCopy`	`PUT /{bucket}/{key}?partNumber&uploadId with x-amz-copy-source`	Editor	Partial	The source needs the Viewer role and must be in the same workspace. One byte range per part.
`UploadPart`	`PUT /{bucket}/{key}?partNumber&uploadId`	Editor	Yes	Returns the part ETag. Every part except the last must be the same size.
`ListParts`	`GET /{bucket}/{key}?uploadId`	Viewer	Yes	Lists the parts of one upload, in part order.
`CompleteMultipartUpload`	`POST /{bucket}/{key}?uploadId`	Editor	Yes	Send the parts in ascending order with their exact ETags.
`AbortMultipartUpload`	`DELETE /{bucket}/{key}?uploadId`	Editor	Yes	Safe to send twice.
`CopyObject`	`PUT /{bucket}/{key} with x-amz-copy-source`	Editor	Partial	The source needs the Viewer role and must be in the same workspace. A copy across storage providers returns 501. `aws s3 cp s3://support-tickets/a.json s3://support-tickets/b.json`
`PutObject`	`PUT /{bucket}/{key}`	Editor	Yes	One request can carry at most 200 MiB. Send x-amz-checksum-sha256 to have G4 check the bytes. If-None-Match: * creates only. `aws s3 cp ./a.json s3://support-tickets/a.json`
`HeadObject`	`HEAD /{bucket}/{key}`	Viewer	Yes	The same headers as GetObject, with no body. A public-read bucket needs no signature. `aws s3api head-object --bucket support-tickets --key a.json`
`GetObject`	`GET /{bucket}/{key}`	Viewer	Partial	Supports versionId, conditions, and one byte range. Multiple ranges return 501. A public-read bucket needs no signature. `aws s3 cp s3://support-tickets/a.json ./a.json`
`DeleteObject`	`DELETE /{bucket}/{key}`	Editor	Yes	With versionId, removes that version. In a versioned bucket, adds a delete marker. `aws s3 rm s3://support-tickets/a.json`
`Options`	`OPTIONS /{bucket}/{key}`	—	Yes	CORS preflight only. It reads and changes nothing.
`BucketWebsiteCorsLifecycle`	`GET /{bucket}?website`	—	No	Website, CORS, and lifecycle configuration return 501.
`ObjectAcl`	`GET /{bucket}/{key}?acl`	—	No	Object ACLs return 501. Use the bucket permission in the JSON API.
`ObjectLegalHold`	`GET /{bucket}/{key}?legal-hold`	—	No	Legal hold returns 501.
`SelectObjectContent`	`POST /{bucket}/{key}?select`	—	No	S3 Select returns 501.
`ServerSideEncryptionWithCustomerKeys`	`PUT /{bucket}/{key} with x-amz-server-side-encryption-customer-algorithm`	—	No	SSE-C returns 501. Providers encrypt every object at rest.

Larger files

One PUT or one multipart part carries a limited size. The S3 tools above switch to a multipart upload for a large file by themselves. See Limits.

Was this page helpful?