{"components":{"responses":{"RateLimited":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Rate limit exceeded"},"Unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"API key missing or invalid"}},"schemas":{"Error":{"properties":{"detail":{"type":"string"},"error":{"type":"string"},"hint":{"type":"string"}},"type":"object"},"ScoreInput":{"properties":{"artist_primary":{"example":"Anitta","type":"string"},"audio_path":{"type":"string"},"featured_artists":{"items":{"type":"string"},"type":"array"},"genre":{"example":"pop latino","type":"string"},"isrc":{"example":"BR-RGE-22-00001","type":"string"},"language":{"enum":["pt-BR","pt-PT","en","es","fr","it","ko"],"type":"string"},"lyrics":{"type":"string"},"release_date":{"format":"date","type":"string"},"title":{"example":"Envolver","type":"string"}},"required":["title","artist_primary"],"type":"object"},"ScoreOutput":{"properties":{"analysis_url":{"type":"string"},"category":{"enum":["HIGH_POTENTIAL","WATCH","NEUTRAL","LOW","DEAD_WEIGHT"],"type":"string"},"confidence":{"enum":["low","medium","high"],"type":"string"},"horizon_30d":{"maximum":1,"minimum":0,"type":"number"},"horizon_90d":{"maximum":1,"minimum":0,"type":"number"},"ml_meta":{"description":"FASE 9.1 \u2014 meta-info do modelo (vers\u00e3o, calibra\u00e7\u00e3o, pipeline)","nullable":true,"properties":{"ml_calibration":{"enum":["platt","isotonic","none",null],"nullable":true,"type":"string"},"ml_pipeline_used":{"nullable":true,"type":"boolean"},"ml_prob":{"nullable":true,"type":"number"},"ml_raw_prob":{"description":"Probabilidade pr\u00e9-calibra\u00e7\u00e3o","nullable":true,"type":"number"},"ml_score":{"nullable":true,"type":"integer"},"ml_version":{"example":"v1.0.2","nullable":true,"type":"string"},"model_path":{"nullable":true,"type":"string"}},"type":"object"},"ml_prob":{"nullable":true,"type":"number"},"ml_score":{"description":"LightGBM model output (paralelo ao heur\u00edstico)","nullable":true,"type":"integer"},"score":{"maximum":100,"minimum":0,"type":"integer"},"scorer_version":{"example":"vega-engine-3layer","type":"string"},"sub_scores":{"properties":{"audio_similarity":{"type":"integer"},"streaming_potential":{"type":"integer"},"tiktok_potential":{"type":"integer"}},"type":"object"},"track_id":{"example":"tr_abc123","type":"string"},"trend":{"enum":["rising","stable","falling"],"type":"string"}},"type":"object"},"Webhook":{"properties":{"active":{"enum":[0,1],"type":"integer"},"created_at":{"format":"date-time","type":"string"},"events":{"example":"high_potential","type":"string"},"last_delivered_at":{"format":"date-time","nullable":true,"type":"string"},"n_delivered":{"type":"integer"},"n_failed":{"type":"integer"},"url":{"format":"uri","type":"string"},"webhook_id":{"type":"string"}},"type":"object"}},"securitySchemes":{"BasicAuth":{"description":"HTTP Basic Auth (admin endpoints)","scheme":"basic","type":"http"},"BearerAuth":{"bearerFormat":"API_KEY","description":"Bearer token (lu_live_xxx or lu_test_xxx)","scheme":"bearer","type":"http"}}},"info":{"contact":{"email":"suporte@vegaindex.app.br","name":"ART Produ\u00e7\u00f5es","url":"https://www.vegaindex.app.br"},"description":"Predictive viral inference engine pra m\u00fasica brasileira.\n\n**Score endpoint** retorna preditividade 0-100 com horizontes 30d/90d + 3 camadas (heur\u00edstica + absor\u00e7\u00e3o + similaridade).\n\n**Webhooks** notificam quando score >= 80 (HIGH_POTENTIAL).\n\nTier: starter (free 1k/m\u00eas) \u2192 growth ($99/m\u00eas) \u2192 scale ($499/m\u00eas).","termsOfService":"https://www.vegaindex.app.br/docs","title":"VEGA INDEX API","version":"1.0.0"},"openapi":"3.0.3","paths":{"/admin/audit/export.csv":{"get":{"description":"Mesmos filtros do /admin/audit. Default 30 dias. Max 100000 rows. \u00datil pra LGPD audit response.","parameters":[{"in":"query","name":"since","schema":{"format":"date-time","type":"string"}},{"in":"query","name":"action_prefix","schema":{"type":"string"}},{"in":"query","name":"actor_id","schema":{"type":"string"}},{"in":"query","name":"max_rows","schema":{"default":10000,"maximum":100000,"type":"integer"}}],"responses":{"200":{"content":{"text/csv":{"schema":{"type":"string"}}},"description":"CSV file (text/csv)"},"401":{"description":"Basic auth required"}},"summary":"Export audit log filtered como CSV (compliance/SOC2)","tags":["admin"]}},"/admin/models":{"get":{"description":"Admin endpoint, HTTP Basic Auth.","parameters":[{"in":"query","name":"limit","schema":{"default":50,"maximum":200,"type":"integer"}}],"responses":{"200":{"description":"Lista versions + production/previous"},"401":{"description":"Admin auth required"}},"summary":"Lista todas versions registradas no model registry","tags":["admin"]}},"/admin/models/compare":{"get":{"parameters":[{"in":"query","name":"from","required":true,"schema":{"type":"string"}},{"in":"query","name":"to","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"auc_delta, brier_delta, recommendation"},"400":{"description":"missing_versions"},"404":{"description":"version_not_found"}},"summary":"Diff metrics entre 2 versions + recommendation","tags":["admin"]}},"/admin/models/production":{"get":{"responses":{"200":{"description":"Production entry com size + exists flags"},"404":{"description":"No production model registered"}},"summary":"Entry da current production model","tags":["admin"]}},"/admin/models/rollback":{"post":{"responses":{"200":{"description":"Rolled back"},"409":{"description":"No previous version available"}},"summary":"Swap production \u2194 previous","tags":["admin"]}},"/admin/models/{version}":{"get":{"parameters":[{"in":"path","name":"version","required":true,"schema":{"example":"v1.0.2","type":"string"}}],"responses":{"200":{"description":"Version entry"},"404":{"description":"Version not found"}},"summary":"Detalhes de uma vers\u00e3o espec\u00edfica","tags":["admin"]}},"/admin/models/{version}/promote":{"post":{"parameters":[{"in":"path","name":"version","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Promoted (ou no-op se j\u00e1 era prod)"},"404":{"description":"Version not found"}},"summary":"Promote vers\u00e3o pra production (idempotente)","tags":["admin"]}},"/customer/health":{"get":{"description":"Snapshot do estado da pr\u00f3pria conta. Inclui quota usage, latency percentiles 24h, error rate, webhook delivery success rate. **Bypass quota check** \u2014 vis\u00edvel mesmo se quota_used \u2265 quota_monthly (customer precisa saber que t\u00e1 no cap).\n\n`health_score` \u00e9 classifica\u00e7\u00e3o overall: `good` (default) / `degraded` (quota \u2265 90% OU error_rate \u2265 5% OU p95 > 2000ms) / `critical` (quota = 100% OU error_rate \u2265 20%).","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"customer_id":{"type":"string"},"errors":{"type":"object"},"health_score":{"enum":["good","degraded","critical"],"type":"string"},"performance":{"type":"object"},"quota":{"type":"object"},"recent_activity":{"type":"object"},"ts_utc":{"format":"date-time","type":"string"},"webhooks":{"type":"object"}},"type":"object"}}},"description":"Customer health snapshot"},"401":{"description":"Auth required"}},"summary":"Per-customer SLA snapshot (quota, latency, errors)","tags":["customer"]}},"/drift":{"get":{"responses":{"200":{"description":"Snapshot"},"404":{"description":"Sem snapshots"}},"summary":"Snapshot atual do drift monitor","tags":["drift"]}},"/healthz":{"get":{"parameters":[{"description":"deep=1 retorna checks DB/ML/drift/SIGMA/webhooks/encoders/email","in":"query","name":"deep","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"status":{"enum":["ok","degraded"],"type":"string"}},"type":"object"}}},"description":"Service healthy"}},"summary":"Healthcheck (sub-second)","tags":["health"]}},"/keys/rotate":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"grace_period_minutes":{"default":60,"maximum":1440,"minimum":0,"type":"integer"}},"type":"object"}}}},"responses":{"201":{"description":"Nova key + revoga atual com grace"}},"security":[{"BearerAuth":[]}],"summary":"Rotaciona API key (grace period default 60min)","tags":["keys"]}},"/metrics":{"get":{"description":"Scraping endpoint pra Prometheus/Datadog/Grafana. Sem auth.","responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Text/plain v0.0.4 format com counters + gauges"}},"summary":"Prometheus text exposition format","tags":["observability"]}},"/score":{"post":{"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ScoreInput"},{"properties":{"tracks":{"items":{"$ref":"#/components/schemas/ScoreInput"},"type":"array"}},"type":"object"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"items":{"$ref":"#/components/schemas/ScoreOutput"},"type":"array"}},"type":"object"}}},"description":"Score(s) computed"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"summary":"Score uma ou m\u00faltiplas tracks","tags":["score"]}},"/score/feedback":{"get":{"responses":{"200":{"description":"Stats"}},"summary":"Agregados (sem PII)","tags":["feedback"]},"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"metric_value":{"type":"number"},"observation_date":{"format":"date","type":"string"},"outcome":{"enum":["viralized","flopped","catalog_hit","unknown"],"type":"string"},"track_id":{"type":"string"}},"required":["observation_date","outcome"],"type":"object"}}},"required":true},"responses":{"201":{"description":"Created"}},"summary":"Reporta outcome real (gold label)","tags":["feedback"]}},"/score/history":{"get":{"parameters":[{"in":"query","name":"since","schema":{"format":"date","type":"string"}},{"in":"query","name":"category","schema":{"enum":["HIGH_POTENTIAL","WATCH","NEUTRAL","LOW","DEAD_WEIGHT"],"type":"string"}},{"in":"query","name":"min_score","schema":{"type":"integer"}},{"in":"query","name":"limit","schema":{"default":50,"maximum":200,"type":"integer"}},{"in":"query","name":"cursor","schema":{"type":"string"}},{"in":"query","name":"order","schema":{"enum":["date","score"],"type":"string"}}],"responses":{"200":{"description":"Lista paginada"}},"summary":"Hist\u00f3rico com cursor pagination","tags":["score"]}},"/score/history.csv":{"get":{"parameters":[{"in":"query","name":"since","schema":{"format":"date","type":"string"}},{"in":"query","name":"limit","schema":{"default":1000,"maximum":10000,"type":"integer"}}],"responses":{"200":{"content":{"text/csv":{}},"description":"CSV streaming"}},"summary":"Export CSV (Excel/Sheets)","tags":["score"]}},"/score/public":{"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreInput"}}},"required":true},"responses":{"200":{"description":"Score com track_id ephemeral pub_*"},"413":{"description":"Mais que 3 tracks (signup pra mais)"}},"summary":"Demo p\u00fablico (sem auth, max 3 tracks)","tags":["score"]}},"/score/{track_id}":{"get":{"parameters":[{"in":"path","name":"track_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Score details"},"404":{"description":"Track not found"}},"security":[{"BearerAuth":[]}],"summary":"Detalhe de scoring job","tags":["score"]}},"/score/{track_id}/audit":{"get":{"description":"Lista scoring_jobs history + webhook deliveries triggered + feedback submissions. Ownership check via tracks.customer_id.","parameters":[{"in":"path","name":"track_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{track_id, scoring_jobs, webhook_deliveries, feedback}"},"403":{"description":"Track pertence a outro customer"},"404":{"description":"Track not found"}},"security":[{"BearerAuth":[]}],"summary":"Customer-visible audit trail pra uma track","tags":["scoring"]}},"/score/{track_id}/pdf":{"get":{"parameters":[{"in":"path","name":"track_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/pdf":{}},"description":"PDF binary"},"404":{"description":"Track ephemeral or not scored"}},"summary":"PDF report (branded)","tags":["score"]}},"/search":{"get":{"parameters":[{"in":"query","name":"q","required":true,"schema":{"minLength":2,"type":"string"}},{"in":"query","name":"limit","schema":{"default":10,"maximum":50,"type":"integer"}},{"in":"query","name":"min_chart_position","schema":{"type":"integer"}}],"responses":{"200":{"description":"Lista de matches"}},"summary":"Autocomplete artist+title em chart_snapshots","tags":["search"]}},"/usage":{"get":{"responses":{"200":{"description":"{plan, quota_used, quota_remaining, score_distribution}"}},"security":[{"BearerAuth":[]}],"summary":"Quota atual + score distribution","tags":["usage"]}},"/usage/history":{"get":{"description":"Trend de uso pra mostrar no dashboard. Inclui n_scores/n_high/n_watch/n_low/n_failed por dia.","parameters":[{"in":"query","name":"days","required":false,"schema":{"default":30,"maximum":365,"minimum":1,"type":"integer"}}],"responses":{"200":{"description":"{days, from_date, to_date, history[], totals}"}},"security":[{"BearerAuth":[]}],"summary":"Agregados di\u00e1rios \u00faltimos N dias (default 30, max 365)","tags":["usage"]}},"/webhooks":{"get":{"responses":{"200":{"description":"Lista (sem secret)"}},"security":[{"BearerAuth":[]}],"summary":"Lista webhooks do customer","tags":["webhooks"]},"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"events":{"items":{"enum":["high_potential","viralized","custom"],"type":"string"},"type":"array"},"url":{"format":"uri","type":"string"}},"required":["url"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}},"description":"Webhook criado"}},"security":[{"BearerAuth":[]}],"summary":"Cria webhook (returns secret 1x)","tags":["webhooks"]}},"/webhooks/{webhook_id}":{"delete":{"parameters":[{"in":"path","name":"webhook_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"404":{"description":"Not found"}},"security":[{"BearerAuth":[]}],"summary":"Soft-delete (active=0)","tags":["webhooks"]}},"/webhooks/{webhook_id}/deliveries":{"get":{"parameters":[{"in":"path","name":"webhook_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de deliveries"},"403":{"description":"Webhook n\u00e3o pertence ao customer"},"404":{"description":"Webhook n\u00e3o encontrado"}},"security":[{"BearerAuth":[]}],"summary":"Lista \u00faltimas 50 deliveries (debug + dead-letter visibility)","tags":["webhooks"]}},"/webhooks/{webhook_id}/deliveries/{delivery_id}/retry":{"post":{"description":"\u00datil quando customer corrige endpoint ap\u00f3s dead-letter. Reset status=pending, attempts mant\u00e9m hist\u00f3rico.","parameters":[{"in":"path","name":"webhook_id","required":true,"schema":{"type":"string"}},{"in":"path","name":"delivery_id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Requeued \u2014 {requeued: true, prev_status}"},"403":{"description":"Delivery pertence a outro customer"},"404":{"description":"Delivery n\u00e3o encontrada"},"409":{"description":"Status atual n\u00e3o pode ser requeued (ex: success)"}},"security":[{"BearerAuth":[]}],"summary":"Re-enfileira delivery em dead/failed pra pr\u00f3ximo worker tick","tags":["webhooks"]}}},"servers":[{"description":"Production","url":"https://www.vegaindex.app.br/api/v1"},{"description":"Local dev","url":"http://localhost:5000/api/v1"}],"tags":[{"description":"Scoring endpoints","name":"score"},{"description":"Webhook management","name":"webhooks"},{"description":"API key management","name":"keys"},{"description":"Track search/autocomplete","name":"search"},{"description":"Drift monitor (public)","name":"drift"},{"description":"Ground truth feedback","name":"feedback"},{"description":"Admin (basic auth)","name":"admin"},{"description":"Healthcheck","name":"health"}]}