MediaGrade SFTP Server API (2.0.0)

Endpoint de health check, ne nécessite pas d'authentification

Retourne la liste de tous les comptes SFTP. Peut être filtrée par une liste d'account IDs via le paramètre accountIds.

Crée un nouveau compte SFTP pour un compte MediaGrade. Le client est responsable de la génération du username et du password.

Retourne les informations détaillées d'un compte SFTP spécifique

Supprime définitivement un compte SFTP et tous ses fichiers. ⚠️ Attention : Cette opération est irréversible.

Change le mot de passe SFTP d'un compte. Le client doit fournir le nouveau mot de passe.

Modifie la limite de stockage d'un compte.

Active ou désactive l'accès SFTP d'un compte

Retourne la liste des fichiers et répertoires d'un compte avec pagination. Supporte le tri par nom, taille, date de création/modification.

Pattern presigned URL. Le client demande une URL S3 signée puis fait un PUT direct vers cette URL avec les bytes du fichier — aucun byte ne transite par l'API Gateway, ce qui contourne la limite 10 MB.

const { data } = await fetch('/api/files/{accountId}/upload-url', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Api-Key': apiKey },
  body: JSON.stringify({ fileName: 'photo.jpg', path: '/folder', contentType: 'image/jpeg' })
}).then(r => r.json());
await fetch(data.uploadUrl, { method: 'PUT', body: file, headers: { 'Content-Type': data.contentType } });

L'URL signée expire après 1 h. Une fois l'upload réussi, la Lambda file-sync est déclenchée par S3 et met à jour le listing du compte.

Pattern presigned URL. Retourne une URL S3 signée vers laquelle le client fait un GET pour récupérer les bytes directement, sans passer par l'API Gateway.

Pour un téléchargement multi-fichiers, voir download-batch qui construit un ZIP en arrière-plan.

Retourne un redirect HTTP 302 vers une URL S3 signée. Le client suit la redirection et télécharge directement depuis S3 ; aucun byte ne transite par l'API. Pas de support des requêtes Range côté API (S3 gère les Range sur l'URL signée).

Pour récupérer l'URL signée sans suivre la redirection, utiliser plutôt GET /api/files/{accountId}/download-url.

Pattern async job + polling propre au download-batch — antérieur au pattern unifié des delete/rename/move et donc légèrement différent : le statut se poll sur GET /api/files/{accountId}/download-batch/status/{jobId} (et non sur /api/jobs/{jobId}/status). Le résultat final est une URL signée S3 vers l'archive ZIP générée par un service Fargate.

Crée un nouveau répertoire

Pattern async job + polling. Retourne immédiatement 202 Accepted avec un jobId (préfixe dl-) et un statusUrl. Le client poll statusUrl jusqu'à un statut terminal.

Une retry avec le même Idempotency-Key renvoie le même jobId.

Sur status partial, errors[] liste les objets non-supprimés (avec leur motif S3) — le client peut proposer un retry ciblé.

Pattern async job + polling. Pour un fichier seul, l'opération est rapide (~1 s perçu). Pour un dossier contenant beaucoup de fichiers, le worker copie chaque objet S3 puis supprime — peut prendre plusieurs secondes selon le volume.

Une retry avec le même Idempotency-Key renvoie le même jobId (préfixe rn-).

Pattern async job + polling. Chaque source peut être un fichier ou un dossier; le worker copie sous destination/basename(source) puis supprime l'original. Préfixe du jobId : mv-.

Pattern async job + polling. Réconcilie la table file_storage avec le contenu réel S3 dans le scope demandé : insert/update des fichiers présents en S3, suppression des rows orphelines (fichiers ou dossiers qui n'existent plus en S3), borné au sous-arbre spécifié.

• Sans path → resync complet du compte. Le worker recalcule used_bytes à la fin.
• Avec path → resync limité au sous-arbre. used_bytes n'est pas recalculé (les events S3 + file-sync le maintiennent à jour pendant le fonctionnement normal).

Préfixe du jobId : rf-. Le worker utilise des opérations bulk SQL (jsonb_to_recordset + DELETE … NOT EXISTS) pour rester rapide quel que soit le volume — un compte de 50 K fichiers passe en quelques secondes côté worker.

Cas d'usage typique côté browser : appeler avec path: "<dossier courant>" à chaque clic refresh, pour ne resync que la vue affichée (~10 fois plus rapide que le refresh global).

Pattern sync direct. Recherche par sous-chaîne (ILIKE) sur file_name, optionnellement scopée à un dossier. Le résultat est paginé via limit / offset.

Le terme de recherche q doit faire au moins 2 caractères.

Retourne l'état courant d'un job. Le préfixe du jobId (dl-, rn-, mv-, rf-) identifie la table sous-jacente — le client n'a pas à s'en préoccuper.

Pour un job refresh, la réponse inclut en plus data.scopePath (chemin du sous-arbre resync ou null si compte complet), data.syncedCount (fichiers upserted) et data.removedCount (orphelins supprimés).

Cadence de polling recommandée : 500 ms initial, backoff exponentiel plafonné à 5 s. La progression est mise à jour côté worker toutes les 50 items ou 1 s, donc poller plus vite n'apporte rien.

const url = `/api/jobs/${jobId}/status`;
let delay = 500;
while (true) {
  const r = await fetch(url, { headers: { 'X-Api-Key': apiKey } });
  const { data } = await r.json();
  updateProgressBar(data.progress.percent);
  if (['completed', 'partial', 'error'].includes(data.status)) return data;
  await new Promise(r => setTimeout(r, delay));
  delay = Math.min(delay * 2, 5000);
}

Retourne les statistiques globales du serveur SFTP

Retourne le nom du service, sa version, l'environnement et l'architecture courante.