---
title: "Storage API"
description: "Manage storage buckets, S3 access keys, objects, presigned URLs and bucket metrics over the Edge REST API, with endpoint tables and curl examples."
url: "https://edge.network/docs/api/storage"
section: "REST API"
---

# Storage API

Manage buckets, S3 access keys, and objects under /api/storage.

All endpoints require [authentication](/docs/api/authentication). For high-volume object traffic, use the S3-compatible endpoint at `storage.edge.network` with any S3 SDK. See [SDK examples](/docs/storage/sdk-examples).

## Quick start

```bash
# 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. Body: `{ 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. Body: `{ 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](/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. Body: `{ source_key, dest_key }` |
| `POST /api/storage/buckets/:name/folders` | Create a folder. Body: `{ path }` |
| `POST /api/storage/buckets/:name/download-zip` | Download up to 100 objects as a ZIP. Body: `{ keys: [...] }` |

### Presigned URLs

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

```bash
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:

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

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

## Activity and 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 |