{"openapi":"3.1.0","info":{"title":"StressZero Intelligence API","version":"1.2.0","description":"API REST pour évaluer le risque de burnout entrepreneurial. Scoring multi-dimensionnel, analyse d'équipe, rapports détaillés, webhooks temps réel.\n\n**Disclaimer:** This API provides informational burnout risk scoring only. It is NOT a medical diagnosis tool. Always consult a qualified healthcare professional.","contact":{"email":"hello@stresszeroentrepreneur.fr","url":"https://stresszeroentrepreneur.fr/intelligence-api"},"license":{"name":"Proprietary"},"x-logo":{"url":"https://stresszeroentrepreneur.fr/og-image.jpg"}},"servers":[{"url":"https://stresszeroentrepreneur.fr","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Burnout Analysis","description":"Individual and team burnout scoring"},{"name":"Reports","description":"Detailed burnout reports with action plans"},{"name":"Webhooks","description":"Real-time event notifications"},{"name":"API Keys","description":"Self-serve API key management"},{"name":"System","description":"Health, status, and documentation"}],"paths":{"/api/v1/analyze-burnout":{"post":{"summary":"Analyse le risque de burnout individuel","description":"Score multi-dimensionnel (physique, émotionnel, efficacité) avec recommandations personnalisées et produit suggéré.","operationId":"analyzeBurnout","tags":["Burnout Analysis"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeBurnoutRequest"},"example":{"responses":[{"dimension":"physical","question_id":"sleep_quality","value":65,"weight":3},{"dimension":"physical","question_id":"energy_level","value":70,"weight":2},{"dimension":"emotional","question_id":"motivation","value":60,"weight":2},{"dimension":"emotional","question_id":"stress_level","value":75,"weight":3},{"dimension":"effectiveness","question_id":"productivity","value":55,"weight":2},{"dimension":"effectiveness","question_id":"focus","value":50,"weight":1}],"context":{"profession":"entrepreneur","hours_per_week":55},"options":{"language":"fr","include_recommendations":true,"include_dimensions":true}}}}},"responses":{"200":{"description":"Analyse réussie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeBurnoutResponse"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests in window"},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix timestamp when limit resets"}}},"401":{"description":"Clé API invalide ou manquante","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Erreur de validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Quota ou rate limit dépassé","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"summary":"Documentation endpoint analyze-burnout","operationId":"getAnalyzeBurnoutDocs","tags":["System"],"security":[],"responses":{"200":{"description":"Documentation de l'endpoint"}}}},"/api/v1/analyze-team":{"post":{"summary":"Analyse burnout d'équipe","description":"Analyse agrégée pour 2-500 membres avec distribution des risques, breakdown par département, alertes et recommandations. Chaque membre compte comme 1 appel API. Nécessite tier Starter+.","operationId":"analyzeTeam","tags":["Burnout Analysis"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeTeamRequest"},"example":{"team_name":"Startup Alpha","members":[{"member_id":"alice","responses":[{"dimension":"physical","question_id":"sleep","value":40,"weight":2},{"dimension":"emotional","question_id":"stress","value":55,"weight":2},{"dimension":"effectiveness","question_id":"focus","value":35,"weight":1}],"context":{"role":"CTO","department":"Engineering","hours_per_week":50}},{"member_id":"bob","responses":[{"dimension":"physical","question_id":"sleep","value":70,"weight":2},{"dimension":"emotional","question_id":"stress","value":80,"weight":2},{"dimension":"effectiveness","question_id":"focus","value":65,"weight":1}],"context":{"role":"Sales Lead","department":"Sales","hours_per_week":60}}],"options":{"anonymize":true,"include_distribution":true,"language":"fr"}}}}},"responses":{"200":{"description":"Analyse d'équipe réussie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeTeamResponse"}}}},"401":{"description":"Clé API invalide"},"403":{"description":"Tier insuffisant (nécessite starter+)"},"422":{"description":"Erreur de validation"},"429":{"description":"Quota ou rate limit dépassé"}}},"get":{"summary":"Documentation endpoint analyze-team","operationId":"getAnalyzeTeamDocs","tags":["System"],"security":[],"responses":{"200":{"description":"Documentation de l'endpoint"}}}},"/api/v1/generate-report":{"post":{"summary":"Génère un rapport burnout détaillé","description":"Rapport complet avec analyse par dimension, plan d'action (immédiat, court terme, long terme) et ressources. Nécessite tier Starter+.","operationId":"generateReport","tags":["Reports"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateReportRequest"},"example":{"responses":[{"dimension":"physical","question_id":"sleep","value":72,"weight":3},{"dimension":"emotional","question_id":"motivation","value":65,"weight":2},{"dimension":"effectiveness","question_id":"productivity","value":58,"weight":2}],"context":{"profession":"CEO","company_name":"TechCorp","hours_per_week":60,"years_experience":8},"format":"json","language":"fr"}}}},"responses":{"200":{"description":"Rapport généré","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResponse"}}}},"401":{"description":"Clé API invalide"},"403":{"description":"Tier insuffisant (nécessite starter+)"},"422":{"description":"Erreur de validation"}}},"get":{"summary":"Documentation endpoint generate-report","operationId":"getGenerateReportDocs","tags":["System"],"security":[],"responses":{"200":{"description":"Documentation de l'endpoint"}}}},"/api/v1/webhooks":{"post":{"summary":"Créer un webhook","description":"Abonnement à des événements temps réel (analyse complétée, alerte critique, quota, etc.). Les payloads sont signés HMAC-SHA256. Nécessite Starter+.","operationId":"createWebhook","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"},"example":{"url":"https://yourapp.com/webhooks/stresszero","events":["analysis.completed","analysis.critical_alert"]}}}},"responses":{"200":{"description":"Webhook créé — le secret est affiché une seule fois","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"secret":{"type":"string","description":"HMAC-SHA256 signing secret (shown once)"}}}}}}}},"403":{"description":"Tier insuffisant"},"422":{"description":"URL invalide ou événement inconnu"}}},"get":{"summary":"Lister vos webhooks","operationId":"listWebhooks","tags":["Webhooks"],"responses":{"200":{"description":"Liste des webhooks actifs"}}},"delete":{"summary":"Supprimer un webhook","operationId":"deleteWebhook","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["webhook_id"],"properties":{"webhook_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Webhook supprimé"},"404":{"description":"Webhook non trouvé"}}}},"/api/v1/keys":{"post":{"summary":"Créer une clé API (self-serve)","description":"Génère une clé API gratuite (100 appels/mois). Les tiers payants sont provisionnés automatiquement via Stripe.","operationId":"createApiKey","tags":["API Keys"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Email professionnel"},"name":{"type":"string","default":"Default","description":"Nom descriptif de la clé"}}},"example":{"email":"dev@startup.com","name":"Production App"}}}},"responses":{"200":{"description":"Clé API créée (affichée une seule fois)"},"409":{"description":"Une clé active existe déjà pour cet email"}}}},"/api/v1/health":{"get":{"summary":"Statut de l'API","description":"Vérifie la connectivité de tous les services (database, rate limiter) et retourne le statut global.","operationId":"getHealthStatus","tags":["System"],"security":[],"responses":{"200":{"description":"API opérationnelle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"Service indisponible"}}}},"/api/v1/openapi":{"get":{"summary":"Spécification OpenAPI 3.1","operationId":"getOpenApiSpec","tags":["System"],"security":[],"responses":{"200":{"description":"Spécification OpenAPI 3.1 JSON"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key au format `sz_live_...` (production) ou `sz_test_...` (sandbox). Les clés sandbox ne consomment pas de quota et ne nécessitent pas de DB.","bearerFormat":"sz_live_xxx / sz_test_xxx"}},"schemas":{"BurnoutResponseItem":{"type":"object","required":["dimension","question_id","value"],"properties":{"dimension":{"type":"string","enum":["physical","emotional","effectiveness"],"description":"Dimension du burnout évaluée"},"question_id":{"type":"string","minLength":1,"description":"Identifiant unique de la question"},"value":{"type":"number","minimum":0,"maximum":100,"description":"Score de 0 (aucun risque) à 100 (risque maximal)"},"weight":{"type":"number","minimum":1,"maximum":3,"default":1,"description":"Poids de la question (1=normal, 3=critique)"}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"message":{"type":"string"},"status":{"type":"integer"}}}}},"ValidationErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"message":{"type":"string","example":"Validation error"},"status":{"type":"integer","example":422},"errors":{"type":"array","items":{"type":"string"},"description":"Liste des erreurs de validation"}}}}},"AnalyzeBurnoutRequest":{"type":"object","required":["responses"],"properties":{"responses":{"type":"array","items":{"$ref":"#/components/schemas/BurnoutResponseItem"},"minItems":3,"maxItems":20},"context":{"type":"object","description":"Contexte professionnel pour affiner l'analyse","properties":{"profession":{"type":"string","maxLength":100},"hours_per_week":{"type":"number","minimum":0,"maximum":120},"team_size":{"type":"number","minimum":0,"maximum":1000},"years_experience":{"type":"number","minimum":0,"maximum":50}}},"options":{"type":"object","properties":{"include_recommendations":{"type":"boolean","default":true},"include_dimensions":{"type":"boolean","default":true},"language":{"type":"string","enum":["fr","en"],"default":"fr"}}}}},"AnalyzeBurnoutResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"score":{"type":"object","properties":{"total":{"type":"number","description":"Score global 0-100"},"dimensions":{"type":"object","properties":{"physical":{"type":"number"},"emotional":{"type":"number"},"effectiveness":{"type":"number"}}}}},"risk":{"type":"object","properties":{"level":{"type":"string","enum":["low","moderate","high","critical"]},"factors":{"type":"array","items":{"type":"string"},"description":"Facteurs de risque identifiés"},"urgency":{"type":"number","minimum":1,"maximum":10,"description":"Niveau d'urgence (1=faible, 10=critique)"}}},"recommendations":{"type":"array","items":{"type":"string"}},"suggested_product":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"}}},"disclaimer":{"type":"string"}}},"meta":{"type":"object","properties":{"api_version":{"type":"string"},"latency_ms":{"type":"number"},"quota":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"},"tier":{"type":"string"}}}}}}},"AnalyzeTeamRequest":{"type":"object","required":["members"],"properties":{"team_name":{"type":"string","maxLength":200},"members":{"type":"array","minItems":2,"maxItems":500,"items":{"type":"object","required":["responses"],"properties":{"member_id":{"type":"string","maxLength":100},"responses":{"type":"array","items":{"$ref":"#/components/schemas/BurnoutResponseItem"},"minItems":3,"maxItems":20},"context":{"type":"object","properties":{"role":{"type":"string","maxLength":100},"department":{"type":"string","maxLength":100},"hours_per_week":{"type":"number","minimum":0,"maximum":120}}}}}},"options":{"type":"object","properties":{"anonymize":{"type":"boolean","default":true,"description":"Anonymiser les member_id dans la réponse"},"include_distribution":{"type":"boolean","default":true},"include_department_breakdown":{"type":"boolean","default":true},"language":{"type":"string","enum":["fr","en"],"default":"fr"}}}}},"AnalyzeTeamResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"team":{"type":"object","properties":{"name":{"type":"string"},"size":{"type":"integer"},"avg_score":{"type":"number"},"min_score":{"type":"number"},"max_score":{"type":"number"},"std_deviation":{"type":"number"},"risk_level":{"type":"string","enum":["low","moderate","high","critical"]}}},"distribution":{"type":"object","properties":{"low":{"type":"integer"},"moderate":{"type":"integer"},"high":{"type":"integer"},"critical":{"type":"integer"}}},"department_breakdown":{"type":"object","additionalProperties":{"type":"object","properties":{"avg_score":{"type":"number"},"count":{"type":"integer"},"risk_distribution":{"type":"object"}}}},"alerts":{"type":"array","items":{"type":"string"}},"recommendations":{"type":"array","items":{"type":"string"}},"members":{"type":"array","items":{"type":"object","properties":{"member_id":{"type":"string"},"score":{"type":"number"},"risk_level":{"type":"string"},"dimensions":{"type":"object"}}}},"disclaimer":{"type":"string"}}}}},"GenerateReportRequest":{"type":"object","required":["responses"],"properties":{"responses":{"type":"array","items":{"$ref":"#/components/schemas/BurnoutResponseItem"}},"context":{"type":"object","properties":{"profession":{"type":"string"},"hours_per_week":{"type":"number"},"company_name":{"type":"string"},"employee_name":{"type":"string"},"years_experience":{"type":"number"}}},"format":{"type":"string","enum":["json","html"],"default":"json"},"language":{"type":"string","enum":["fr","en"],"default":"fr"}}},"ReportResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"report":{"type":"object","properties":{"title":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"subject":{"type":"string"},"company":{"type":"string"}}},"summary":{"type":"object","properties":{"total_score":{"type":"number"},"risk_level":{"type":"string"},"risk_label":{"type":"string"},"urgency":{"type":"number"},"one_liner":{"type":"string"}}},"dimensions":{"type":"object","description":"Analyse détaillée par dimension (physical, emotional, effectiveness) avec score, statut, interprétation et recommandations"},"action_plan":{"type":"object","properties":{"immediate":{"type":"array","items":{"type":"string"}},"short_term":{"type":"array","items":{"type":"string"}},"long_term":{"type":"array","items":{"type":"string"}}}},"resources":{"type":"object","description":"Liens vers coaching, kit, guide"}}}}},"CreateWebhookRequest":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","description":"URL HTTPS de destination"},"events":{"type":"array","items":{"type":"string","enum":["analysis.completed","analysis.critical_alert","quota.warning","quota.exceeded","key.expiring","team.report_ready"]},"minItems":1,"description":"Événements auxquels s'abonner"}}},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded","down"]},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"latency_ms":{"type":"number"},"checks":{"type":"object","properties":{"database":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded","down"]},"latency_ms":{"type":"number"}}},"rate_limiter":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}}}}},"x-sandbox":{"description":"Utilisez des clés préfixées sz_test_ pour le mode sandbox. Pas de base de données requise, pas de consommation de quota.","test_keys":{"sz_test_free":"Sandbox Free tier (10 req/min, 100/month)","sz_test_starter":"Sandbox Starter tier (30 req/min, 5K/month)","sz_test_pro":"Sandbox Pro tier (60 req/min, 25K/month)","sz_test_enterprise":"Sandbox Enterprise tier (120 req/min, 100K/month)"}},"x-pricing":{"free":{"price":"0€","quota":"100 calls/month","rate_limit":"10 req/min","features":["analyze-burnout"]},"starter":{"price":"29€/month","quota":"5,000 calls/month","rate_limit":"30 req/min","features":["analyze-burnout","generate-report","analyze-team","webhooks"]},"pro":{"price":"149€/month","quota":"25,000 calls/month","rate_limit":"60 req/min","features":["All Starter features","Priority support"]},"enterprise":{"price":"499€/month","quota":"100,000 calls/month","rate_limit":"120 req/min","features":["All Pro features","SLA guarantee","Dedicated support"]}}}