FileMoon — FileMoon API-Dokumentation

FileMoon REST API

Einführung

Die FileMoon API ist eine JSON-basierte HTTP-API zur Automatisierung von Uploads, Verwaltung eigener Dateien und zum Import autorisierter direkter Video-URLs.

Basis-URL	`https://filemoon.org/api/v1`
Aktuelle Version	`v1`
Content-Type	`application/json` / `multipart/form-data`

Security: Verwenden Sie HTTPS. Veröffentlichen Sie private Token niemals in öffentlichem Code, Screenshots, Repositories oder Logs.

Erste Schritte

Authentifizierung

Senden Sie ein FileMoon-Zugriffstoken im Authorization-Header mit dem Bearer-Schema.

HTTP Headers

Authorization: Bearer YOUR_FILEMOON_TOKEN
Accept: application/json

Erstellen Sie das Token unter Benutzerbereich → API & Remote Upload. Es wird nur einmal vollständig angezeigt.

Token-Berechtigungen

files:readKonto, Dateien und Status lesen.

files:writeEigene Dateien hochladen, aktualisieren und löschen.

remote:writeRemote-Aufträge erstellen, abbrechen und erneut starten.

HTTP 429

Anfragelimits

Limits gelten pro Token und IP-Adresse. Das aktive Limit steht in den Antwort-Headern und beträgt höchstens 60 Anfragen pro Minute.

Response Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
Retry-After: 12
X-Request-ID: 2c7c4d7a-0e4d-4d92-bb53-e32f1e705dda

Warten Sie nach HTTP 429 die in Retry-After angegebene Zeit.

Erste Schritte

Kontoinformationen

Liefert Konto, Dateianzahl, Speicherverbrauch und Remote-Zähler.

GET /account

Parameter

Keine Anfrageparameter.

Beispielanfrage

cURL

curl -sS "https://filemoon.org/api/v1/account" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Beispielantwort

200 JSON

{
  "success": true,
  "data": {
    "id": "rk9zKY45m0lY",
    "username": "example_user",
    "email": "[email protected]",
    "status": true,
    "files": 20,
    "storage_bytes": 1846721934,
    "remote_jobs": {
      "pending": 0,
      "running": 0,
      "completed": 1,
      "failed": 0
    }
  }
}

Dateien

Dateien auflisten

Liefert eine paginierte Liste. search filtert nach Namen.

GET /files

Parameter

Feld	Typ	Erforderlich	Beschreibung
`search`	string	Optional	Filter by name or stored filename. Maximum 255 characters.
`page`	integer	Optional	Pagination page. Minimum 1.
`per_page`	integer	Optional	Results per page. Default 25, maximum 100.

Beispielanfrage

cURL

curl -sS "https://filemoon.org/api/v1/files?search=sample&per_page=25&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Beispielantwort

200 JSON

