⚠ MOCK · Endpoints reais entram na FASE 3

API — Documentação

REST sobre HTTPS. Auth via API key Bearer. Base URL https://api.vegapni.app.br/v1. Esta página é o contrato esperado da API. Endpoints reais entram na FASE 3 do roadmap — esta página existe pra validar shape com clientes BETA antes de implementar.

Autenticação

API keys formato Stripe-style lu_test_xxx (sandbox) / lu_live_xxx (prod). Header Authorization: Bearer lu_live_.... Cada key tem scopes (score, jobs, usage, webhooks, admin).

// Header em toda request:
Authorization: Bearer lu_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Content-Type:  application/json

Storage: SHA-256 hash do key full + key_id 16 chars visíveis (audit-safe). Logs nunca contêm a key full.

Endpoints principais

POST /v1/score

Submete uma ou mais tracks pra scoring síncrono. Resposta ≤ 2s p95.

Request

{
  "tracks": [
    {
      "isrc":           "BR-XYZ-26-00142",
      "title":          "Tô Bem Demais",
      "artist_primary": "DJ Vida Nova",
      "audio_url":      "https://cdn.distro.com/track.mp3",
      "release_date":   "2026-04-15",
      "genre":          "gospel-funk",
      "language":       "pt-BR",
      "target_region":  "BR",
      "label_tier":     "indie",
      "lyrics":         "..."
    }
  ],
  "include_narrative": true
}

Response 200

{
  "results": [
    {
      "track_id":   "tr_a1b2c3d4e5",
      "score":      71,
      "category":   "WATCH",
      "sub_scores": {
        "tiktok_potential":    78,
        "streaming_potential": 64,
        "audio_similarity":    70
      },
      "confidence":   "medium",
      "trend":        "rising",
      "horizon_30d":  0.34,
      "horizon_90d":  0.47,
      "last_updated": "2026-04-15T18:30:00Z",
      "narrative":    "Track com tração inicial forte no TikTok, especialmente via creators de médio porte. Streaming ainda em estágio inicial — vale acompanhar pra confirmar se a tração se converte em saves no Spotify."
    }
  ]
}

GET /v1/score/{track_id}

Busca o estado atual + histórico. Auto-refresh 90 dias incluso. Sem cobrança se nada mudou desde a última poll.

Response 200

{
  "track_id":     "tr_a1b2c3d4e5",
  "score":        81,
  "trend":        "rising",
  "last_updated": "2026-04-22T10:15:00Z",
  "score_history": [
    { "ts": "2026-04-15T18:30:00Z", "score": 71 },
    { "ts": "2026-04-18T18:30:00Z", "score": 75 },
    { "ts": "2026-04-22T10:15:00Z", "score": 81 }
  ]
}

POST /v1/score/batch

Submete catálogo grande em lote (até 10.000 tracks por request). Callback via webhook ou polling.

Request

{
  "catalog_id":   "my_catalog_q2",
  "callback_url": "https://api.minhadistro.com/vegapni/callback",
  "tracks":       [ /* ... até 10000 tracks ... */ ]
}

Response 202

{
  "batch_id":    "batch_xyz789",
  "eta_seconds": 3200,
  "status_url":  "/v1/batch/batch_xyz789"
}

GET /v1/batch/{batch_id}

Status do batch + IDs já completos.

{
  "batch_id": "batch_xyz789",
  "status":   "running",
  "progress": { "completed": 2543, "total": 10000 },
  "completed_track_ids": [ "tr_...", ... ]
}

GET /v1/usage

Quota mensal + breakdown + distribuição de scores até agora.

{
  "plan":           "pro",
  "quota_monthly":  10000,
  "quota_used":     3214,
  "reset_at":       "2026-06-01T00:00:00Z",
  "score_distribution": {
    "HIGH_POTENTIAL": 312,
    "WATCH":          854,
    "NEUTRAL":        1280,
    "LOW":            643,
    "DEAD_WEIGHT":    125
  }
}

Códigos HTTP

Status	Significado
`200`	OK
`202`	Aceito pra processamento async
`400`	Request inválido (campo faltando, tipo errado)
`401`	API key ausente ou inválida
`402`	Quota mensal excedida (precisa upgrade ou esperar reset)
`403`	Scope insuficiente pra esse endpoint
`413`	Audio muito grande (>30 MB) ou batch > 10k tracks
`429`	Rate limit burst excedido (retry-after no header)
`500`	Erro interno (reportar pra suporte com X-Request-ID)

SDKs

SDK Python single-file open-source (pip install vegapni). Single dependência: requests. Exemplo:

from vegapni import Client

client = Client(api_key="vp_live_...")

result = client.score(
    isrc="BR-XYZ-26-00142",
    title="Tô Bem Demais",
    artist_primary="DJ Vida Nova",
    audio_file="track.mp3",
    genre="gospel-funk",
)

if result.is_high_potential():
    promo_queue.append(result.track_id)

Webhooks (Pro/Enterprise)

Inscreva-se em eventos score.completed, batch.completed, score.refreshed. Payload HMAC-SHA256 signed com seu webhook secret. Retry exponencial (1m, 5m, 30m, 2h, 12h, 24h).

X-VEGA-Signature: sha256=<hex>
X-VEGA-Event:     score.completed
X-VEGA-Delivery:  evt_abc123

Status atual: esta API é o contrato planejado — endpoints reais entram em produção na FASE 3 do roadmap (estimada ~3-4 semanas após início). Pra acompanhar lançamento, entre na waiting list em /.