API.md

Image Management API Documentation

Base URL

The API is accessible at: https://file-upload.replit.app/api

Authentication

Protected endpoints require an API key to be included in the request headers:

X-API-KEY: your-api-key-here

Endpoints

Upload Image

Upload a new image to the storage.

POST /api/upload
Content-Type: multipart/form-data
X-API-KEY: your-api-key

Request Body:

• file: Image file (Required)
  • Supported formats: JPEG, PNG
  • Max file size: 5MB

Example Request (zsh/bash):

# Using curl
curl -X POST \
  -H "Content-Type: multipart/form-data" \
  -H "X-API-KEY: your-api-key" \
  -F "file=@\"./path/to/your/image.jpg\"" \
  https://file-upload.replit.app/api/upload

# Using httpie (alternative)
http -f POST https://file-upload.replit.app/api/upload \
  "X-API-KEY: your-api-key" \
  file@"./path/to/your/image.jpg"

Success Response:

{
  "success": true,
  "data": {
    "id": 1,
    "filename": "images/1234567890-image.jpg",
    "url": "/api/storage/1234567890-image.jpg",
    "contentType": "image/jpeg",
    "size": 123456
  }
}

Get All Images

Retrieve a list of all uploaded images.

GET /api/images

Example Request (zsh/bash):

# Using curl
curl "https://file-upload.replit.app/api/images"

# Using httpie (alternative)
http GET https://file-upload.replit.app/api/images

Success Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "filename": "images/1234567890-image.jpg",
      "url": "/api/storage/1234567890-image.jpg",
      "contentType": "image/jpeg",
      "size": 123456
    }
  ]
}

Get Single Image

Retrieve information about a specific image by ID.

GET /api/images/:id

Example Request (zsh/bash):

# Using curl
curl "https://file-upload.replit.app/api/images/1"

# Using httpie (alternative)
http GET https://file-upload.replit.app/api/images/1

Success Response:

{
  "success": true,
  "data": {
    "id": 1,
    "filename": "images/1234567890-image.jpg",
    "url": "/api/storage/1234567890-image.jpg",
    "contentType": "image/jpeg",
    "size": 123456
  }
}

Delete Image

Delete a specific image by ID.

DELETE /api/images/:id
X-API-KEY: your-api-key

Example Request (zsh/bash):

# Using curl
curl -X DELETE \
  -H "X-API-KEY: your-api-key" \
  "https://file-upload.replit.app/api/images/1"

# Using httpie (alternative)
http DELETE https://file-upload.replit.app/api/images/1 \
  "X-API-KEY: your-api-key"

Success Response:

{
  "success": true,
  "data": {
    "id": 1
  }
}

Download/View Image

Get the actual image file.

GET /api/storage/:filename

Example Request (zsh/bash):

# Using curl (download file)
curl -O "https://file-upload.replit.app/api/storage/1234567890-image.jpg"

# Using curl (view in browser)
curl "https://file-upload.replit.app/api/storage/1234567890-image.jpg"

# Using httpie
http GET https://file-upload.replit.app/api/storage/1234567890-image.jpg

Response:

• Returns the image file directly
• Appropriate content-type header will be set (image/jpeg, image/png)
• Includes caching headers for better performance

Error Responses

All endpoints return error responses in the following format:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Common HTTP Status Codes:

• 400: Bad Request (invalid input)
• 401: Unauthorized (missing API key)
• 403: Forbidden (invalid API key)
• 404: Not Found (image or resource doesn't exist)
• 500: Internal Server Error

File Size and Type Restrictions

• Maximum file size: 5MB
• Supported image formats: JPEG, PNG
• Filenames are automatically sanitized and timestamped

Shell-specific Notes

• If you're using zsh or bash, the examples above should work as-is
• For filenames with spaces, make sure to properly escape or quote them
• For curl uploads, the @ symbol must be immediately after the = sign
• All URLs are properly quoted to handle special characters

Testing Examples

Here's a quick test you can run to verify the API is working:

# List all images (public endpoint)
curl "https://file-upload.replit.app/api/images"

# Upload a test image (protected endpoint)
curl -X POST \
  -H "Content-Type: multipart/form-data" \
  -H "X-API-KEY: your-api-key" \
  -F "file=@\"./test-image.jpg\"" \
  https://file-upload.replit.app/api/upload

For testing uploads with sample images, you can use any JPEG or PNG file under 5MB.