API Reference

Build with fstorage API

Authentication

All API requests require authentication via an API key. Include your API key in the X-API-Key header of every request. You can generate and manage your API keys from the dashboard.

curl -X POST https://api.fstorage.duckdns.org/v1/files \
-H "X-API-Key: your-api-key-here" \
-F "file=@document.pdf"

Base URL

https://api.fstorage.duckdns.org/v1

All endpoints are versioned under the /v1 namespace. Future versions will be released under a new version prefix.

Endpoints

Upload a file

POST /v1/files

Upload a file to fstorage. The file is stored securely and a unique identifier is returned for retrieval.

curl -X POST https://api.fstorage.duckdns.org/v1/files \
-H "X-API-Key: your-api-key-here" \
-F "file=@document.pdf"

Download a file

GET /v1/files/:id

Retrieve a previously uploaded file using its unique ID.

curl -X GET https://api.fstorage.duckdns.org/v1/files/abc123 \
-H "X-API-Key: your-api-key-here" \
-o downloaded-file.pdf

Delete a file

DELETE /v1/files/:id

Permanently remove a file from storage using its unique ID.

curl -X DELETE https://api.fstorage.duckdns.org/v1/files/abc123 \
-H "X-API-Key: your-api-key-here"

Rate Limits

API requests are rate-limited to ensure fair usage and system stability.

  • Free tier: 1,000 requests per hour
  • Pro tier: 10,000 requests per hour

Rate limit headers are included in every API response so you can monitor your usage.

Response Format

All API responses are returned in JSON format. A successful response includes the requested data along with a status indicator.

{
"status": "success",
"data": {
"id": "abc123",
"filename": "document.pdf",
"size": 1024000,
"mime_type": "application/pdf",
"expires_at": "2026-08-29T12:00:00Z",
"download_url": "https://api.fstorage.duckdns.org/v1/files/abc123"
}
}

Error Codes

The API uses standard HTTP response codes to indicate success or failure.

  • 400 Bad Request - The request was malformed or missing required parameters.
  • 401 Unauthorized - Invalid or missing API key.
  • 403 Forbidden - You do not have permission to access the requested resource.
  • 404 Not Found - The requested resource does not exist.
  • 429 Too Many Requests - Rate limit exceeded. Wait before retrying.
  • 500 Internal Server Error - Something went wrong on our end.