{
  "success": true,
  "data": [
    {
      "id": "0JgG7vRZzoYW",
      "name": "sample-video",
      "filename": "sample-video.mp4",
      "mime": "video/mp4",
      "extension": "mp4",
      "size_bytes": 1520849,
      "visibility": "public",
      "password_protected": false,
      "allow_online_watch": true,
      "downloads": 0,
      "stream_views": 0,
      "urls": {
        "page": "https://filemoon.org/0JgG7vRZzoYW/file",
        "watch": "https://filemoon.org/0JgG7vRZzoYW/watch",
        "embed": "https://filemoon.org/0JgG7vRZzoYW/embed"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 25,
    "total": 1
  }
}

Dateien

Dateiinformationen

Liefert eine eigene Datei anhand der öffentlichen FileMoon-ID.

GET /files/{id}

Parameter

Feld	Typ	Erforderlich	Beschreibung
`id`	string (path)	Ja	Public FileMoon file ID owned by the authenticated account.

Beispielanfrage

cURL

curl -sS "https://filemoon.org/api/v1/files/0JgG7vRZzoYW" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Dateien

Datei- und HLS-Status

Liefert Datei und HLS-Konvertierungsstatus.

GET /files/{id}/status

Parameter

Feld	Typ	Erforderlich	Beschreibung
`id`	string (path)	Ja	Public FileMoon file ID owned by the authenticated account.

Beispielanfrage

cURL

curl -sS "https://filemoon.org/api/v1/files/0JgG7vRZzoYW/status" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Beispielantwort

200 JSON

{
  "success": true,
  "data": {
    "file": {
      "id": "0JgG7vRZzoYW",
      "name": "sample-video",
      "allow_online_watch": true
    },
    "conversion": {
      "status": "completed",
      "stage": "adaptive",
      "attempts": 1,
      "duration_seconds": 42,
      "error": null,
      "updated_at": "2026-07-18 19:20:00"
    }
  }
}

Dateien

Lokale Datei hochladen

Laden Sie mit multipart/form-data hoch. file ist erforderlich; visibility akzeptiert 1 oder 0.

POST /files/upload

Parameter

Feld	Typ	Erforderlich	Beschreibung
`file`	binary	Ja	Local file attached as multipart/form-data.
`visibility`	boolean	Optional	Use 1 for public or 0 for private.

Beispielanfrage

cURL

curl -sS -X POST "https://filemoon.org/api/v1/files/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -F "file=@/path/to/video.mp4" \
  -F "visibility=1"

Dateien

Datei aktualisieren

Ändern Sie unterstützte Metadaten. Senden Sie nur zu ändernde Felder.

PATCH /files/{id}

Parameter

Feld	Typ	Erforderlich	Beschreibung
`id`	string (path)	Ja	Public FileMoon file ID.
`name`	string	Optional	New file name. Maximum 255 characters.
`description`	string\|null	Optional	File description. Maximum 1000 characters.
`visibility`	boolean	Optional	Public or private visibility.
`allow_online_watch`	boolean	Optional	Enable or disable online video watch.
`password`	string\|null	Optional	Set, change or remove the file password.

Beispielanfrage

cURL

curl -sS -X PATCH "https://filemoon.org/api/v1/files/0JgG7vRZzoYW" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated-video-name",
    "description": "Updated through FileMoon API",
    "visibility": true,
    "allow_online_watch": true
  }'

Dateien

Datei löschen

Löscht Datei und Daten dauerhaft. Nicht rückgängig zu machen.

DELETE /files/{id}

Parameter

Feld	Typ	Erforderlich	Beschreibung
`id`	string (path)	Ja	Public FileMoon file ID.

Beispielanfrage

cURL

curl -sS -X DELETE "https://filemoon.org/api/v1/files/0JgG7vRZzoYW" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Remote-Upload

Remote-Aufträge erstellen

Stellen Sie eine oder mehrere URLs in die Warteschlange. HTTP 202 bestätigt die Hintergrundverarbeitung.

Akzeptiert öffentliche direkte HTTP/HTTPS-Medien-URLs. Private Netze, localhost, Cloud-Metadaten, unsichere Weiterleitungen, Skripte und Nicht-Video-Antworten werden blockiert.

POST /remote-uploads

Parameter

Feld	Typ	Erforderlich	Beschreibung
`urls`	array<string>	Ja	One or more public direct HTTP/HTTPS media URLs.
`name`	string\|null	Optional	Custom file name. Maximum 240 characters.
`description`	string\|null	Optional	Description. Maximum 1000 characters.
`folder_id`	integer\|null	Optional	Folder ID owned by the authenticated user.
`visibility`	boolean	Optional	Public or private file.
`allow_online_watch`	boolean	Optional	Allow online video playback.
`password`	string\|null	Optional	Optional file password.
`blocked_countries`	array<string>	Optional	Two-letter country codes. Maximum 50 entries.

Beispielanfrage

cURL

curl -sS -X POST "https://filemoon.org/api/v1/remote-uploads" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://cdn.example.com/video.mp4"],
    "name": "remote-video",
    "description": "Imported through FileMoon API",
    "visibility": true,
    "allow_online_watch": true,
    "blocked_countries": ["US", "GB"]
  }'

Beispielantwort

202 JSON

{
  "success": true,
  "message": "Remote upload job(s) queued.",
  "data": [
    {
      "id": "d96f9d69-1d44-42eb-89e3-5a62b052e77d",
      "host": "cdn.example.com",
      "name": "remote-video",
      "status": "pending",
      "stage": "queued",
      "attempts": 0,
      "bytes_downloaded": 0,
      "bytes_total": null,
      "progress_percent": null,
      "error": null,
      "file_id": null
    }
  ]
}

Auftragsstatus

pendingrunningcompletedfailedcancelled

Remote-Upload

Remote-Aufträge auflisten

Liefert eine paginierte Liste der Remote-Aufträge.

GET /remote-uploads

Parameter

