API Documentation
Integrate hostedit.cloud into your apps. Upload, manage, and share files programmatically using simple REST endpoints.
REST API
API Key Auth
Pro Plan Required
Introduction
The hostedit.cloud API lets you manage files programmatically — upload, list, delete, and generate public share links. It's a simple JSON REST API secured with API keys.
Authentication
All API requests require an API key. Generate one from your API Keys page. Keys begin with hit_.
Option 1 — X-API-Key Header (recommended)
# Example with curl
curl https://hostedit.cloud/api/developer/v1/me \
-H "X-API-Key: hit_your_key_here"
Option 2 — Bearer Token
curl https://hostedit.cloud/api/developer/v1/me \
-H "Authorization: Bearer hit_your_key_here"
Keep your API key secret. Never expose it in client-side code or public repositories. Rotate keys immediately if compromised.
Base URL
All API endpoints are prefixed with:
https://hostedit.cloud/api/developer/v1
All responses are JSON with standard HTTP status codes.
Error Handling
Errors return a JSON object with a detail field describing the problem.
{
"detail": "File not found"
}
HTTP Status Codes
| Code | Meaning |
|---|
200 | Success |
400 | Bad request (invalid parameters, quota exceeded) |
401 | Missing or invalid API key |
403 | Plan does not include API access |
404 | Resource not found |
429 | Rate limit exceeded |
500 | Internal server error |
Account Info
Returns your user profile, plan info, and current storage usage.
Example Response
{
"id": 42,
"username": "yourname",
"email": "you@example.com",
"plan": "250gb",
"storage_used": 1073741824,
"storage_limit": 268435456000
}
List Files
Returns an array of all your files, ordered newest first.
Example Response
[
{
"id": 123,
"name": "photo.jpg",
"size": 2048576,
"mime_type": "image/jpeg",
"is_public": true,
"public_token": "a1b2c3d4-...",
"download_count": 17,
"created_at": "2025-05-01T12:00:00"
}
]
Get File
Returns full details for one file by ID, including share status and expiry.
Example
curl https://hostedit.cloud/api/developer/v1/files/123 \
-H "X-API-Key: hit_your_key_here"
Example Response
{
"id": 123,
"name": "photo.jpg",
"size": 2048576,
"mime_type": "image/jpeg",
"is_public": true,
"public_token": "a1b2c3d4-...",
"public_expires_at": "2025-05-22T15:00:00",
"download_count": 17,
"created_at": "2025-05-01T12:00:00"
}
Upload File
Upload a file using multipart/form-data. The file is stored in your account and counts against your storage quota.
Request
| Field | Type | Description |
|---|
file |
File |
The file to upload. Required
Max 10 GB per file. |
Example (curl)
curl -X POST https://hostedit.cloud/api/developer/v1/files/upload \
-H "X-API-Key: hit_your_key_here" \
-F "file=@/path/to/your/file.jpg"
Example Response
{
"id": 456,
"name": "file.jpg",
"size": 2048576,
"mime_type": "image/jpeg",
"created_at": "2025-05-21T10:30:00"
}
Rename File
Updates the display name of a file. The internal storage key is unchanged — only the label shown in your dashboard and API responses changes.
Body Parameters
| Field | Type | Description |
|---|
name | string | New filename. Required |
Example
curl -X PATCH https://hostedit.cloud/api/developer/v1/files/123 \
-H "X-API-Key: hit_your_key_here" \
-H "Content-Type: application/json" \
-d '{"name": "new-name.jpg"}'
Example Response
{
"id": 123,
"name": "new-name.jpg"
}
Get Download URL
Returns a time-limited URL that allows direct download of the file for 1 hour. Useful for piping downloads into scripts or automation.
Example
curl https://hostedit.cloud/api/developer/v1/files/123/download-url \
-H "X-API-Key: hit_your_key_here"
Example Response
{
"url": "https://cdn.hostedit.cloud/files/...",
"expires_in": 3600,
"filename": "photo.jpg"
}
Usage example (download to disk)
# Shell one-liner: fetch URL then download the file
URL=$(curl -s https://hostedit.cloud/api/developer/v1/files/123/download-url \
-H "X-API-Key: hit_your_key_here" | jq -r '.url')
curl -L "$URL" -o photo.jpg
Delete File
Permanently deletes a file and frees the storage. This action cannot be undone.
Path Parameters
| Parameter | Type | Description |
|---|
file_id | integer | The ID of the file to delete. Required |
Example
curl -X DELETE https://hostedit.cloud/api/developer/v1/files/456 \
-H "X-API-Key: hit_your_key_here"
Example Response
{
"message": "File deleted"
}
Toggle Share Link
Toggles the public share link for a file. If currently private, enables sharing and returns a public URL valid for duration_hours (capped by your plan). If currently public, calling this endpoint disables sharing.
Path Parameters
| Parameter | Type | Description |
|---|
file_id | integer | The ID of the file to toggle. Required |
Body Parameters (optional JSON)
| Field | Type | Description |
|---|
duration_hours | integer | How many hours the share link should remain active. Default 3. Capped by your plan's maximum. Optional |
Example (enable with 24-hour link)
curl -X POST https://hostedit.cloud/api/developer/v1/files/456/share \
-H "X-API-Key: hit_your_key_here" \
-H "Content-Type: application/json" \
-d '{"duration_hours": 24}'
Example Response (sharing enabled)
{
"id": 456,
"is_public": true,
"public_token": "a1b2c3d4-e5f6-...",
"public_expires_at": "2025-05-22T15:00:00",
"share_url": "https://hostedit.cloud/share/a1b2c3d4-e5f6-..."
}
Rate Limits
Each API key is subject to a per-second request limit based on your plan. Requests that exceed the limit receive a 429 Too Many Requests response with a Retry-After header indicating when you may retry.
| Plan | Requests / second | Downloads / day | Storage |
|---|
| Free / Starter | No API access | — | 2 GB / 120 GB |
| Pro | 10 req/s | 3,000 | 250 GB |
| Business | 30 req/s | 7,500 | 500 GB |
| Enterprise | 100 req/s | Unlimited | 1 TB |
Daily download limits apply to files served through the API and reset at midnight UTC. Exceeding them returns 429 until the reset.
Plan Access
API access is available on Pro and above. On the Free and Starter plans, API requests return 403 Forbidden.
Upgrade to Pro starting at $4.99/month to unlock API access, file embedding, and 250 GB of storage.