API Documentation

API Documentation

Integrate media uploads into your applications in minutes with our ready-to-use snippets.

1. Authentication

Authenticate your API requests using your API Key and Secret via headers or Bearer tokens.

# Headers format
X-Api-Key: md_live_xxxxxxxx
X-Api-Secret: your_secret_key

# Or Bearer token format
Authorization: Bearer md_live_xxxxxxxx:your_secret_key

2. Upload Endpoint

POST multipart file data to our upload endpoint to instantly store and register media.

POST https://mediadock.leslychuo.me/api/v1/upload
Content-Type: multipart/form-data

# Parameters
- file: (Binary file, max 500MB)
- bucket: (Optional slug string, defaults to key scope)

**Response JSON** – Returns metadata about the newly uploaded media:

{
    "id": "01m5fkcdx0dhn008kjdazjqh4v",
    "bucket_id": "01m5fkcdx0dhn008kjdazjqh4v",
    "filename": "01m5h4r78j88g6mwhabdaadyjm.png",
    "original_filename": "image.png",
    "url": "https://mediadock.leslychuo.me/m/dgcp1zazk/image/upload/assets/01m5h4r78j88g6mwhabdaadyjm.png",
    "mime_type": "image/png",
    "size": 124578,
    "status": "ready",
    "metadata": {
        "resource_type": "image",
        "folder": "assets"
    },
    "created_at": "2026-10-22T12:34:56Z"
}

**TypeScript Interface** – Use this shape in your client code:

interface UploadResponse {
    id: string;
    bucket_id: string;
    filename: string;
    original_filename: string;
    url: string; // full public URL
    mime_type: string;
    size: number;
    status: string;
    metadata: {
        resource_type: string;
        folder: string;
    };
    created_at: string; // ISO timestamp
}

cURL Snippet

curl -X POST https://mediadock.leslychuo.me/api/v1/upload \
  -H "X-Api-Key: md_live_..." \
  -H "X-Api-Secret: ..." \
  -F "file=@/path/to/video.mp4" \
  -F "bucket=my-bucket-slug"

PHP (Guzzle)

$client = new \GuzzleHttp\Client();
$response = $client->post('https://mediadock.leslychuo.me/api/v1/upload', [
    'headers' => [
        'X-Api-Key' => 'md_live_...',
        'X-Api-Secret' => '...',
    ],
    'multipart' => [
        ['name' => 'file', 'contents' => fopen('video.mp4', 'r')],
        ['name' => 'bucket', 'contents' => 'my-slug']
    ]
]);
$data = json_decode($response->getBody(), true);

Node.js (Fetch)

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('bucket', 'my-slug');

const res = await fetch('https://mediadock.leslychuo.me/api/v1/upload', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'md_live_...',
    'X-Api-Secret': '...'
  },
  body: formData
});
const json = await res.json();

TypeScript (Axios + Fetch)

// Axios Example
import axios from 'axios';
import FormData from 'form-data';
import fs from 'fs';

const formData = new FormData();
formData.append('file', fs.createReadStream('video.mp4'));
formData.append('bucket', 'my-slug');

const res = await axios.post('https://mediadock.leslychuo.me/api/v1/upload', formData, {
  headers: {
    'X-Api-Key': 'md_live_...',
    'X-Api-Secret': '...',
    ...formData.getHeaders()
  }
});
console.log(res.data);

// Native Fetch (TypeScript)
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('bucket', 'my-slug');

const res = await fetch('https://mediadock.leslychuo.me/api/v1/upload', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'md_live_...',
    'X-Api-Secret': '...'
  },
  body: formData
});
const json = await res.json();

3. Media URL Structure (Cloudinary-Style)

Uploaded files are accessible via clean, CDN-ready URLs using your bucket key:

https://mediadock.leslychuo.me/m/{bucketKey}/{resourceType}/upload/{folder}/{filename}
Example Image:
https://mediadock.leslychuo.me/m/dgcp1zazk/image/upload/assets/01m5h4r78j88g6mwhabdaadyjm.png
Example Video:
https://mediadock.leslychuo.me/m/dgcp1zazk/video/upload/products/summer/01m5h4r9w4eyzd8pngx73x0hhn.mp4

Resource Types: image | video | audio | raw (documents, archives)

4. Streaming Endpoint (Byte-Range Support)

Stream media with full HTTP range request support for seeking, adaptive bitrate, and progressive playback.

GET https://mediadock.leslychuo.me/api/v1/media/{id}/stream
# Response Headers
Accept-Ranges: bytes
Content-Type: video/mp4 (or audio/..., image/...)
Content-Length: 12345678

Works natively with HTML5 / tags and players like Video.js, HLS.js, Plyr.