API de Account Meta

La API de Account Meta entrega los datos maestros de cuenta y team que cualquier frontend necesita en el bootstrap — team actual, balance de créditos, KPIs del dashboard y (admin only) reportes internos de coste de API. Todos los endpoints están autenticados con Sanctum y scope al team.

Endpoints

/v1/team

Devuelve el team actual. El team switch se hace en el frontend vía cookie de sesión — la API en sí siempre lee el team activo desde $request->user()->currentTeam().

curl "$BASE/team" -H "Authorization: Bearer $TOKEN"

{
  "data": {
    "id": 3,
    "name": "Acme GmbH",
    "slug": "acme-gmbh",
    "owner_id": 12,
    "member_count": 4,
    "plan": "pro",
    "created_at": "2025-11-04T10:22:13Z"
  }
}

/v1/credits

Muestra el balance de créditos con su periodo de facturación. El histórico detallado de transacciones con patrones de gasto está en el endpoint dedicado de Credits — ver API de Créditos.

curl "$BASE/credits" -H "Authorization: Bearer $TOKEN"

{
  "data": {
    "balance": 4823,
    "plan": "pro",
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-04-30T23:59:59Z",
    "auto_topup": false
  }
}

GET /v1/credits/history pagina los eventos individuales de consumo con endpoint, credits_used, created_at.

/v1/dashboard

Payload agregado de bootstrap para la UI del dashboard. Contiene:

• headline_kpis — AVI score, conteo de Top-10 keywords, nuevos backlinks, score de Site Audit
• recent_activity — últimos 10 eventos a nivel team (Article generated, Audit completed, ...)
• quick_actions — tareas high-priority sugeridas por el Action Center

Un solo roundtrip en lugar de 5 llamadas separadas — por eso el endpoint dedicado.

curl "$BASE/dashboard" -H "Authorization: Bearer $TOKEN" | jq .data.headline_kpis

/v1/admin/api-costs

Admin only — entrega la tabla de cost tracking de los providers externos (OpenAI, Anthropic, ScraperAPI, DataForSEO, Resend, ...). Los usuarios sin rol admin reciben 403 Forbidden.

curl "$BASE/admin/api-costs?from=2026-04-01&to=2026-04-30" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": [
    { "provider": "anthropic", "model": "claude-opus-4-7",
      "calls": 1842, "input_tokens": 4_120_000, "output_tokens": 980_000,
      "usd_cost": 184.32 },
    { "provider": "scraperapi",
      "calls": 9211, "usd_cost": 27.63 }
  ],
  "totals": { "usd_cost": 312.84, "credits_billed": 12_400 }
}

Gestión de tokens

Los API tokens se generan en la UI vía /settings/api-tokens — la interfaz HTTP correspondiente vive en el módulo Auth (login/logout/token issue). Detalles: API de Auth.

Regla práctica:

• Personal Access Token — generado manualmente en la UI, larga vida útil, scope = team actual.
• OAuth Token — para integraciones de terceros, TTL corto, refresh flow.

Los tokens no se rotan vía endpoints de Account Meta — usa para eso los endpoints de Auth.

Pitfalls

• currentTeam() lo gobierna la cookie. Si el usuario está en varios teams, haz el switch en el frontend (/teams/switch) antes de leer /v1/team.
• /dashboard no está cacheado. En polling frecuente, mete un caché de cliente con TTL ~30 s.
• /admin/api-costs es raw. Las columnas son las entradas internas de coste por provider — la conversión a créditos pasa por separado en la capa de billing.
• Los plan limits no leakean por /team. Los detalles de cuota (max projects, max articles) se leen por el endpoint del plan en el módulo Auth.

Relacionado: API de Auth · API de Créditos · API de Proyectos.