REST API

L'API HTTP su cui sono costruiti il server MCP e la CLI. Usala per integrare Willet con qualsiasi cosa che parli HTTP.

Riferimento interattivo

Il riferimento completo e sempre aggiornato è l'API explorer interattivo nella tua dashboard. Mostra la specifica OpenAPI con ogni endpoint, parametro e schema di risposta, e ti permette di eseguire richieste live sul tuo account usando un token temporaneo.

Apri l'API explorer

URL di base

Su Willet Cloud, ogni endpoint si trova sotto https://willet.bgenc.dev/api/v1. I server self-hosted espongono la stessa API sotto <your-server>/api/v1.

La specifica OpenAPI 3.1 grezza è disponibile all'indirizzo /api/v1/openapi.json se preferisci generare un client o importarla nei tuoi strumenti.

Autenticazione

Invia un segreto API come bearer token in ogni richiesta: Authorization: Bearer <secret>.

curl -H "Authorization: Bearer $WILLET_API_TOKEN" \
  https://willet.bgenc.dev/api/v1/me

Su Willet Cloud, crea un segreto nella dashboard sotto Impostazioni → Segreti API. Ogni segreto ha un ambito e un livello di accesso:

user / project sceglie tutti i tuoi progetti, o solo uno.
read / read_write sceglie sola lettura, o lettura/scrittura completa.

Errori

Gli errori restituiscono uno stato non-2xx e un corpo JSON: { "error": "message", "details": [...] }.

`400`	Validazione della richiesta fallita.
`401`	Segreto mancante, non valido, revocato o scaduto.
`403`	Al segreto mancano i permessi necessari, ad esempio un segreto in sola lettura o limitato a un progetto specifico usato dove non è consentito.
`404`	La risorsa non esiste.
`501`	Un endpoint solo Cloud chiamato su un server self-hosted.

Avanti

Preferisci il terminale? La CLI include tutti questi endpoint con login, output JSON e codici di uscita.

Riferimento CLI →