# Panoramica API

> Automatizza PentAGI tramite REST e GraphQL: crea un token Bearer, avvia i flows dalla CI/CD, recupera i risultati nei tuoi strumenti e genera un client.

La maggior parte di ciò che puoi fare nell'interfaccia web è disponibile tramite l'API: avvia [flows](https://pentagi.com/it/docs/glossary/#flow) da CI/CD, importa i risultati nei tuoi strumenti o crea integrazioni.

| API     | Endpoint          | Documentazione interattiva   |
| ------- | ----------------- | ---------------------------- |
| GraphQL | `/api/v1/graphql` | `/api/v1/graphql/playground` |
| REST    | `/api/v1/...`     | `/api/v1/swagger/index.html` |

## [Crea un token](https://pentagi.com/it/docs/api/overview/#create-a-token)

1. Apri **Settings → API Tokens** nell'interfaccia web.
2. Clicca su **Create Token**, assegnagli facoltativamente un nome e imposta una scadenza tra 1 minuto e 3 anni.
3. Copia subito il token: viene mostrato una sola volta.

Un token è associato al tuo account ed eredita i permessi del tuo ruolo. Utenti, ruoli e token API, [template](https://pentagi.com/it/docs/glossary/#template) dei flow, preferiti e le tue impostazioni sono gestiti solo da una sessione del browser con accesso effettuato: un token riceve 403 sulle route REST `/users`, `/roles` e `/tokens` e un errore da quelle operazioni GraphQL.

## [Chiama l'API](https://pentagi.com/it/docs/api/overview/#call-the-api)

```bash
curl -X POST https://your-pentagi-host:8443/api/v1/graphql \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ flows { id title status } }"}'

curl https://your-pentagi-host:8443/api/v1/flows/ \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Avvia un flow con una mutazione GraphQL:

```graphql
mutation CreateFlow {
  createFlow(modelProvider: "openai", input: "Test the security of https://example.com") {
    id
    title
    status
    createdAt
  }
}
```

## [Genera un client](https://pentagi.com/it/docs/api/overview/#generate-a-client)

* **GraphQL** — lo schema si trova in `backend/pkg/graph/schema.graphqls` nel repository; usa GraphQL Code Generator, genqlient o Apollo.
* **REST** — la specifica OpenAPI è disponibile su `/api/v1/swagger/doc.json`:

```bash
openapi-generator-cli generate \
  -i https://your-pentagi-host:8443/api/v1/swagger/doc.json \
  -g python \
  -o ./pentagi-client
```