POST /storage/upload

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.

Caution

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

Endpoint

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)

{
  "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)

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);