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

# API di Square Cloud: URL base e prima richiesta

> Inizia con l'API REST di Square Cloud: URL base v2, header Authorization, una prima richiesta curl, il formato delle risposte, gli ID e gli errori.

L'API di Square Cloud è un'API REST su HTTPS. Copre ciò che fai nella dashboard: deploy e controllo delle applicazioni, lettura di log e metriche, gestione di file, variabili d'ambiente, snapshot, database e workspace. Invia e riceve JSON, con due eccezioni: [upload](/it/api-reference/endpoint/apps/upload) e [commit](/it/api-reference/endpoint/apps/commit) accettano uno zip come `multipart/form-data`, e [realtime](/it/api-reference/endpoint/apps/realtime) trasmette Server-Sent Events.

## URL base

Ogni endpoint di questa reference è relativo a:

```bash theme={"system"}
https://api.squarecloud.app/v2
```

[Blob Storage](/it/blob-reference/quickstart) è un'API separata con un proprio URL base, `https://blob.squarecloud.app/v1`, e accetta la stessa chiave API.

## Autenticazione

Crea una chiave API nelle [impostazioni di sicurezza del tuo account](https://squarecloud.app/it/account/security) e inviala nell'header `Authorization` di ogni richiesta. Il prefisso `Bearer ` è facoltativo.

```bash theme={"system"}
Authorization: <api_key>
```

La chiave viene mostrata una sola volta, al momento della creazione. Conservala sul tuo server, in una variabile d'ambiente, e mai nel codice lato client o in un repository. Ogni chiave ha degli scope che limitano cosa può fare: consulta [Autenticazione](/it/api-reference/authentication) per lo scope di ogni endpoint.

## La tua prima richiesta

[Informazioni sull'account](/it/api-reference/endpoint/users/me) restituisce il tuo profilo, il tuo piano e tutte le applicazioni e i database di cui sei proprietario. Richiede una chiave con lo scope `account:read`.

```bash theme={"system"}
export SQUARECLOUD_API_KEY="your-api-key"

curl https://api.squarecloud.app/v2/users/me \
  --header "Authorization: $SQUARECLOUD_API_KEY"
```

```json theme={"system"}
{
  "status": "success",
  "response": {
    "user": {
      "id": "1234567890",
      "name": "John Doe",
      "email": "john@example.com",
      "locale": "en-US",
      "plan": {
        "name": "standard-4",
        "memory": { "limit": 4096, "available": 3584, "used": 512 },
        "duration": 1780615237662
      },
      "created_at": "2024-05-01T12:00:00.000Z"
    },
    "applications": [
      {
        "id": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
        "name": "my-app",
        "ram": 512,
        "lang": "javascript",
        "domain": "my-app.squareweb.app",
        "custom": null,
        "cluster": "example-cluster",
        "created_at": "2024-05-01T12:00:00.000Z"
      }
    ],
    "databases": []
  }
}
```

Se ricevi `401 ACCESS_DENIED`, la chiave è mancante o non viene riconosciuta. Se ricevi `403 MISSING_SCOPE`, la chiave funziona ma non ha `account:read`.

## Formato delle risposte

Una chiamata riuscita risponde `2xx` con `"status": "success"` e, quando c'è qualcosa da restituire, i dati in `response`:

```json theme={"system"}
{ "status": "success", "response": { } }
```

Azioni come l'avvio o l'arresto rispondono solo `{ "status": "success" }`. Una chiamata non riuscita risponde `4xx` o `5xx` con `"status": "error"` e un `code` su cui basare la logica:

```json theme={"system"}
{ "status": "error", "code": "APP_NOT_FOUND" }
```

I nomi dei campi nelle risposte usano `snake_case`. Ogni codice, con cosa fare, è in [Errori](/it/api-reference/errors).

## ID

* **Applicazioni e database** hanno un id esadecimale di 32 caratteri, come `a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d`. Lo trovi in [Informazioni sull'account](/it/api-reference/endpoint/users/me) o nell'indirizzo della risorsa nella dashboard.
* **Un'applicazione condivisa con te tramite un workspace** si indica come `<appId>-<workspaceId>` nel percorso, ad esempio `/v2/apps/<appId>-<workspaceId>/status`.
* **I workspace** hanno un id esadecimale di 32 caratteri. I workspace più vecchi mantengono un id di 40 caratteri.

## Limiti

Ogni account ha un budget di richieste ogni 60 secondi, stabilito dal suo piano, e alcuni endpoint hanno un proprio limite, indicato nella loro pagina. Consulta [Limiti e restrizioni](/it/api-reference/limitations-and-restrictions) per i valori ed [Errori](/it/api-reference/errors#limiti-di-frequenza) per capire come funziona il `429`.

## Specifica OpenAPI

L'intera API è descritta in un [documento OpenAPI](/it/api-reference/openapi) all'indirizzo `https://api.squarecloud.app/v2/openapi.json`. Importalo in Postman o Insomnia, oppure genera un client a partire da esso.

<Tip>
  Preferisci un client tipizzato? Gli [SDK di Square Cloud](/it/sdks/introduction) per [JavaScript](/it/sdks/js/client), [Python](/it/sdks/py/client) e [Go](/it/sdks/go/client) coprono ogni endpoint di questa reference, e la [CLI](/it/cli-reference/quickstart) svolge le stesse attività dal terminale.
</Tip>

## Prossimi passi

<CardGroup cols={2}>
  <Card title="Autenticazione e scope" icon="lock" href="/it/api-reference/authentication">
    Scegli gli scope di cui ha bisogno ogni integrazione.
  </Card>

  <Card title="Codici di errore" icon="triangle-exclamation" href="/it/api-reference/errors">
    Ogni codice restituito dall'API e come gestirlo.
  </Card>

  <Card title="Carica un'applicazione" icon="upload" href="/it/api-reference/endpoint/apps/upload">
    Fai il deploy di uno zip con una sola richiesta.
  </Card>

  <Card title="Rate limit" icon="gauge" href="/it/api-reference/limitations-and-restrictions">
    Budget di richieste per piano.
  </Card>
</CardGroup>