Feld	Typ	Erforderlich	Beschreibung
`page`	integer	Optional	Pagination page.
`per_page`	integer	Optional	Default 25, maximum 100.

Beispielanfrage

cURL

curl -sS "https://filemoon.org/api/v1/remote-uploads?per_page=25&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Remote-Upload

Remote-Auftragsstatus

Liefert Fortschritt, Phase, Fehler und die erstellte Datei-ID.

GET /remote-uploads/{id}

Parameter

Feld	Typ	Erforderlich	Beschreibung
`id`	UUID (path)	Ja	Remote-upload job ID.

Beispielanfrage

cURL

curl -sS "https://filemoon.org/api/v1/remote-uploads/d96f9d69-1d44-42eb-89e3-5a62b052e77d" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Beispielantwort

200 JSON

{
  "success": true,
  "data": {
    "id": "d96f9d69-1d44-42eb-89e3-5a62b052e77d",
    "host": "cdn.example.com",
    "name": "remote-video",
    "status": "completed",
    "stage": "completed",
    "attempts": 1,
    "bytes_downloaded": 1520849,
    "bytes_total": 1520849,
    "progress_percent": 100,
    "error": null,
    "file_id": "0JgG7vRZzoYW"
  }
}

Remote-Upload

Remote-Auftrag abbrechen

Bricht einen wartenden Auftrag ab oder fordert den Abbruch an.

POST /remote-uploads/{id}/cancel

Parameter

Feld	Typ	Erforderlich	Beschreibung
`id`	UUID (path)	Ja	Remote-upload job ID.

Beispielanfrage

cURL

curl -sS -X POST "https://filemoon.org/api/v1/remote-uploads/JOB_ID/cancel" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Remote-Upload

Remote-Auftrag wiederholen

Setzt einen fehlgeschlagenen oder abgebrochenen Auftrag zurück.

POST /remote-uploads/{id}/retry

Parameter

Feld	Typ	Erforderlich	Beschreibung
`id`	UUID (path)	Ja	Remote-upload job ID.

Beispielanfrage

cURL

curl -sS -X POST "https://filemoon.org/api/v1/remote-uploads/JOB_ID/retry" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

HTTP

Fehler und Statuscodes

Fehler verwenden eine einheitliche JSON-Struktur. Bewahren Sie request_id für Support auf.

401

UNAUTHENTICATED

Missing or invalid Bearer token.

403

TOKEN_DISABLED / TOKEN_EXPIRED

Token disabled, expired, IP blocked or missing permission.

404

NOT_FOUND

Owned file or remote job could not be found.

409

REMOTE_JOB_NOT_CANCELLABLE

The job can no longer be cancelled.

422

VALIDATION_ERROR

Request fields or uploaded file are invalid.

429

RATE_LIMITED

Too many requests. Use Retry-After.

503

API_DISABLED

The administrator temporarily disabled the API.

Beispielantwort

Error JSON

{
  "success": false,
  "error": {
    "code": "TOKEN_ABILITY_DENIED",
    "message": "The token does not have the required permission."
  },
  "request_id": "2c7c4d7a-0e4d-4d92-bb53-e32f1e705dda"
}

Referenz

Sicherheitsanforderungen

Beachten Sie diese Regeln bei der Integration.

Speichern Sie Token auf einem vertrauenswürdigen Server und widerrufen Sie offengelegte Token.

Vergeben Sie nur minimale Berechtigungen.

Beschränken Sie Token nach Möglichkeit auf vertrauenswürdige IPs oder CIDR.

Laden Sie nur eigene oder autorisierte Inhalte hoch.

cURL · PHP · JavaScript

Client-Beispiele

Minimale cURL-, PHP- und serverseitige JavaScript-Beispiele.

cURL

curl -sS "https://filemoon.org/api/v1/account" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

PHP 8+

<?php
$token = getenv('FILEMOON_API_TOKEN');

$ch = curl_init('https://filemoon.org/api/v1/account');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Accept: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$response = curl_exec($ch);
if ($response === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
if ($status >= 400) {
    throw new RuntimeException($data['error']['message'] ?? 'API request failed');
}
print_r($data);

Node.js / Server-side JS

const token = process.env.FILEMOON_API_TOKEN;

const response = await fetch('https://filemoon.org/api/v1/account', {
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: 'application/json'
  }
});

const data = await response.json();
if (!response.ok) {
  throw new Error(data?.error?.message || 'API request failed');
}
console.log(data);