{"openapi":"3.1.0","info":{"title":"RevAI API","description":"\n## Churn Prediction & Lead Scoring API\n\n### Core Features\n- **Predict churn**: Send customer data, get churn risk scores + explanations\n- **Score leads**: Prioritize sales pipeline by conversion probability\n- **Train custom models**: Upload labeled data, get a company-specific XGBoost model\n- **Analyze calls**: Transcribe support/sales calls, detect churn intent signals\n\n### Authentication\nAll endpoints (except `/v1/health`) require an API key header:\n```\nX-API-Key: revai_live_...\n```\n\nGet your key by registering at `/v1/auth/register`.\n\n### Rate Limits\n| Tier    | Predictions/mo | Models | Req/min |\n|---------|---------------|--------|---------|\n| Free    | 100           | 0      | 10      |\n| Maker   | 5,000         | 3      | 100     |\n| Growth  | 50,000        | 10     | 500     |\n| Scale   | 500,000       | Unlim  | 2,000   |\n\n### Pricing\nVisit [RevAI on Payhip](https://payhip.com) to subscribe.\n    ","version":"1.0.0"},"paths":{"/_health":{"get":{"summary":"Root Health","operationId":"root_health__health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/":{"get":{"summary":"Root Health","operationId":"root_health__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/register":{"post":{"tags":["auth"],"summary":"Register","operationId":"register_v1_auth_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserRegister"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/login":{"post":{"tags":["auth"],"summary":"Login","operationId":"login_v1_auth_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLogin"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/keys":{"get":{"tags":["auth"],"summary":"List Api Keys","operationId":"list_api_keys_v1_auth_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/APIKeyResponse"},"type":"array","title":"Response List Api Keys V1 Auth Keys Get"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/predict/smart":{"post":{"tags":["Prediction"],"summary":"Predict Smart","description":"Universal connector — send rows with ANY column names. We auto-map them\nto RevAI's signals (and derive durations from dates), then score. The\nresponse includes a `field_mapping` report of what was matched/missed.","operationId":"predict_smart_v1_predict_smart_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartPredictInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/predict/csv":{"post":{"tags":["Prediction"],"summary":"Predict Csv","description":"Upload a CSV instead of hand-building JSON. One column per signal,\none row per customer/lead — we parse it and score every row.","operationId":"predict_csv_v1_predict_csv_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_predict_csv_v1_predict_csv_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/predict/churn":{"post":{"tags":["Prediction"],"summary":"Predict Churn","operationId":"predict_churn_v1_predict_churn_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/predict/lead":{"post":{"tags":["Prediction"],"summary":"Predict Lead","operationId":"predict_lead_v1_predict_lead_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/train":{"post":{"tags":["training"],"summary":"Train Model","operationId":"train_model_v1_train_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainingInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainingResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/models":{"get":{"tags":["training"],"summary":"List Models","operationId":"list_models_v1_models_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MLModelListResponse"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/models/{model_id}":{"get":{"tags":["training"],"summary":"Get Model","operationId":"get_model_v1_models__model_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"model_id","in":"path","required":true,"schema":{"type":"string","title":"Model Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MLModelResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["training"],"summary":"Delete Model","operationId":"delete_model_v1_models__model_id__delete","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"model_id","in":"path","required":true,"schema":{"type":"string","title":"Model Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/analyze/call":{"post":{"tags":["audio"],"summary":"Analyze Call Endpoint","operationId":"analyze_call_endpoint_v1_analyze_call_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_analyze_call_endpoint_v1_analyze_call_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallAnalysisResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/analyze/calls/batch":{"post":{"tags":["audio"],"summary":"Analyze Calls Batch","operationId":"analyze_calls_batch_v1_analyze_calls_batch_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_analyze_calls_batch_v1_analyze_calls_batch_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallAnalysisResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/benchmarks":{"get":{"tags":["benchmarks"],"summary":"Get Global Benchmarks","description":"Get global anonymized benchmarks. Minimum 3 companies required for privacy.","operationId":"get_global_benchmarks_v1_benchmarks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/usage":{"get":{"tags":["usage"],"summary":"Get Usage","operationId":"get_usage_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/health":{"get":{"tags":["usage"],"summary":"Health Check","operationId":"health_check_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/connect/stripe":{"post":{"tags":["connectors"],"summary":"Connect Stripe","description":"Paste a read-only Stripe key → we pull your recent customers, derive\nbilling-based churn signals (tenure, payment delays, subscription status,\ncontract type), and score them. The key is used in-memory and never stored.","operationId":"connect_stripe_v1_connect_stripe_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeConnectInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}}},"components":{"schemas":{"APIKeyResponse":{"properties":{"id":{"type":"string","title":"Id"},"prefix":{"type":"string","title":"Prefix"},"name":{"type":"string","title":"Name"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"}},"type":"object","required":["id","prefix","name","is_active","created_at"],"title":"APIKeyResponse"},"Body_analyze_call_endpoint_v1_analyze_call_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"},"openai_api_key":{"type":"string","title":"Openai Api Key"}},"type":"object","required":["file","openai_api_key"],"title":"Body_analyze_call_endpoint_v1_analyze_call_post"},"Body_analyze_calls_batch_v1_analyze_calls_batch_post":{"properties":{"files":{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array","title":"Files"},"openai_api_key":{"type":"string","title":"Openai Api Key"}},"type":"object","required":["files","openai_api_key"],"title":"Body_analyze_calls_batch_v1_analyze_calls_batch_post"},"Body_predict_csv_v1_predict_csv_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"CSV export of your customers/leads"},"model_type":{"type":"string","title":"Model Type","description":"'churn' or 'lead'","default":"churn"},"model_id":{"type":"string","title":"Model Id","description":"Optional trained model ID"}},"type":"object","required":["file"],"title":"Body_predict_csv_v1_predict_csv_post"},"CallAnalysisItem":{"properties":{"filename":{"type":"string","title":"Filename"},"transcript_snippet":{"type":"string","title":"Transcript Snippet"},"sentiment_score":{"type":"number","title":"Sentiment Score"},"sentiment_label":{"type":"string","title":"Sentiment Label"},"churn_intent_score":{"type":"number","title":"Churn Intent Score"},"flagged_keywords":{"items":{"type":"string"},"type":"array","title":"Flagged Keywords"},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds"}},"type":"object","required":["filename","transcript_snippet","sentiment_score","sentiment_label","churn_intent_score","flagged_keywords"],"title":"CallAnalysisItem"},"CallAnalysisResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/CallAnalysisItem"},"type":"array","title":"Results"},"summary":{"additionalProperties":true,"type":"object","title":"Summary"},"usage":{"additionalProperties":true,"type":"object","title":"Usage"}},"type":"object","required":["results","summary","usage"],"title":"CallAnalysisResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status","default":"ok"},"version":{"type":"string","title":"Version"},"uptime":{"type":"number","title":"Uptime"}},"type":"object","required":["version","uptime"],"title":"HealthResponse"},"MLModelListResponse":{"properties":{"models":{"items":{"$ref":"#/components/schemas/MLModelResponse"},"type":"array","title":"Models"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["models","total"],"title":"MLModelListResponse"},"MLModelResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"model_type":{"type":"string","title":"Model Type"},"n_features":{"type":"integer","title":"N Features"},"n_rows":{"type":"integer","title":"N Rows"},"metrics":{"additionalProperties":true,"type":"object","title":"Metrics"},"summary":{"additionalProperties":true,"type":"object","title":"Summary"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","name","model_type","n_features","n_rows","metrics","summary","created_at"],"title":"MLModelResponse"},"PredictionInput":{"properties":{"data":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":1000,"minItems":1,"title":"Data","example":[{"avg_session_minutes":8,"contract_type":"Month-to-Month","customer_id":"CUST-042","days_since_last_login":18,"feature_adoption_score":45,"login_frequency_7d":1,"monthly_spend_usd":99.0,"nps_score":3,"payment_delays_90d":2,"plan_tier":"Standard","support_tickets_last_30d":4,"tenure_days":45}]},"model_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Id","description":"Custom trained model ID for ML-based prediction"}},"type":"object","required":["data"],"title":"PredictionInput"},"PredictionResponse":{"properties":{"predictions":{"items":{"$ref":"#/components/schemas/SinglePrediction"},"type":"array","title":"Predictions"},"model_used":{"type":"string","title":"Model Used"},"usage":{"additionalProperties":true,"type":"object","title":"Usage"},"benchmark":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Benchmark"},"field_mapping":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Field Mapping"}},"type":"object","required":["predictions","model_used","usage"],"title":"PredictionResponse"},"RiskFactor":{"properties":{"rule":{"type":"string","title":"Rule"},"points":{"type":"integer","title":"Points"},"detail":{"type":"string","title":"Detail"}},"type":"object","required":["rule","points","detail"],"title":"RiskFactor"},"SinglePrediction":{"properties":{"index":{"type":"integer","title":"Index"},"score":{"type":"number","title":"Score"},"risk_level":{"type":"string","title":"Risk Level"},"recommended_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recommended Action"},"risk_factors":{"items":{"$ref":"#/components/schemas/RiskFactor"},"type":"array","title":"Risk Factors","default":[]},"scoring_mode":{"type":"string","title":"Scoring Mode"},"customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Id"},"input_fields":{"additionalProperties":true,"type":"object","title":"Input Fields","default":{}}},"type":"object","required":["index","score","risk_level","scoring_mode"],"title":"SinglePrediction"},"SmartPredictInput":{"properties":{"data":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":1000,"minItems":1,"title":"Data","description":"Your rows with WHATEVER column names you already have"},"mapping":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Mapping","description":"Optional {canonical_signal: your_column} overrides; auto-detected otherwise"},"model_type":{"type":"string","title":"Model Type","description":"'churn' or 'lead'","default":"churn"},"model_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Id","description":"Optional trained model ID"}},"type":"object","required":["data"],"title":"SmartPredictInput"},"StripeConnectInput":{"properties":{"stripe_key":{"type":"string","title":"Stripe Key","description":"Your restricted, read-only Stripe key (rk_live_… or sk_…)"},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"How many recent customers to score","default":100},"model_type":{"type":"string","title":"Model Type","description":"'churn' or 'lead'","default":"churn"},"model_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Id","description":"Optional trained model ID"}},"type":"object","required":["stripe_key"],"title":"StripeConnectInput"},"TokenResponse":{"properties":{"access_token":{"type":"string","title":"Access Token"},"token_type":{"type":"string","title":"Token Type","default":"bearer"},"user_id":{"type":"string","title":"User Id"},"email":{"type":"string","title":"Email"},"tier":{"type":"string","title":"Tier"},"api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},"type":"object","required":["access_token","user_id","email","tier"],"title":"TokenResponse"},"TrainingInput":{"properties":{"data":{"items":{"additionalProperties":true,"type":"object"},"type":"array","minItems":50,"title":"Data","example":[{"churned":1,"contract_type":"Monthly","login_frequency_7d":1,"nps_score":2,"payment_delays_90d":3,"tenure_days":30},{"churned":0,"contract_type":"Annual","login_frequency_7d":10,"nps_score":8,"payment_delays_90d":0,"tenure_days":400}]},"target_column":{"type":"string","title":"Target Column","description":"Column name containing 0/1 labels to predict","default":"churned"},"model_type":{"type":"string","title":"Model Type","description":"Model type: 'churn' or 'lead'","default":"churn"},"model_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Name","description":"Optional name for your trained model"}},"type":"object","required":["data"],"title":"TrainingInput"},"TrainingResponse":{"properties":{"model_id":{"type":"string","title":"Model Id"},"model_name":{"type":"string","title":"Model Name"},"model_type":{"type":"string","title":"Model Type"},"metrics":{"additionalProperties":true,"type":"object","title":"Metrics"},"summary":{"additionalProperties":true,"type":"object","title":"Summary"}},"type":"object","required":["model_id","model_name","model_type","metrics","summary"],"title":"TrainingResponse"},"UsageResponse":{"properties":{"tier":{"type":"string","title":"Tier"},"predictions_used":{"type":"integer","title":"Predictions Used"},"predictions_limit":{"type":"integer","title":"Predictions Limit"},"models_used":{"type":"integer","title":"Models Used"},"models_limit":{"type":"integer","title":"Models Limit"},"remaining_predictions":{"type":"integer","title":"Remaining Predictions"},"remaining_models":{"type":"integer","title":"Remaining Models"},"usage_by_endpoint":{"additionalProperties":{"type":"integer"},"type":"object","title":"Usage By Endpoint"}},"type":"object","required":["tier","predictions_used","predictions_limit","models_used","models_limit","remaining_predictions","remaining_models","usage_by_endpoint"],"title":"UsageResponse"},"UserLogin":{"properties":{"email":{"type":"string","title":"Email"},"password":{"type":"string","title":"Password"}},"type":"object","required":["email","password"],"title":"UserLogin"},"UserRegister":{"properties":{"email":{"type":"string","title":"Email"},"password":{"type":"string","minLength":8,"title":"Password"},"name":{"type":"string","title":"Name","default":""}},"type":"object","required":["email","password"],"title":"UserRegister"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"tags":[{"name":"Prediction","description":"Churn prediction and lead scoring endpoints"},{"name":"training","description":"Train custom XGBoost models on your labeled data"},{"name":"audio","description":"Analyze support/sales call recordings for churn intent signals"},{"name":"auth","description":"Register, login, and manage API keys"},{"name":"benchmarks","description":"Anonymized industry benchmark comparisons"},{"name":"usage","description":"Check usage, tier limits, and API health"}]}