Documentation API v1 - Moustache AI

Tous les exemples utilisent des requêtes HTTP classiques. Les en-têtes et corps sont encodés en JSON UTF-8.

1. Authentification

Chaque requête doit contenir l’en-tête :

Authorization: Bearer <API_TOKEN_DE_LA_SOCIETE>

API_TOKEN_DE_LA_SOCIETE correspond au champ api_token de la table company. Si l’en-tête est manquant ou invalide, le serveur renvoie 401 Unauthorized.

2. Créer / mettre à jour un client

POST /api/v1/customers

Champ	Type	Obligatoire	Description
`companyIdentifier`	`string`	oui	Identifiant unique du client (propre à votre système).
`metadata`	`object` (JSON)	oui	Méta-données librement définies (nom, email, etc.). Toutes les clefs et valeurs doivent être des chaînes de caractères.

Réponses possibles

Code	Signification
200	Création ou mise à jour réussie (`{ success: "…" }`).
400	Paramètres manquants.
401	Token d’API invalide.
500	Erreur interne.

Exemple de requête

curl -X POST https://api.moustacheai.com/api/v1/customers \
  -H "Authorization: Bearer MON_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "companyIdentifier": "CLIENT_123",
        "metadata": {
          "email": "contact@client.fr",
          "nom": "Société Exemple"
        }
      }'

2bis. Récupérer un client

GET /api/v1/customers Permet de récupérer les informations d’un client existant à partir de son identifiant.

Paramètres de requête (query string)

Paramètre	Type	Obligatoire	Description
`companyIdentifier`	string	oui	Identifiant unique du client (même valeur que pour `POST /api/v1/customers`).

Réponses possibles

Code	Corps JSON
200	`{ "id": 1, "company_identifier": "CLIENT_123", "data": { "email": "...", "nom": "..." } }`
400	`{ "error": "Missing companyIdentifier query parameter" }`
401	`{ "error": "Unauthorized: Unknown token" }`
404	`{ "error": "Customer not found" }`
500	`{ "error": "Internal Server Error" }`

Exemple de requête

curl -X GET 'https://api.moustacheai.com/api/v1/customers?companyIdentifier=CLIENT_123' \
  -H "Authorization: Bearer MON_API_TOKEN"

Réponse :

{
  "id": 42,
  "company_identifier": "CLIENT_123",
  "data": {
    "email": "contact@client.fr",
    "nom": "Société Exemple"
  }
}

3. Envoyer une question à un agent

POST /api/v1/responses

Champ	Type	Obligatoire	Description
`companyIdentifier`	`string`	oui	Identifiant du client (même valeur que pour `/customers`).
`agentUUID`	`string`	oui	UUID de l’agent (assistant) qui doit répondre.
`question`	`string`	oui	Question de l’utilisateur final.
`stream`	`boolean`	non (def: true)	`true` → réponse en flux (SSE) ; `false` → réponse complète en une fois.
`files`	`array`	non	Images et documents joints à la question. Chaque élément : `{ "url": "...", "type": "image/png", "name": "optionnel" }`. Voir Fichiers joints ci-dessous.

Aucun uuid n’est requis : le serveur génère l’identifiant de la réponse et vous le renvoie (champ uuid en mode non stream, en-tête X-Moustache-Message-UUID en mode stream). Il sert à noter la réponse (section 3quater).

Fichiers joints

Type	Formats	Traitement
Images	PNG, JPG, GIF, WebP	Envoyées au modèle en entrée vision. L’agent doit utiliser un modèle vision avec la vision activée, sinon 403. `url` peut être une URL publique HTTPS ou un `data:` URL base64.
Documents	PDF, DOCX, PPTX, TXT, CSV, JSON (25 Mo max par fichier)	Le texte est extrait par Moustache AI puis ajouté à la question. Fonctionne avec tous les modèles. Un PDF scanné passe par une reconnaissance de texte (OCR) quand un modèle vision auxiliaire est configuré. Envoi en `data:` URL base64 ou en multipart uniquement : une URL distante est refusée (400).

Les fichiers peuvent être envoyés :

en JSON via files (data: URL base64, ou URL publique HTTPS pour les images) ;
en multipart/form-data via un champ files (un ou plusieurs fichiers).

Les fichiers joints sont conservés et retrouvés dans l’historique (section 3bis).

