Storage API

The Storage service provides object storage with presigned URLs for secure file uploads and downloads.

Base URL: https://storage.nextepoch.cloud

Upload File

Get Presigned Upload URL

POST /v1/upload

Headers:

Header	Required	Description
Authorization	Yes	Bearer <your-jwt-token>
Content-Type	Yes	application/json

Request Body:

{
  "filename": "report.pdf",
  "content_type": "application/pdf"
}

Response:

{
  "data": {
    "upload_url": "https://...",
    "file_id": "file_abc123",
    "expires_in": 3600
  }
}

Then upload the file directly to the presigned URL:

curl -X PUT "<upload_url>" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

Download File

Get Presigned Download URL

GET /v1/files/{file_id}/download

Headers:

Header	Required	Description
Authorization	Yes	Bearer <your-jwt-token>

Response:

{
  "data": {
    "download_url": "https://...",
    "filename": "report.pdf",
    "content_type": "application/pdf",
    "size_bytes": 104857,
    "expires_in": 3600
  }
}

List Files

GET /v1/files

Query Parameters:

Parameter	Type	Default	Description
limit	integer	50	Max results (1-100)
offset	integer	0	Pagination offset

Response:

{
  "data": {
    "files": [
      {
        "id": "file_abc123",
        "filename": "report.pdf",
        "content_type": "application/pdf",
        "size_bytes": 104857,
        "created_at": "2025-01-15T10:30:00Z"
      }
    ],
    "total": 42
  }
}

Delete File

DELETE /v1/files/{file_id}

Response: 204 No Content

Health Check

GET /health

Returns service health status.