# S3 endpoints

Any S3-compatible bucket can be a location: Tigris, Cloudflare R2, a neocloud's
object store, or an existing S3 or GCS bucket you would rather not have the app
create. It is the usual choice for the fallback.

## Fields

| Field                 | Is                                                                                                                          |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Endpoint              | The S3 API URL, `https://t3.storage.dev` or `https://s3.us-east-1.amazonaws.com`                                            |
| Bucket                | An existing bucket                                                                                                          |
| Path                  | An optional prefix inside it; versions go under it                                                                          |
| Signing region        | The SigV4 region, `auto` for Tigris and R2                                                                                  |
| Path style            | `https://endpoint/bucket/key` instead of `https://bucket.endpoint/key`                                                      |
| Access key ID, secret | A key that can put, get and delete objects and run multipart uploads in the bucket. Stored encrypted; never handed to a box |
| Cloud, region         | The **placement tag**: what a box that should write here reports                                                            |
| Fallback              | Make this the organization's fallback                                                                                       |

The cloud and region are free strings matched against what a box reports:
`nebius` / `eu-north1` for a Nebius bucket, `aws` / `us-east-1` for an existing
S3 bucket, `tigris` / `global` for a fallback no box reports. See
[Locations and placement](https://artifacts.041.io/docs/placement.md).

Before saving, the app tests a put, a ranged get, a multipart upload and a
delete against the bucket, so a wrong key or a missing permission shows up at
once, not at the first checkpoint. It then writes `_o41_organization` at the
path, naming your organization: another organization cannot add the same bucket
path, so two never write over each other's versions.

## Example

```bash
curl -X POST -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  https://artifacts.041.io/api/v1/locations -d '{
    "kind": "s3",
    "endpoint": "https://t3.storage.dev",
    "bucket": "my-checkpoints",
    "path": "artifacts",
    "signingRegion": "auto",
    "pathStyle": true,
    "accessKeyId": "tid_…",
    "secretAccessKey": "tsec_…",
    "cloud": "tigris",
    "region": "global",
    "fallback": true
  }'
```

---

Artifacts by 041 documentation. Every page: https://artifacts.041.io/llms.txt