API Square Cloud : URL de base et première requête

L’API Square Cloud est une API REST sur HTTPS. Elle couvre ce que vous faites dans le tableau de bord : déployer et piloter des applications, lire leurs logs et leurs métriques, gérer les fichiers, les variables d’environnement, les snapshots, les bases de données et les workspaces. Elle envoie et reçoit du JSON, avec deux exceptions : l’envoi et le commit reçoivent un zip en multipart/form-data, et le temps réel diffuse des Server-Sent Events.

URL de base

Chaque endpoint de cette référence est relatif à :

https://api.squarecloud.app/v2

Blob Storage est une API distincte avec sa propre URL de base, https://blob.squarecloud.app/v1, et elle accepte la même clé API.

Authentification

Créez une clé API dans les paramètres de sécurité de votre compte et envoyez-la dans l’en-tête Authorization de chaque requête. Le préfixe Bearer est facultatif.

Authorization: <api_key>

La clé ne s’affiche qu’une seule fois, à sa création. Conservez-la sur votre serveur, dans une variable d’environnement, et jamais dans du code côté client ni dans un dépôt. Chaque clé porte des scopes qui limitent ce qu’elle peut faire : consultez Authentification pour connaître le scope de chaque endpoint.

Votre première requête

Informations sur le compte renvoie votre profil, votre plan et chaque application et base de données que vous possédez. Il faut une clé avec le scope account:read.

export SQUARECLOUD_API_KEY="your-api-key"

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

{
  "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": []
  }
}

Si vous recevez 401 ACCESS_DENIED, la clé est absente ou n’est pas reconnue. Si vous recevez 403 MISSING_SCOPE, la clé fonctionne mais n’a pas account:read.

Format de réponse

Un appel réussi répond 2xx avec "status": "success" et, lorsqu’il y a quelque chose à renvoyer, les données dans response :

{ "status": "success", "response": { } }

Les actions comme démarrer ou arrêter répondent seulement { "status": "success" }. Un appel en échec répond 4xx ou 5xx avec "status": "error" et un code sur lequel vous pouvez vous appuyer :

{ "status": "error", "code": "APP_NOT_FOUND" }

Les noms de champs des réponses sont en snake_case. Chaque code, avec la marche à suivre, figure dans Erreurs.

IDs

Les applications et les bases de données ont un id hexadécimal de 32 caractères, comme a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d. Récupérez-les avec Informations sur le compte ou dans l’adresse de la ressource dans le tableau de bord.
Une application partagée avec vous via un workspace s’adresse sous la forme <appId>-<workspaceId> dans le chemin, par exemple /v2/apps/<appId>-<workspaceId>/status.
Les workspaces ont un id hexadécimal de 32 caractères. Les workspaces plus anciens conservent un id de 40 caractères.

Limites

Chaque compte dispose d’un budget de requêtes par tranche de 60 secondes, fixé par son plan, et certains endpoints ont leur propre limite, indiquée sur leur page. Consultez Limitations et restrictions pour les valeurs et Erreurs pour le fonctionnement du 429.

Spécification OpenAPI

Toute l’API est décrite dans un document OpenAPI à l’adresse https://api.squarecloud.app/v2/openapi.json. Importez-le dans Postman ou Insomnia, ou générez un client à partir de celui-ci.

Vous préférez un client typé ? Les SDK Square Cloud pour JavaScript, Python et Go couvrent chaque endpoint de cette référence, et la CLI permet les mêmes tâches depuis un terminal.

Étapes suivantes

Authentification et scopes

Choisissez les scopes dont chaque intégration a besoin.

Codes d'erreur

Chaque code renvoyé par l’API et comment le gérer.

Envoyer une application

Déployez un zip en une seule requête.

Limites de débit

Budgets de requêtes par plan.

Premiers pas

Compte

Applications

Bases de données

Workspaces

IA

API Square Cloud : URL de base et première requête

URL de base

Authentification

Votre première requête

Format de réponse

IDs

Limites

Spécification OpenAPI

Étapes suivantes

Authentification et scopes

Codes d'erreur

Envoyer une application

Limites de débit

​URL de base

​Authentification

​Votre première requête

​Format de réponse

​IDs

​Limites

​Spécification OpenAPI

​Étapes suivantes

Authentification et scopes

Codes d'erreur

Envoyer une application

Limites de débit

URL de base

Authentification

Votre première requête

Format de réponse

IDs

Limites

Spécification OpenAPI

Étapes suivantes