Documentation API

Intégrez les capacités d'accords mets-vins de Be The Wine dans vos applications.

Authentification

Toutes les requêtes API doivent inclure votre clé API dans l'en-tête Authorization :

Authorization: Bearer btw_your_api_key_here

Obtenir votre clé API

Limitation des requêtes

Les requêtes API sont limitées à 1 000 par jour par clé API. Les informations de limite sont incluses dans les en-têtes de réponse.

Header	Description
X-RateLimit-Limit	Nombre maximum de requêtes autorisées par jour
X-RateLimit-Remaining	Requêtes restantes pour la journée
X-RateLimit-Reset	Horodatage Unix de la réinitialisation de la limite

POST /api/v1/analyze

Analysez un texte pour extraire les informations de vin ou de plat et les vecteurs sensoriels.

Corps de la requête

Paramètre	Type	Requis	Description
text	string	Oui	Le texte à analyser (description de plat ou de vin)
type	"wine" \| "plate"	Non	Forcer la détection du type : 'wine' ou 'plate'. Si omis, détection automatique.
locale	"en" \| "fr"	Non	Langue de la réponse : 'en' ou 'fr'. Par défaut : 'en'.

Exemple

curl -X POST https://bethe.wine/api/v1/analyze \
  -H "Authorization: Bearer btw_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Beef Bourguignon with mushrooms",
    "type": "plate",
    "locale": "en"
  }'

Réponse

{
  "success": true,
  "items": [
    {
      "type": "plate",
      "name": "Beef Bourguignon",
      "description": "Traditional French beef stew...",
      "vector": [0.8, 0.6, ...],
      "tags": ["french", "beef", "stew", "rich"]
    }
  ]
}

POST /api/v1/recommend

Obtenez des recommandations de vins pour un plat spécifique basées sur la correspondance sensorielle.

Corps de la requête

Paramètre	Type	Requis	Description
plate_id	string	Oui	L'ID du plat pour lequel obtenir des recommandations
project_id	string	Non	ID de projet optionnel pour filtrer les vins d'un projet spécifique
top_k	number	Non	Nombre de recommandations à retourner (par défaut : 5)

Exemple

curl -X POST https://bethe.wine/api/v1/recommend \
  -H "Authorization: Bearer btw_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "plate_id": "clxxxxxxxxxx",
    "top_k": 5
  }'

Réponse

{
  "success": true,
  "plate_id": "clxxxxxxxxxx",
  "plate_name": "Beef Bourguignon",
  "recommendations": [
    {
      "rank": 1,
      "wine_id": "clyyyyyyyyyy",
      "wine_name": "Burgundy Pinot Noir 2019",
      "score": 0.942,
      "explanation": "Excellent match..."
    },
    ...
  ],
  "personalized": true
}

Codes d'erreur

Code de statut	Description
200	Succès
400	Requête invalide - Paramètres invalides ou manquants
401	Non autorisé - Clé API invalide ou manquante
404	Non trouvé - Ressource non trouvée
429	Trop de requêtes - Limite de requêtes dépassée
500	Erreur serveur interne

Gérer les clés API