> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Modulo API

Il contratto pubblico versionato, il plumbing delle chiavi e la superficie OpenAPI.

## Prima di iniziare

Apri il progetto supastack scaricato in Visual Studio Code utilizzando File → Apri cartella, quindi scegli Terminale → Nuovo terminale. La radice del repository è la cartella contenente package.json, app e pacchetti. Esegui il comando qui sotto e lascia il suo terminale aperto. Se un comando non viene riconosciuto, completare la guida all'installazione dello strumento prima di continuare.

Leggi prima il tutorial sulla piattaforma. Un server è il processo dell'app che risponde alle richieste del browser o del telefono. Il Web legge apps/web/.env.local, Expo legge apps/mobile/.env.local e i comandi di migrazione del database leggono root .env. La dimostrazione senza database/dashboard è separata dagli account reali/auth, che necessitano della migrazione Postgres. Un pagamento solo telefonico o desktop richiede un backend Web eseguito separatamente.

[Installa gli strumenti e ottieni il codice](https://supastack.dev/it/docs/web/before-you-start.md)

[Impara comandi, file e configurazione](https://supastack.dev/it/docs/web/terminal-basics.md)

[Completa il tutorial di prima esecuzione sul Web](https://supastack.dev/it/docs/web/ship-in-5-minutes.md)

```
corepack pnpm --filter @supastack/web dev
```


## Installazione e configurazione

packages/api è la fonte di verità per la superficie REST pubblica: schemi zod per richieste, risposte e l'involucro di errore, più il documento OpenAPI (openApiDocument) servito su /api/v1/openapi. Gli handler di route compongono questi schemi invece di ridefinire forme.

Le chiavi API sono emesse per workspace con prefisso sk_<env>_, archiviate con hash a confronto a tempo costante, e portano scope — read di default. api-keys.ts possiede creazione, lookup e revoca.

```
apiV1 = "/api/v1"

schemas: currentWorkspace, entitlement,
  modelRequirements, createAiTaskRequest,
  aiTask, aiTaskResult, apiError

openApiDocument → GET /api/v1/openapi
```


## Flusso di implementazione

Aggiungi endpoint dentro la versione esistente: estendi gli schemi, mantieni l'involucro di errore e rigenera la superficie OpenAPI così /api/docs resta accurato. I cambiamenti breaking ottengono una nuova versione, non un cambio di forma silenzioso.

Risolvi il workspace del chiamante dalla chiave presentata, applica le stesse regole di entitlement e validazione della web app, e rate-limita per chiave.


## Verifica e risoluzione dei problemi

Fai contract-test di ogni forma di route contro gli schemi del package. Verifica che chiavi sconosciute, revocate e richieste con scope insufficiente falliscano tutte con l'involucro di errore documentato, e che il documento OpenAPI resti JSON valido.


## Successivo

[Limitazione di frequenza](https://supastack.dev/it/docs/modules/rate-limiting.md)