Réponses (mode stream)

200 OK : renvoie un flux texte text/html; charset=utf-8 dont chaque chunk est une partie de la réponse. Le flux se termine par le marqueur :EOS:.
Autres codes d’erreur : voir tableau ci-dessous.

Réponses (mode non stream)

Code	Corps JSON
200	`{ "uuid": "…", "message": "…", "buttons": [ "Option 1", "Option 2" ] }`
400	`{ "error": "Missing parameters" }`, ou document envoyé par URL distante, vide ou mal encodé
401	`{ "error": "Unauthorized: Unknown token" }`
403	`{ "error": "Image inputs require a vision-capable model …" }`
404	`{ "error": "Unauthorized: Assistant not found for your company" }`
413	Document de plus de 25 Mo
415	Type de fichier non pris en charge
422	Aucun texte n’a pu être extrait du document
500	`{ "error": "Answer not found" }` ou erreur interne.

Exemple : réponse complète (stream = false)

curl -X POST https://api.moustacheai.com/api/v1/responses \
  -H "Authorization: Bearer MON_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "companyIdentifier": "CLIENT_123",
        "agentUUID": "28ce3b2d-5791-4905-8d66-123456789abc",
        "question": "Quels sont vos horaires d\'ouverture ?",
        "stream": false
      }'

Réponse :

{
  "uuid": "9b2f6c1e-4a8d-4f3e-9c1a-2d5e7f8a9b0c",
  "message": "Nous sommes ouverts du lundi au vendredi de 9h à 18h.",
  "buttons": null
}

Exemple : question avec fichiers (stream = false)

curl -X POST https://api.moustacheai.com/api/v1/responses \
  -H "Authorization: Bearer MON_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "companyIdentifier": "CLIENT_123",
        "agentUUID": "28ce3b2d-5791-4905-8d66-123456789abc",
        "question": "Peux-tu décrire l’image ?",
        "stream": false,
        "files": [
          {
            "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
            "type": "image/jpeg",
            "name": "produit-1.jpg"
          }
        ]
      }'

Exemple : question sur un document PDF (multipart/form-data)

curl -X POST https://api.moustacheai.com/api/v1/responses \
  -H "Authorization: Bearer MON_API_TOKEN" \
  -F "companyIdentifier=CLIENT_123" \
  -F "agentUUID=28ce3b2d-5791-4905-8d66-123456789abc" \
  -F "question=Résume ce devis" \
  -F "stream=false" \
  -F "files=@/chemin/vers/devis.pdf;type=application/pdf"

Exemple : envoi multipart/form-data

curl -X POST https://api.moustacheai.com/api/v1/responses \
  -H "Authorization: Bearer MON_API_TOKEN" \
  -F "companyIdentifier=CLIENT_123" \
  -F "agentUUID=28ce3b2d-5791-4905-8d66-123456789abc" \
  -F "question=Peux-tu décrire l’image ?" \
  -F "stream=false" \
  -F "files=@/chemin/vers/produit-1.jpg"

Exemple : plusieurs fichiers (multipart/form-data)

curl -X POST https://api.moustacheai.com/api/v1/responses \
  -H "Authorization: Bearer MON_API_TOKEN" \
  -F "companyIdentifier=CLIENT_123" \
  -F "agentUUID=28ce3b2d-5791-4905-8d66-123456789abc" \
  -F "question=Compare ces deux images" \
  -F "stream=false" \
  -F "files=@/chemin/vers/produit-1.jpg" \
  -F "files=@/chemin/vers/produit-2.jpg"

Exemple : réponse en flux (stream = true)

curl -N -X POST https://api.moustacheai.com/api/v1/responses \
  -H "Authorization: Bearer MON_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "companyIdentifier": "CLIENT_123",
        "agentUUID": "28ce3b2d-5791-4905-8d66-123456789abc",
        "question": "Je souhaite prendre rendez-vous.",
        "stream": true
      }'

Le flux affiche progressivement la réponse puis se termine par :EOS:. L’identifiant de la réponse est dans l’en-tête X-Moustache-Message-UUID (affichez-le avec curl -i).

3bis. Récupérer l’historique d’une conversation

GET /api/v1/responses Permet de récupérer l’historique complet (questions/réponses) d’une conversation entre un client et un agent, au format JSON.

