---
title: Référence API
description: Documentation détaillée de tous les points de terminaison de l'API Memegoat.
---

## 📖 Référence API

Cette page documente tous les points de terminaison disponibles sur l'API Memegoat. L'URL de base de l'API est `https://api.memegoat.fr`.

<Callout type="info">
  L'authentification est gérée via des **cookies HttpOnly sécurisés** (`iron-session`). Les tokens ne sont pas exposés dans le corps des réponses après connexion pour une sécurité maximale.
</Callout>

### 🔐 Authentification (`/auth`)

<Accordions>
  <Accordion title="POST /auth/register">
    Inscrit un nouvel utilisateur.

    **Corps de la requête (JSON) :**
    - `username` (string) : Nom d'utilisateur unique.
    - `email` (string) : Adresse email valide.
    - `password` (string) : Mot de passe (min. 8 caractères).

    ```json
    {
      "username": "goat_user",
      "email": "user@memegoat.fr",
      "password": "strong-password"
    }
    ```
  </Accordion>

  <Accordion title="POST /auth/login">
    Authentifie un utilisateur et retourne les jetons de session. Si la 2FA est activée, retourne un indicateur.

    **Corps de la requête :**
    - `email` (string)
    - `password` (string)

    **Réponse (Succès) :**
    ```json
    {
      "message": "User logged in successfully",
      "userId": "uuid-v4"
    }
    ```
    *Note: L'access_token et le refresh_token sont stockés dans un cookie HttpOnly chiffré.*

    **Réponse (2FA requise) :**
    ```json
    {
      "message": "2FA required",
      "requires2FA": true,
      "userId": "uuid-v4"
    }
    ```
  </Accordion>

  <Accordion title="POST /auth/verify-2fa">
    Finalise la connexion si la 2FA est requise.

    **Corps de la requête :**
    - `userId` (uuid) : ID de l'utilisateur.
    - `token` (string) : Code TOTP à 6 chiffres.
  </Accordion>

  <Accordion title="POST /auth/refresh">
    Obtient un nouvel `access_token` à partir du `refresh_token` stocké dans la session.
    Met à jour automatiquement le cookie de session.
  </Accordion>

  <Accordion title="POST /auth/logout">
    Invalide la session actuelle.
  </Accordion>
</Accordions>

### 👤 Utilisateurs (`/users`)

<Accordions>
  <Accordion title="GET /users/me">
    Récupère les informations détaillées de l'utilisateur connecté. Requiert l'authentification.
  </Accordion>

  <Accordion title="GET /users/public/:username">
    Récupère le profil public d'un utilisateur par son nom d'utilisateur.
    **Réponse :** `id`, `username`, `displayName`, `avatarUrl`, `createdAt`.
  </Accordion>

  <Accordion title="GET /users/me/export">
    Extrait l'intégralité des données de l'utilisateur au format JSON (Conformité RGPD).
    Contient le profil, les contenus et les favoris.
  </Accordion>

  <Accordion title="PATCH /users/me">
    Met à jour les informations du profil.
    **Corps :**
    - `displayName` (string)
    - `bio` (string)
  </Accordion>

  <Accordion title="POST /users/me/avatar">
    Met à jour l'avatar de l'utilisateur.
    **Type :** `multipart/form-data`
    **Champ :** `file` (Image)
  </Accordion>

  <Accordion title="PATCH /users/me/consent">
    Met à jour les consentements légaux de l'utilisateur.
    **Corps :**
    - `termsVersion` (string)
    - `privacyVersion` (string)
  </Accordion>

  <Accordion title="DELETE /users/me">
    Marque le compte pour suppression (Soft Delete). 
    <Callout type="warn">
      Les données sont définitivement purgées après un délai légal de 30 jours.
    </Callout>
  </Accordion>

  <Accordion title="POST /users/me/2fa/setup">
    Génère un secret et un QR Code pour la configuration de la 2FA.
  </Accordion>

  <Accordion title="POST /users/me/2fa/enable">
    Active la 2FA après vérification du jeton TOTP.
  </Accordion>

  <Accordion title="POST /users/me/2fa/disable">
    Désactive la 2FA en utilisant un jeton TOTP valide.
  </Accordion>

  <Accordion title="GET /users/admin">
    Liste tous les utilisateurs (réservé aux administrateurs).
    **Query Params :** `limit`, `offset`.
  </Accordion>

  <Accordion title="DELETE /users/:uuid">
    Supprime définitivement un utilisateur par son UUID (réservé aux administrateurs).
  </Accordion>
</Accordions>

### 🖼️ Contenus (`/contents`)

