---
title: "Storage API"
description: "Manage buckets, S3 access keys, and objects over the Edge REST API."
url: https://edge.network/docs/api/storage/
---

# Storage API

# Storage API

Manage buckets, S3 access keys, and objects under
`/api/storage`.
For high-volume object traffic, use the S3-compatible endpoint at
`storage.edge.network` with any S3 SDK —
see [SDK Examples](https://edge.network/docs/storage/sdk-examples).

## Quick Start

```
# Create a bucket
curl -X POST https://edge.network/api/storage/buckets \
  -H "Authorization: Bearer ek_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-assets" }'

# Create S3 credentials
curl -X POST https://edge.network/api/storage/keys \
  -H "Authorization: Bearer ek_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "app-uploads" }'
```

## Buckets

| Endpoint | Description |
| GET | POST /api/storage/buckets | List / create buckets — body `{ name, notes? }` |
| GET | PATCH | DELETE /api/storage/buckets/:name | Get / update notes / delete (bucket must be empty) |
| PATCH /api/storage/buckets/:name/public | Toggle public access — body `{ "is_public": true }` |
| GET | POST /api/storage/buckets/:name/lifecycle | List / add expiry rules — `{ prefix?, expire_days }` |
| DELETE .../lifecycle/:ruleId | Remove a lifecycle rule |
| GET /api/storage/usage | Total bytes, object counts, and per-bucket breakdown |

## S3 Access Keys

| Endpoint | Description |
| GET | POST /api/storage/keys | List / create S3 credentials — `{ name?, permissions?, bucketScope? }` |
| DELETE /api/storage/keys/:id | Delete credentials |
| GET /api/storage/endpoint | S3 connection details — `{ endpoint, port, region }` |

These are separate from your account API keys — they authenticate S3 SDKs against
`storage.edge.network`.
See [Access Keys](https://edge.network/docs/storage/access-keys).

## Objects

| Endpoint | Description |
| GET /api/storage/buckets/:name/objects?prefix=&marker= | List objects, optionally under a prefix |
| POST /api/storage/buckets/:name/upload | Upload — multipart or raw body |
| GET /api/storage/buckets/:name/download/* | Download an object (also accepts presigned `?token=`) |
| DELETE /api/storage/buckets/:name/objects/* | Delete an object |
| POST /api/storage/buckets/:name/copy | Copy within a bucket — `{ source_key, dest_key }` |
| POST /api/storage/buckets/:name/folders | Create a folder — `{ path }` |
| POST /api/storage/buckets/:name/download-zip | Download up to 100 objects as a ZIP — `{ keys: [...] }` |

### Presigned URLs

Generate time-limited upload or download URLs to hand to browsers and untrusted clients:

```
curl -X POST https://edge.network/api/storage/buckets/my-assets/presign \
  -H "Authorization: Bearer ek_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "key": "uploads/photo.jpg", "action": "upload", "expires": "1h" }'

# Response
{
  "url": "https://storage.edge.network/...",
  "method": "PUT",
  "expires": "1h"
}
```

`expires` accepts values like
`30m`, `1h`,
`7d` (default 1h, max 7d). See
[Presigned URLs](https://edge.network/docs/storage/presigned-urls).

## Activity & Metrics

| Endpoint | Description |
| GET /api/storage/buckets/:name/events?limit=50 | Bucket activity log |
| GET /api/storage/buckets/:name/metrics?hours=168 | Hourly request and bandwidth metrics |
| GET .../metrics/summary?hours=24 | Aggregated metrics for a window |
| GET .../metrics/top-objects?limit=10 | Most-accessed objects |
| GET .../metrics/file-types | Storage broken down by file type |

[Back to Docs](https://edge.network/docs) [Need help?](https://edge.network/support)