Paramètres de requête (query string)

Paramètre	Type	Obligatoire	Description
`companyIdentifier`	string	oui	Identifiant du client (même valeur que pour `/customers`).
`agentUUID`	string	oui	UUID de l’agent (assistant) dont on veut l’historique.

L’authentification se fait via le header :

Authorization: Bearer <API_TOKEN_DE_LA_SOCIETE>

Réponse

Code	Corps JSON
200	`{ "messages": [ { "uuid": "…", "message": "…", "buttons": ["Option 1"], "message_type": "Answer", "created_at": "…", "review": "up" }, ... ] }`
400	`{ "error": "Missing parameters" }`
401	`{ "error": "Unauthorized: Unknown token" }`
404	`{ "error": "Unauthorized: Assistant not found for your company" }` ou `Customer not found`
500	`{ "error": "Internal Server Error" }`

Chaque message du tableau contient :

uuid : identifiant du message (celui d’une réponse sert à la noter, section 3quater)
message : texte de la question ou réponse
buttons : tableau d’options (si présent)
message_type : “Question” ou “Answer”
created_at : date ISO
review (réponses uniquement) : "up", "down" ou null, que la note vienne de l’API ou du pouce du chatbot
attachments (questions uniquement) : fichiers joints à la question, chacun { "kind": "image" | "document", "name", "type", "size", "url" }. url est un lien de téléchargement temporaire (valable 1 heure) ; il vaut null si le fichier n’a pas pu être conservé. Rappelez l’historique pour obtenir des liens neufs.

Exemple de requête

curl -X GET 'https://api.moustacheai.com/api/v1/responses?companyIdentifier=CLIENT_123&agentUUID=28ce3b2d-5791-4905-8d66-123456789abc' \
  -H "Authorization: Bearer MON_API_TOKEN"

Réponse :

{
  "messages": [
    {
      "uuid": "5d0c9a2e-1f3b-4c7d-8e9f-0a1b2c3d4e5f",
      "message": "Que dit ce devis sur les délais ?",
      "message_type": "Question",
      "created_at": "2026-10-05T12:34:56.000Z",
      "attachments": [
        {
          "kind": "document",
          "name": "devis.pdf",
          "type": "application/pdf",
          "size": 48213,
          "url": "https://…/devis.pdf?X-Amz-Expires=3600&…"
        }
      ]
    },
    {
      "uuid": "9b2f6c1e-4a8d-4f3e-9c1a-2d5e7f8a9b0c",
      "message": "Le devis prévoit une livraison sous 3 semaines.",
      "buttons": null,
      "message_type": "Answer",
      "created_at": "2026-10-05T12:35:10.000Z",
      "review": null
    }
  ]
}

3quater. Noter une réponse

PUT /api/v1/responses/{uuid}/review Équivalent du pouce positif / négatif du chatbot. La note apparaît dans la console Moustache AI comme celles du chatbot, et dans le champ review de l’historique.

Champ	Type	Obligatoire	Description
`review`	`string`	oui	`"up"` (pouce positif), `"down"` (pouce négatif) ou `"none"` (retire la note).

{uuid} est l’identifiant de la réponse : champ uuid de la réponse non stream, en-tête X-Moustache-Message-UUID en mode stream, ou champ uuid d’un message Answer de l’historique.

Code	Corps JSON
200	`{ "uuid": "…", "review": "up" }` (`null` après `"none"`)
400	UUID invalide, ou `review` différent de `up`, `down`, `none`
401	`{ "error": "Provide Auth via Authorization with …" }`
404	`{ "error": "Answer not found" }` : la réponse n’existe pas ou n’appartient pas à vos agents

curl -X PUT https://api.moustacheai.com/api/v1/responses/9b2f6c1e-4a8d-4f3e-9c1a-2d5e7f8a9b0c/review \
  -H "Authorization: Bearer MON_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "review": "down" }'

3ter. Alimenter la base documentaire d’un agent

Ces points de terminaison permettent à une intégration externe (par exemple un workflow n8n) d’envoyer, lister et supprimer les documents d’un agent. L’API utilise automatiquement le RAG interne ou le Vector Store OpenAI/Azure configuré sur l’agent.

L’agent est désigné par son UUID dans l’URL. L’agentUUID doit appartenir à la société propriétaire du token.

