# POST /storage/upload

> Upload a file to project storage

Uploads a file (currently supports images) to the project's storage. Returns a media ID that can be used to link the file to other resources, such as a user avatar.

  **Authentication required.** You must send a valid JWT: `Authorization: Bearer <token>`

## Endpoint

```http
POST /v1/public/projects/:projectSlug/storage/upload
```

## Request Parameters

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `projectSlug` | string | ✅ | Your project's unique slug |

### Headers

| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | ✅ | `Bearer <jwt-token>` |
| `Content-Type` | ✅ | `multipart/form-data` |

### Body (Multipart Form Data)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file` | File | ✅ | The file to upload (Max 5MB, Images only) |

## Response

### Success (201 Created)

```json
{
  "id": "725365d7-21fc-45eb-b6ec-8390f0a438d1",
  "url": "/v1/public/projects/my-project/storage/725365d7-21fc-45eb-b6ec-8390f0a438d1/file",
  "filename": "avatar.jpg",
  "mime_type": "image/jpeg",
  "size": 177382
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | **Important:** The Media ID. Use this ID to link the file to other resources (e.g., updating user avatar). |
| `url` | string | Public URL to access the file |
| `filename` | string | Original filename |
| `mime_type` | string | File MIME type |
| `size` | number | File size in bytes |

### Error Responses

| Status Code | Error Code | Description |
|-------------|------------|-------------|
| 400 | `BAD_REQUEST` | No file uploaded, invalid type, or size limit exceeded |
| 401 | `UNAUTHORIZED` | Missing or invalid token |
| 429 | `RATE_LIMIT_EXCEEDED` | Too many uploads |

## Usage Example

### Javascript (FormData)

```javascript
const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('https://api.aerostack.dev/v1/public/projects/my-project/storage/upload', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
    // Note: Do NOT set Content-Type header manually when using FormData, 
    // the browser will set it with the correct boundary.
  },
  body: formData
});

const data = await response.json();
console.log('Uploaded File ID:', data.id);
```