Documentation API v1

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	Fichiers (images) pour la vision. Chaque élément: `{ "url": "...", "type": "image/png", "name": "optionnel" }`. `url` peut être une URL publique HTTPS ou un `data:` URL base64.

Aucun uuid n’est requis : le serveur génère un identifiant de message unique. Si files est fourni, l’assistant doit utiliser un modèle vision (vision activée), sinon la requête échoue en 403. Les fichiers peuvent être envoyés :

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

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	`{ "message": "…", "buttons": [ "Option 1", "Option 2" ] }`
400	`{ "error": "Missing parameters" }`
401	`{ "error": "Unauthorized: Unknown token" }`
404	`{ "error": "Unauthorized: Assistant not found for your company" }`
403	`{ "error": "Image inputs require a vision-enabled model for this assistant" }`
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 :

{
  "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 : 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:.

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": [ { "message": "…", "buttons": ["Option 1"], "message_type": "Question", "created_at": "…" }, ... ] }`
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 :

message : texte de la question ou réponse
buttons : tableau d’options (si présent)
message_type : “Question” ou “Answer”
created_at : date ISO

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": [
    {
      "message": "Bonjour, comment puis-je vous aider ?",
      "buttons": null,
      "message_type": "Question",
      "created_at": "2024-06-07T12:34:56.000Z"
    },
    {
      "message": "Je souhaite prendre rendez-vous.",
      "buttons": null,
      "message_type": "Answer",
      "created_at": "2024-06-07T12:35:10.000Z"
    }
  ]
}

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é
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.

Pour commencer

Changelog

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

Réponses (mode stream)

Réponses (mode non stream)

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

Exemple : question avec fichiers (stream = false)

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

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

​Réponses (mode stream)

​Réponses (mode non stream)

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

​Exemple : question avec fichiers (stream = false)

​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

​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

Réponses (mode stream)

Réponses (mode non stream)

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

Exemple : question avec fichiers (stream = false)

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

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