Docs / API v1 · Fatti indicizzare dalle AI

API Reference

Documentazione tecnica degli endpoint /api/v1/* usati dal plugin.

Autenticazione

Tutti gli endpoint (eccetto GET /api/v1/health) richiedono Authorization: Bearer GC22-XXXX-XXXX-XXXX. La license key viene hashata (SHA-256) e confrontata con licenses.key_hash.

Method	Endpoint	Tier	Scopo
GET	/api/v1/health	pubblico	Health check / versione API
POST	/api/v1/license/validate	tutti	Valida license key + ritorna tier info
POST	/api/v1/license/refresh	tutti	Refresh stato licenza (cron plugin 12h)
GET	/api/v1/credits/balance	Premium	Saldo crediti correnti
POST	/api/v1/credits/consume	Premium	Consumo crediti (idempotent)
POST	/api/v1/ai/generate	Premium	Proxy AI managed (idempotent)

Error codes

Errori standardizzati via campo error.code:

LICENSE_NOT_FOUND
LICENSE_SUSPENDED
LICENSE_EXPIRED
LICENSE_REVOKED
TIER_NOT_ALLOWED
SITE_LIMIT_EXCEEDED
INSUFFICIENT_CREDITS
IDEMPOTENCY_CONFLICT
AI_PROVIDERS_UNAVAILABLE
AI_TOOL_USE_MALFORMED
PAYLOAD_TOO_LARGE
RATE_LIMIT_EXCEEDED

Rate limiting

Rate limit per license key. In caso di superamento: HTTP 429 con header Retry-After. Dettaglio quote e strategie di backoff esposti in fase 5a della roadmap webapp.

API v1 in stabilizzazione

L'implementazione degli endpoint arriva in Fase 5a-5b del roadmap. Questa pagina documenta il contratto API come definito nella spec 1.2.0; scostamenti verranno documentati nel changelog.