# Mindmap API

Crea mappe mentali da prompt e da contesto LiveDoc opzionale.

Questa pagina documenta le API Felo esistenti `/v2`, usando **le entitlements dell'account Felo e le regole dei crediti Pro**. Se i crediti vengono scalati dipende dall'[operazione](https://openapi.felo.ai/it/docs/faq/billing-and-credits.md#regole-dei-crediti-per-funzionalit-v2). Per le chiamate con saldo della piattaforma, scegli un endpoint [Felo OpenAPI](https://openapi.felo.ai/it/docs/api-reference/openapi/overview.md) supportato; le forme di richiesta e risposta possono differire.

La Mindmap API fornisce funzionalità di generazione di mindmap. Puoi creare una mindmap con un argomento o una domanda, e specificare facoltativamente un tipo di layout.

## Usa con gli AI Agent

Installa il pacchetto completo `felo-ai` per consentire a un Agent di creare mindmap insieme a ogni altra Felo Skill disponibile. L'installer scopre dinamicamente ogni directory di pacchetto che contiene `SKILL.md`, quindi include aggiunte future. Installa tutte le Skill scoperte in Codex `~/.codex/skills`, Claude Code `~/.claude/skills`, OpenClaw `~/.agents/skills` o Hermes Agent `~/.hermes/skills`. Segui la [guida manuale alla configurazione dell'AI Agent](https://openapi.felo.ai/it/docs/felo-skills.md) per la procedura sicura di configurazione per ciascuna piattaforma.


## Autenticazione

Tutte le richieste richiedono una API Key nell'header `Authorization`:

```
Authorization: Bearer YOUR_API_KEY
```

## Crea mindmap

Crea una mindmap basata su una query (argomento o domanda).

### Endpoint

```
POST https://openapi.felo.ai/v2/mindmap
```

### Header della richiesta

| Header | Obbligatorio | Descrizione |
|--------|--------------|-------------|
| `Authorization` | Sì | La tua API Key nel formato `Bearer YOUR_API_KEY` |
| `Content-Type` | Sì | Deve essere `application/json` |

### Body della richiesta

| Parametro | Tipo | Obbligatorio | Descrizione |
|-----------|------|--------------|-------------|
| `query` | string | Sì | L'argomento o la domanda per la generazione della mindmap. Massimo 2000 caratteri |
| `layout` | string | No | Tipo di layout. Predefinito: `MIND_MAP` |
| `livedoc_short_id` | string | No | ID LiveDoc. Se non fornito, verrà creato automaticamente un nuovo LiveDoc |

### Tipi di layout

| Layout | Descrizione |
|--------|-------------|
| `MIND_MAP` | Mind map classica (predefinita) |
| `LOGICAL_STRUCTURE` | Diagramma di struttura logica |
| `ORGANIZATION_STRUCTURE` | Organigramma |
| `CATALOG_ORGANIZATION` | Organigramma a catalogo |
| `TIMELINE` | Diagramma temporale |
| `FISHBONE` | Diagramma a lisca di pesce |

### Esempio: crea con LiveDoc automatico

```bash
curl -X POST 'https://openapi.felo.ai/v2/mindmap' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Artificial Intelligence trends in 2024"
  }'
```

### Esempio: crea con LiveDoc specifico

```bash
curl -X POST 'https://openapi.felo.ai/v2/mindmap' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Project timeline overview",
    "layout": "TIMELINE",
    "livedoc_short_id": "abc123xyz"
  }'
```

### Risposta di successo (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": {
    "resource_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "livedoc_short_id": "PvyKouzJirXjFdst4uKRK3",
    "mindmap_url": "https://felo.ai/mindmap/550e8400-e29b-41d4-a716-446655440000",
    "message": "Mindmap created successfully"
  }
}
```

### Campi della risposta

| Campo | Tipo | Descrizione |
|-------|------|-------------|
| `resource_id` | string | ID della risorsa della mindmap creata |
| `status` | string | Stato della mindmap (ad es. `COMPLETED`) |
| `livedoc_short_id` | string | Short ID LiveDoc in cui la mindmap è archiviata |
| `mindmap_url` | string | URL per visualizzare la mindmap (formato: `{host}/mindmap/{resource_id}`) |
| `svg` | string \| null | SVG opzionale, presente solo quando il generatore lo fornisce; può essere omesso |
| `message` | string | Messaggio di stato |

### Leggi la struttura della mindmap

Usa `data.livedoc_short_id` e `data.resource_id` per leggere la risorsa `mindmap` salvata:

```bash
curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/550e8400-e29b-41d4-a716-446655440000/content' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

La risposta della risorsa ha `data.type: "mindmap"`. Analizza `data.content` come JSON per ottenere la struttura:

```json
{
  "layout": "mindMap",
  "text": "# Topic\n## Branch\n### Leaf"
}
```

`text` usa intestazioni Markdown per rappresentare la gerarchia. Il valore `layout` salvato è un valore del renderer (ad esempio `mindMap`); i valori di layout della richiesta usano i nomi in maiuscolo elencati sopra. Le applicazioni possono renderizzare questa struttura o aprire il `mindmap_url` restituito.

## Codici di errore

| Codice | Stato HTTP | Descrizione |
|------|-------------|-------------|
| `INVALID_API_KEY` | 401 | La API Key è non valida o revocata |
| `MINDMAP_CREATE_FAILED` | 502 | Creazione della mindmap fallita |
| `LIVEDOC_CREATE_FAILED` | 502 | Creazione del LiveDoc fallita |
| `LIVEDOC_NOT_FOUND` | 404 | Il LiveDoc specificato non è stato trovato |
| `LLM_SERVICE_UNAVAILABLE` | 503 | Il servizio LLM non è disponibile |
| `LLM_REQUEST_TIMEOUT` | 504 | Timeout della richiesta LLM |
