Media files · OwnMediaHost Docs

Check the returned URL for your release.The platform README uses /a/… aliases and /private/… links; the API document uses /i/… and tokenized /f/… links. These supplied documents differ. Use the actual URL returned by your installed API instead of constructing it.

`GET /api/v1/files`

List media files with pagination and filtering.

Auth required: Yes

Parameter	Type	Default	Description
`limit`	integer	50	Max items (max 200)
`offset`	integer	0	Pagination offset
`type`	string	—	`"image"` or `"video"`
`folder_id`	string	—	Filter by folder UUID
`tag`	string	—	Filter by tag name
`search`	string	—	Full-text search on filename
`trash`	boolean	false	If true, return trashed files only
`sort`	string	`created_at`	Sort by: `created_at`, `file_size`, `filename`

bash

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.example.com/api/v1/files?limit=10&type=image&sort=file_size"

Response:

json

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "f_abc123",
        "public_id": "xK9mP2",
        "filename": "sunset-beach.jpg",
        "original_filename": "IMG_4521.jpg",
        "extension": "jpg",
        "mime_type": "image/jpeg",
        "media_type": "image",
        "file_size": 2458912,
        "width": 3840,
        "height": 2160,
        "sha256": "a1b2c3d4...",
        "visibility": "public",
        "url": "/f/xK9mP2",
        "thumbnail_url": "/thumbnails/xK9mP2.jpg",
        "tags": ["nature", "beach"],
        "aliases": ["/i/sunset"],
        "created_at": "2026-09-19T14:30:00Z",
        "updated_at": "2026-09-19T14:30:00Z"
      }
    ],
    "total": 142,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

`POST /api/v1/files`

Upload a media file via multipart/form-data.

Auth required: Yes

Field	Type	Required	Description
`file`	file	Yes	The image or video file
`folder_id`	string	No	Target folder UUID
`tags`	string	No	Comma-separated tags
`alias`	string	No	Vanity alias path
`visibility`	string	No	`"public"` or `"private"`
`thumbnail`	file	No	Client-generated thumbnail JPEG
`width`	integer	No	Video width (pixels)
`height`	integer	No	Video height (pixels)
`duration`	number	No	Video duration (seconds)

cURL:

bash

curl -X POST https://api.example.com/api/v1/files \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@./photo.jpg" \
  -F "tags=portfolio,hero" \
  -F "alias=hero-banner" \
  -F "visibility=public"

JavaScript:

javascript

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('tags', 'portfolio,hero');
formData.append('alias', 'hero-banner');

const response = await fetch('https://api.example.com/api/v1/files', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_KEY' },
  body: formData,
});

const { data } = await response.json();
console.log('Uploaded:', data.url);

Python:

python

import requests

url = "https://api.example.com/api/v1/files"
headers = {"X-API-Key": "YOUR_KEY"}

with open("photo.jpg", "rb") as f:
    files = {"file": ("photo.jpg", f, "image/jpeg")}
    data = {"tags": "portfolio,hero", "alias": "hero-banner"}
    response = requests.post(url, headers=headers, files=files, data=data)

result = response.json()
print("Uploaded:", result["data"]["url"])

`PATCH /api/v1/files/{id}`

Update file metadata. All fields optional.

Auth required: Yes

bash

curl -X PATCH https://api.example.com/api/v1/files/f_abc123 \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "renamed.jpg", "tags": ["updated"], "visibility": "private"}'

`PUT /api/v1/files/{id}/content`

Replace the binary content of an existing file (keeps the same ID, public ID, aliases).

Auth required: Yes

bash

curl -X PUT https://api.example.com/api/v1/files/f_abc123/content \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@./new-version.jpg"

`DELETE /api/v1/files/{id}`

Soft-delete a file (move to trash). Recoverable for 30 days.

Auth required: Yes

bash

curl -X DELETE https://api.example.com/api/v1/files/f_abc123 \
  -H "X-API-Key: YOUR_KEY"

`POST /api/v1/files/{id}/restore`

Restore a file from trash.

Auth required: Yes

bash

curl -X POST https://api.example.com/api/v1/files/f_abc123/restore \
  -H "X-API-Key: YOUR_KEY"

`DELETE /api/v1/files/{id}/permanent`

Permanently delete a file. This cannot be undone.

Auth required: Yes

bash

curl -X DELETE https://api.example.com/api/v1/files/f_abc123/permanent \
  -H "X-API-Key: YOUR_KEY"

`POST /api/v1/files/{id}/sign-private`

Generate a time-limited signed URL for a private file.

Auth required: Yes

bash

curl -X POST https://api.example.com/api/v1/files/f_abc123/sign-private \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_seconds": 3600}'

Response:

json

{
  "success": true,
  "data": {
    "url": "/f/xK9mP2?token=abc123...",
    "expires_at": "2026-09-19T16:30:00Z",
    "expires_seconds": 3600
  }
}

`POST /api/v1/files/bulk`

Perform bulk operations on multiple files.

Auth required: Yes

bash

curl -X POST https://api.example.com/api/v1/files/bulk \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["f_abc123", "f_def456"],
    "action": "move",
    "target_folder_id": "fld_xyz"
  }'

Supported actions: delete, restore, permanent_delete, move, visibility