<Accordions>
  <Accordion title="GET /contents/explore">
    Recherche et filtre les contenus. Cet endpoint est mis en cache.
    
    **Query Params :**
    - `limit` (number) : Défaut 10.
    - `offset` (number) : Défaut 0.
    - `sort` : `trend` | `recent`
    - `tag` (string) : Filtrer par tag.
    - `category` (slug ou id) : Filtrer par catégorie.
    - `author` (username) : Filtrer par auteur.
    - `query` (titre) : Recherche textuelle.
    - `favoritesOnly` (bool) : Ne montrer que les favoris de l'utilisateur connecté.
    - `userId` (uuid) : Filtrer les contenus d'un utilisateur spécifique.
  </Accordion>

  <Accordion title="GET /contents/trends">
    Récupère les contenus les plus populaires du moment.
  </Accordion>

  <Accordion title="GET /contents/recent">
    Récupère les contenus les plus récents.
  </Accordion>

  <Accordion title="GET /contents/:idOrSlug">
    Récupère un contenu par son ID ou son Slug.
    
    **Détection de Bots (SEO) :**
    Si l'User-Agent correspond à un robot d'indexation (Googlebot, Twitterbot, etc.), l'API retourne un rendu HTML minimal contenant les méta-tags **OpenGraph** et **Twitter Cards** pour un partage optimal. Pour les autres clients, les données sont retournées en JSON.
  </Accordion>

  <Accordion title="POST /contents">
    Crée une entrée de contenu (sans upload de fichier direct). Utile pour référencer des URLs externes.
    **Corps :** `title`, `description`, `url`, `type`, `categoryId`, `tags`.
  </Accordion>

  <Accordion title="POST /contents/upload">
    Upload un fichier avec traitement automatique par le serveur.
    **Type :** `multipart/form-data`

    **Champs :**
    - `file` (binary) : png, jpeg, webp, webm, gif.
    - `type` : `meme` | `gif`
    - `title` : string
    - `categoryId`? : uuid
    - `tags`? : string[]
  </Accordion>

  <Accordion title="POST /contents/upload-url">
    Génère une URL présignée pour un upload direct vers S3.
    **Query Param :** `fileName` (string).
  </Accordion>

  <Accordion title="POST /contents/:id/view">
    Incrémente le compteur de vues d'un contenu.
  </Accordion>

  <Accordion title="POST /contents/:id/use">
    Incrémente le compteur d'utilisation d'un contenu.
  </Accordion>

  <Accordion title="DELETE /contents/:id">
    Supprime un contenu (Soft Delete). Doit être l'auteur.
  </Accordion>

  <Accordion title="DELETE /contents/:id/admin">
    Supprime définitivement un contenu. **Réservé aux administrateurs.**
  </Accordion>
</Accordions>

### 📂 Catégories (`/categories`)

<Accordions>
  <Accordion title="GET /categories">
    Liste toutes les catégories de mèmes disponibles.
  </Accordion>

  <Accordion title="GET /categories/:id">
    Récupère les détails d'une catégorie spécifique.
  </Accordion>

  <Accordion title="POST /categories">
    Crée une nouvelle catégorie (**Admin uniquement**).
  </Accordion>

  <Accordion title="PATCH /categories/:id">
    Met à jour une catégorie existante (**Admin uniquement**).
  </Accordion>

  <Accordion title="DELETE /categories/:id">
    Supprime une catégorie (**Admin uniquement**).
  </Accordion>
</Accordions>

### ⭐ Favoris (`/favorites`)

<Accordions>
  <Accordion title="GET /favorites">
    Liste les favoris de l'utilisateur connecté.
    **Query Params :** `limit`, `offset`.
  </Accordion>

  <Accordion title="POST /favorites/:contentId">
    Ajoute un contenu aux favoris de l'utilisateur.
  </Accordion>

  <Accordion title="DELETE /favorites/:contentId">
    Retire un contenu des favoris de l'utilisateur.
  </Accordion>
</Accordions>

### 🚩 Signalements (`/reports`)

<Accordions>
  <Accordion title="POST /reports">
    Signale un contenu ou un tag inapproprié.
  </Accordion>

  <Accordion title="GET /reports">
    Liste tous les signalements (**Admin/Modérateurs uniquement**).
    **Query Params :** `limit`, `offset`.
  </Accordion>

  <Accordion title="PATCH /reports/:id/status">
    Change le statut d'un signalement (`pending`, `resolved`, `dismissed`) (**Admin/Modérateurs uniquement**).
  </Accordion>
</Accordions>

### 🔑 Clés API (`/api-keys`)

<Accordions>
  <Accordion title="POST /api-keys">
    Génère une nouvelle clé API pour l'utilisateur.
    **Corps :** `{ name, expiresAt? }`.
  </Accordion>

  <Accordion title="GET /api-keys">
    Liste toutes les clés API actives de l'utilisateur.
  </Accordion>

  <Accordion title="DELETE /api-keys/:id">
    Révoque une clé API spécifique.
  </Accordion>
</Accordions>

### 🏷️ Tags (`/tags`)

<Accordions>
  <Accordion title="GET /tags">
    Recherche et liste les tags populaires ou récents.
    **Query Params :** `query`, `sort` (`popular` | `recent`), `limit`, `offset`.
  </Accordion>
</Accordions>

### 🛠️ Système (`/health`)

<Accordions>
  <Accordion title="GET /health">
    Vérifie l'état de santé de l'API et de ses dépendances (Base de données, Redis, etc.).
  </Accordion>
</Accordions>

### 📁 Médias (`/media`)

<Accordions>
  <Accordion title="GET /media">
    Accès direct aux fichiers multimédias.
    **Query Param :** `path` (clé du fichier sur S3).
  </Accordion>
</Accordions>

### 📊 Administration (`/admin`)

<Accordions>
  <Accordion title="GET /admin/stats">
    Récupère les statistiques globales d'utilisation de la plateforme (**Admin uniquement**).
  </Accordion>
</Accordions>