POST — Ajouter (ou mettre à jour) un document

POST /api/v1/agents/{agentUUID}/rag-resources Envoi en multipart/form-data.

Champ	Type	Obligatoire	Description
`file`	fichier	oui	Le document. Types acceptés : TXT, MD, CSV, JSON, PDF, DOCX, PPTX, XLSX, MP3, WAV, MP4, SRT, VTT. Taille max : 500 Mo (configurable).
`externalId`	string	non	Pour le RAG interne, renvoyer le même `externalId` remplace la version précédente. Pour un Vector Store, le remplacement est automatique lorsqu’un fichier du même nom existe déjà.

ℹ️ Pour un agent OpenAI/Azure, le champ id retourné est l’identifiant du fichier du Vector Store. Il sert également à le supprimer avec la route DELETE.

Réponses possibles

Code	Corps JSON
201	`{ "id": 123, "external_id": "notion-page-42", "file_name": "guide.pdf", "file_type": "application/pdf", "file_size_bytes": 20480, "status": "PENDING", "chunk_count": null, "error_message": null, "created_at": "…", "updated_at": "…" }` (`id` est une chaîne pour un fichier Vector Store)
400	`{ "error": "No file provided" }` / type ou `externalId` invalide
401	`{ "error": "Provide Auth via Authorization with \"Bearer YOUR_MOUSTACHE_AI_API_TOKEN\"" }`
404	`{ "error": "Agent not found for your company" }`
409	`{ "error": "A concurrent upload for this externalId is in progress; retry shortly" }`
413	`{ "error": "File size exceeds the 500 MB limit" }`
422	Fournisseur actuel incompatible avec les documents
429	`{ "error": "Rate limit exceeded" }` (en-tête `Retry-After`)
500	`{ "error": "Failed to upload RAG resource" }`

Exemple

curl -X POST 'https://api.moustacheai.com/api/v1/agents/28ce3b2d-5791-4905-8d66-123456789abc/rag-resources' \
  -H "Authorization: Bearer MON_API_TOKEN" \
  -F "file=@guide.pdf" \
  -F "externalId=notion-page-42"

GET — Lister les documents et leur statut

GET /api/v1/agents/{agentUUID}/rag-resources Renvoie le tableau des documents de l’agent, depuis son RAG interne ou son Vector Store, triés du plus récent au plus ancien (résultats paginés). À utiliser pour suivre l’ingestion (status passe de PENDING → PROCESSING → READY, ou FAILED).

Paramètres de requête (query string)

Paramètre	Type	Obligatoire	Description
`externalId`	string	non	Ne renvoyer que le document portant cet identifiant externe.
`status`	string	non	Filtrer par statut : `PENDING`, `PROCESSING`, `READY` ou `FAILED`.
`limit`	integer	non	Taille de page. Défaut 100, plafonné à 200.
`offset`	integer	non	Décalage pour la pagination (défaut 0). Combinez avec `limit` pour parcourir tout.

curl -X GET 'https://api.moustacheai.com/api/v1/agents/28ce3b2d-5791-4905-8d66-123456789abc/rag-resources?externalId=notion-page-42' \
  -H "Authorization: Bearer MON_API_TOKEN"

Réponse :

[
  {
    "id": 123,
    "external_id": "notion-page-42",
    "file_name": "guide.pdf",
    "file_type": "application/pdf",
    "file_size_bytes": 20480,
    "status": "READY",
    "chunk_count": 18,
    "error_message": null,
    "created_at": "2026-06-18T09:00:00.000Z",
    "updated_at": "2026-06-18T09:01:12.000Z"
  }
]

DELETE — Supprimer un document par clé externe

DELETE /api/v1/agents/{agentUUID}/rag-resources/{externalId} Supprime le document (et ses vecteurs). Pour le RAG interne, utilisez son externalId. Pour un Vector Store, utilisez l’id de fichier retourné par POST ou GET.

Code	Signification
204	Supprimé (pas de corps).
401	Token d’API invalide.
404	`{ "error": "Resource not found" }` / agent inconnu.
500	`{ "error": "Failed to delete RAG resource" }`

curl -X DELETE 'https://api.moustacheai.com/api/v1/agents/28ce3b2d-5791-4905-8d66-123456789abc/rag-resources/notion-page-42' \
  -H "Authorization: Bearer MON_API_TOKEN"

