> ## Documentation Index
> Fetch the complete documentation index at: https://www.macaly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Panoramica dell'API

> Realizza applicazioni web ed effettuane il deployment in modo programmatico con l'API di Macaly

L'API di Macaly permette ad applicazioni esterne di creare chat, realizzare applicazioni web con l'IA ed effettuarne il deployment in produzione in modo programmatico.

<Callout icon="user">
  Disponibile solo con il [**piano Agenzie**](/docs/it/welcome/pricing)
</Callout>

## URL di base

```
https://www.macaly.com
```

## Avvio rapido

1. **Ottieni una chiave API** - Vedi [Autenticazione](/docs/it/api/authentication)
2. **Crea una chat** - Invia un prompt per iniziare a realizzare la tua app
3. **Segui l'avanzamento** - Attendi che l'IA finisca
4. **Effettua il deployment** - Pubblica la tua app in produzione

## Endpoint disponibili

| Metodo | Endpoint | Descrizione |
| - | - | - |
| POST | [`/api/chat`](/docs/it/api/create-chat) | Creazione di una nuova chat e avvio del lavoro |
| POST | [`/api/chat/{chatId}/publish`](/docs/it/api/publish-message) | Invio di un messaggio a una chat esistente |
| POST | [`/api/client-app/assets/upload`](/docs/it/api/upload-asset) | Caricamento di un file e ottenimento di una URL CDN permanente |
| GET | [`/api/chat/{chatId}/status`](/docs/it/api/get-status) | Verifica dello stato dell'elaborazione |
| GET | [`/api/chat/{chatId}/subscribe`](/docs/it/api/subscribe-stream) | Sottoscrizione allo stream in tempo reale |
| POST | [`/api/chat/{chatId}/deploy`](/docs/it/api/deploy) | Deployment della chat in produzione |
| GET | [`/api/chat/{chatId}/deployment`](/docs/it/api/get-deployment) | Verifica dello stato del deployment |

## Limiti di richieste e crediti

* Le richieste API consumano crediti dal saldo del tuo team
* La creazione di ogni chat costa quanto l'utilizzo dell'interfaccia web
* I tentativi falliti con la chiave API sono soggetti a un limite di richieste (5 al minuto per indirizzo IP)
* Controlla il tuo utilizzo in **Impostazioni → Utilizzo e limiti**

## Gestione degli errori

Tutti gli errori restituiscono un JSON con un campo `error`:

```json theme={null}
{
  "error": "Error message here"
}
```

### Codici di stato HTTP

| Codice | Descrizione |
| - | - |
| 400 | Bad Request: corpo della richiesta non valido |
| 401 | Unauthorized: chiave API non valida o mancante |
| 402 | Payment Required: crediti insufficienti |
| 403 | Forbidden: permessi insufficienti o team errato |
| 404 | Not Found: risorsa non trovata |
| 422 | Unprocessable Entity: errore di validazione |
| 429 | Too Many Requests: limite di richieste raggiunto |
| 500 | Internal Server Error: errore lato server |
| 503 | Service Unavailable: il server è occupato, riprova più tardi |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.