---
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="Gestion 2FA">
    - `POST /users/me/2fa/setup` : Génère un secret et QR Code.
    - `POST /users/me/2fa/enable` : Active après vérification du jeton.
    - `POST /users/me/2fa/disable` : Désactive avec jeton.
  </Accordion>

  <Accordion title="Administration (Admin uniquement)">
    - `GET /users/admin` : Liste tous les utilisateurs (avec pagination `limit`, `offset`).
    - `DELETE /users/:uuid` : Supprime définitivement un utilisateur par son UUID.
  </Accordion>
</Accordions>

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

<Accordions>
  <Accordion title="GET /contents/explore | /trends | /recent">
    Recherche et filtre les contenus. Ces endpoints sont mis en cache (Redis + Navigateur).
    
    **Query Params :**
    - `limit` (number) : Défaut 10.
    - `offset` (number) : Défaut 0.
    - `sort` : `trend` | `recent` (uniquement sur `/explore`)
    - `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/: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 | /use">
    Incrémente les statistiques de vue ou d'utilisation.
  </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, ⭐ Favoris, 🚩 Signalements

<Accordions>
  <Accordion title="Catégories (/categories)">
    - `GET /categories` : Liste toutes les catégories.
    - `GET /categories/:id` : Détails d'une catégorie.
    - `POST /categories` : Création (Admin uniquement).
    - `PATCH /categories/:id` : Mise à jour (Admin uniquement).
    - `DELETE /categories/:id` : Suppression (Admin uniquement).
  </Accordion>

  <Accordion title="Favoris (/favorites)">
    Requiert l'authentification.
    - `GET /favorites` : Liste les favoris de l'utilisateur (avec pagination `limit`, `offset`).
    - `POST /favorites/:contentId` : Ajoute un favori.
    - `DELETE /favorites/:contentId` : Retire un favori.
  </Accordion>

  <Accordion title="Signalements (/reports)">
    - `POST /reports` : Signale un contenu ou un tag.
    - `GET /reports` : Liste des signalements (Pagination `limit`, `offset`). **Admin/Modérateurs**.
    - `PATCH /reports/:id/status` : Change le statut (`pending`, `resolved`, `dismissed`). **Admin/Modérateurs**.
  </Accordion>
</Accordions>

### 🔑 Clés API & 🏷️ Tags

<Accordions>
  <Accordion title="Clés API (/api-keys)">
    - `POST /api-keys` : Génère une clé `{ name, expiresAt? }`.
    - `GET /api-keys` : Liste les clés actives.
    - `DELETE /api-keys/:id` : Révoque une clé.
  </Accordion>

  <Accordion title="Tags (/tags)">
    - `GET /tags` : Recherche de tags.
    - **Params :** `query` (recherche), `sort` (`popular` | `recent`), `limit`, `offset`.
  </Accordion>
</Accordions>

### 🛠️ Système & Médias

<Accordions>
  <Accordion title="Santé (/health)">
    - `GET /health` : Vérifie l'état de l'API et de la connexion à la base de données.
  </Accordion>

  <Accordion title="Médias (/media)">
    - `GET /media/*key` : Accès direct aux fichiers stockés sur S3. Supporte la mise en cache agressive.
  </Accordion>

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