4. Codes d’erreur communs

Code	Motif
400	Paramètre manquant ou invalide
401	En-tête `Authorization` absent / mauvais
404	Agent introuvable pour la société
413	Fichier trop volumineux
415	Type de fichier non pris en charge
422	Document sans texte exploitable
500	Erreur interne inattendue

5. Bonnes pratiques

Timeout côté client : pour le mode stream, coupez la connexion si aucun chunk n’est reçu depuis >20 s.
Réessais : en cas de 500 réessayez avec back-off exponentiel.
Sécurité : stockez l’API_TOKEN côté serveur uniquement.

6. Détails techniques du mode stream

Le mode streaming (stream: true, valeur par défaut) utilise un ReadableStream HTTP côté serveur.

Format

Content-Type : text/html; charset=utf-8
Chaque chunk contient un fragment de texte de la réponse de l’agent, encodé en UTF-8.
Le flux se termine par le marqueur :EOS: (End Of Stream).
Le timeout serveur est de 120 secondes (maxDuration). Si l’agent met plus longtemps à répondre, la connexion sera coupée.

Backpressure

Le serveur utilise le mécanisme pull() du ReadableStream : les chunks sont mis en file d’attente et envoyés dès que le client est prêt à les consommer. Si le client lit lentement, le serveur met les données en tampon.

Interruption

Si le client ferme la connexion (signal abort), le serveur interrompt la génération et pousse un message d’abandon dans le flux avant de le fermer.

Multipart/form-data

Le streaming fonctionne aussi avec un envoi multipart/form-data (pour joindre des fichiers). Les champs texte (companyIdentifier, agentUUID, question, stream) sont lus depuis le FormData, et les fichiers sont convertis en data: URL base64 avant d’être transmis à l’assistant.

​1. Authentification

​2. Créer / mettre à jour un client

​Réponses possibles

​Exemple de requête

​2bis. Récupérer un client

​Paramètres de requête (query string)

​Réponses possibles

​Exemple de requête

​3. Envoyer une question à un agent

​Fichiers joints

​Réponses (mode stream)

​Réponses (mode non stream)

​Exemple : réponse complète (stream = false)

​Exemple : question avec fichiers (stream = false)

​Exemple : question sur un document PDF (multipart/form-data)

​Exemple : envoi multipart/form-data

​Exemple : plusieurs fichiers (multipart/form-data)

​Exemple : réponse en flux (stream = true)

​3bis. Récupérer l’historique d’une conversation

​Paramètres de requête (query string)

​Réponse

​Exemple de requête

​3quater. Noter une réponse

​3ter. Alimenter la base documentaire d’un agent

​POST — Ajouter (ou mettre à jour) un document

​Réponses possibles

​Exemple

​GET — Lister les documents et leur statut

​Paramètres de requête (query string)

​DELETE — Supprimer un document par clé externe

​4. Codes d’erreur communs

​5. Bonnes pratiques

​6. Détails techniques du mode stream

​Format

​Backpressure

​Interruption

​Multipart/form-data

1. Authentification

2. Créer / mettre à jour un client

Réponses possibles

Exemple de requête

2bis. Récupérer un client

Paramètres de requête (query string)

Réponses possibles

Exemple de requête

3. Envoyer une question à un agent

Fichiers joints

Réponses (mode stream)

Réponses (mode non stream)

Exemple : réponse complète (stream = false)

Exemple : question avec fichiers (stream = false)

Exemple : question sur un document PDF (multipart/form-data)

Exemple : envoi multipart/form-data

Exemple : plusieurs fichiers (multipart/form-data)

Exemple : réponse en flux (stream = true)

3bis. Récupérer l’historique d’une conversation

Paramètres de requête (query string)

Réponse

Exemple de requête

3quater. Noter une réponse

3ter. Alimenter la base documentaire d’un agent

POST — Ajouter (ou mettre à jour) un document

Réponses possibles

Exemple

GET — Lister les documents et leur statut

Paramètres de requête (query string)

DELETE — Supprimer un document par clé externe

4. Codes d’erreur communs

5. Bonnes pratiques

6. Détails techniques du mode stream

Format

Backpressure

Interruption

Multipart/form-data