> ## 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.

# Criar snapshot da aplicação

> Faça backup dos arquivos da aplicação em .zip com POST /v2/apps/{app_id}/snapshots. Retorna uma URL de download, ou 202 enquanto um snapshot grande é gerado.

<Warning>Cada conta pode executar até (RAM / 256) \* 2 snapshots a cada 24 horas.</Warning>

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

Requer uma chave de API com o [escopo](/pt-br/api-reference/authentication#escopos) `snapshots:write`.

Criar Snapshot captura uma cópia `.zip` do armazenamento completo de uma aplicação em um determinado momento e retorna uma URL de download assinada, dando a você um ponto de restauração antes de uma mudança arriscada ou uma forma de obter um backup completo fora da plataforma. Para trazer a aplicação de volta a esse estado depois, passe o snapshot resultante para [Restaurar Snapshot](/pt-br/api-reference/endpoint/apps/snapshots/restore); para inspecionar ou baixar snapshots anteriores sem criar um novo, use [Listar Snapshots](/pt-br/api-reference/endpoint/apps/snapshots/list).

Snapshots estão disponíveis apenas com um plano ativo, e a cota diária escala com a RAM da aplicação ((RAM / 256) × 2 a cada 24 horas). Em aplicações compartilhadas em workspace, quem chama precisa da [função](/pt-br/api-reference/endpoint/workspace/members/invite#funções) `admin`.

## Parâmetros

<ParamField path="app_id" type="string" placeholder="ID da Aplicação" required>
  O ID da aplicação. Você pode encontrá-lo na URL da sua aplicação no dashboard.
</ParamField>

## Comportamento de prazo flexível (soft deadline)

Esta rota segue um modelo de **prazo flexível (soft deadline)**: ela não responde mais sempre de forma síncrona.

* Se o snapshot terminar em até **\~90 segundos**, a rota responde com `200 success` e uma URL de download assinada (válida por 30 dias), exatamente como antes.
* Se o snapshot levar mais de **\~90 segundos** para ser gerado, a rota responde **imediatamente** com `202` e o código `SNAPSHOT_PROCESSING`. **Isso não é uma falha.** O snapshot continua sendo gerado em segundo plano e aparecerá sozinho na [listagem de snapshots](/pt-br/api-reference/endpoint/apps/snapshots/list), normalmente em até \~2 minutos. Esse é o comportamento esperado para aplicações grandes.

<Warning>
  Não use este endpoint `POST` como mecanismo de polling. Para verificar se um snapshot em `SNAPSHOT_PROCESSING` foi concluído, use o endpoint [Listar Snapshots](/pt-br/api-reference/endpoint/apps/snapshots/list) (`GET`), e **não** outro `POST`. Repetir o `POST` depois que o snapshot terminar inicia um snapshot completamente novo do zero.
</Warning>

O cliente deve tratar a resposta da seguinte forma:

| Resposta | Significado | O que fazer |
| - | - | - |
| `status === "success"` | O snapshot está pronto. | Use a `url` para baixá-lo. |
| `status === "error"` e `code === "SNAPSHOT_PROCESSING"` | O snapshot ainda está sendo gerado. | Aguarde \~2 minutos e confirme via [Listar Snapshots](/pt-br/api-reference/endpoint/apps/snapshots/list) (`GET`). **Não** repita o `POST`. |
| `status === "error"` com qualquer outro `code` | Falha real. | Trate o erro (veja abaixo). |

## Resposta

<ResponseField name="status" type="string">
  Indica se a chamada foi bem-sucedida: `success` se foi, `error` se não.
</ResponseField>

<ResponseField name="response" type="object">
  O conteúdo da resposta. Presente apenas quando `status` é `success`.

  <Expandable title="Alternar objeto">
    <ResponseField name="url" type="string">
      A URL para baixar o snapshot da sua aplicação.
    </ResponseField>

    <ResponseField name="key" type="string">
      A chave para baixar o snapshot da sua aplicação.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="SNAPSHOT_PROCESSING" type="202">
  Retornado quando o snapshot ultrapassa o prazo flexível de \~90 segundos. O snapshot continua sendo gerado em segundo plano e aparecerá sozinho na listagem de snapshots, normalmente em até \~2 minutos. Não é um erro: aguarde e confirme via o endpoint de listagem `GET`.
</ResponseField>

## Erros

Uma requisição de snapshot pode ser rejeitada com `429 Too Many Requests`. Use o campo `code` para distinguir os dois casos:

<ResponseField name="KEEP_CALM" type="429">
  Cooldown de curto prazo: você atingiu o limite por usuário (1 requisição / 5s) ou por aplicação (1 requisição / 180s). Aguarde um instante e tente novamente.
</ResponseField>

<ResponseField name="DAILY_SNAPSHOTS_LIMIT_REACHED" type="429">
  Cota diária atingida: a conta esgotou o limite diário de snapshots do plano ((RAM / 256) × 2 por 24h). A cota é renovada conforme a janela de 24 horas avança; para um limite diário maior, faça upgrade do plano.
</ResponseField>

<ResponseExample>
  ```json 200 Success theme={"system"}
  {
      "status": "success",
      "response": {
          "url": "https://snapshots.squarecloud.app/applications/23457145698959364/a23d130fcc9ddaf2d288ae9599a4292c32.zip?AWSAccessKeyId=i06Xdad2dRD74Pm8Xly&Expires=1753081182&Signature=riWPedawcsouRAPGU5n3kGHnWoOuw%3D",
          "key": "AWSAccessKeyId=i06Xdad2dRD74Pm8Xly&Expires=1753081182&Signature=riWPedawcsouRAPGU5n3kGHnWoOuw%3D"
      }
  }
  ```

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

  ```json 429 KEEP_CALM theme={"system"}
  {
    "status": "error",
    "code": "KEEP_CALM",
    "message": "You already requested a snapshot recently. Please wait a minute before trying again. 1r/5s"
  }
  ```

  ```json 429 DAILY_SNAPSHOTS_LIMIT_REACHED theme={"system"}
  {
    "status": "error",
    "code": "DAILY_SNAPSHOTS_LIMIT_REACHED",
    "message": "You are being rate limited for daily snapshots. 8r/24h"
  }
  ```
</ResponseExample>

## Relacionados

* CLI: [`squarecloud app snapshot create`](/pt-br/cli-reference/snapshots#squarecloud-app-snapshot-create)
* SDKs: [`api.apps.snapshots.create()`](/pt-br/sdks/js/snapshots) (JavaScript), [`client.apps.snapshots.create()`](/pt-br/sdks/py/snapshots) (Python), [`c.Apps.Snapshots.Create()`](/pt-br/sdks/go/snapshots) (Go)


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