API da Square Cloud: URL base e primeira requisição

A API da Square Cloud é uma API REST sobre HTTPS. Ela cobre o que você faz no dashboard: fazer deploy e controlar aplicações, ler os logs e as métricas delas, gerenciar arquivos, variáveis de ambiente, snapshots, bancos de dados e workspaces. Ela envia e recebe JSON, com duas exceções: o upload e o commit recebem um zip como multipart/form-data, e o tempo real transmite Server-Sent Events.

URL base

Todo endpoint desta referência é relativo a:

https://api.squarecloud.app/v2

O Blob Storage é uma API separada, com a própria URL base, https://blob.squarecloud.app/v1, e aceita a mesma chave de API.

Autenticação

Crie uma chave de API nas configurações de segurança da sua conta e envie-a no header Authorization de toda requisição. O prefixo Bearer é opcional.

Authorization: <api_key>

A chave aparece uma única vez, quando você a cria. Mantenha-a no seu servidor, em uma variável de ambiente, e nunca em código do lado do cliente nem em um repositório. Cada chave tem escopos que limitam o que ela pode fazer: veja em Autenticação o escopo de cada endpoint.

Sua primeira requisição

Informações da conta retorna o seu perfil, o seu plano e todas as aplicações e bancos de dados que você possui. Exige uma chave com o escopo 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": []
  }
}

Se você receber 401 ACCESS_DENIED, a chave está ausente ou não foi reconhecida. Se receber 403 MISSING_SCOPE, a chave funciona, mas não tem account:read.

Formato das respostas

Uma chamada bem-sucedida responde 2xx com "status": "success" e, quando há algo a retornar, os dados em response:

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

Ações como iniciar ou parar respondem apenas { "status": "success" }. Uma chamada com falha responde 4xx ou 5xx com "status": "error" e um code para você decidir o que fazer:

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

Os nomes dos campos nas respostas usam snake_case. Todos os códigos, com o que fazer em cada um, estão em Erros.

IDs

Aplicações e bancos de dados têm um id hexadecimal de 32 caracteres, como a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d. Obtenha-os em Informações da conta ou no endereço do recurso no dashboard.
Uma aplicação compartilhada com você por um workspace é endereçada como <appId>-<workspaceId> no caminho, por exemplo /v2/apps/<appId>-<workspaceId>/status.
Workspaces têm um id hexadecimal de 32 caracteres. Workspaces mais antigos mantêm um de 40 caracteres.

Limites

Cada conta tem um orçamento de requisições a cada 60 segundos, definido pelo plano, e alguns endpoints têm o próprio limite, informado na página deles. Veja Limitações e restrições para os valores e Erros para entender como o 429 funciona.

Especificação OpenAPI

A API inteira está descrita em um documento OpenAPI em https://api.squarecloud.app/v2/openapi.json. Importe-o no Postman ou no Insomnia, ou gere um cliente a partir dele.

Prefere um cliente tipado? Os SDKs da Square Cloud para JavaScript, Python e Go cobrem todos os endpoints desta referência, e a CLI faz as mesmas tarefas pelo terminal.

Próximos passos

Autenticação e escopos

Escolha os escopos de que cada integração precisa.

Códigos de erro

Todos os códigos que a API retorna e como tratar cada um.

Enviar uma aplicação

Faça o deploy de um zip com uma única requisição.

Limites de requisições

Orçamento de requisições por plano.

Primeiros passos

Conta

Aplicações

Bancos de dados

Workspaces

IA

API da Square Cloud: URL base e primeira requisição

URL base

Autenticação

Sua primeira requisição

Formato das respostas

IDs

Limites

Especificação OpenAPI

Próximos passos

Autenticação e escopos

Códigos de erro

Enviar uma aplicação

Limites de requisições

​URL base

​Autenticação

​Sua primeira requisição

​Formato das respostas

​IDs

​Limites

​Especificação OpenAPI

​Próximos passos

Autenticação e escopos

Códigos de erro

Enviar uma aplicação

Limites de requisições

URL base

Autenticação

Sua primeira requisição

Formato das respostas

IDs

Limites

Especificação OpenAPI

Próximos passos