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

# Enviar um arquivo para o Blob Storage

> Envie um arquivo de até 100 MB para o Blob Storage com POST /v1/objects: público ou privado, com opções de expiração, cache, metadados e checksum.

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

O Envio de Objeto faz o upload de um arquivo e retorna o seu `id` e, para arquivos públicos, uma `url` da CDN que você pode incorporar ou compartilhar diretamente. Ele dá suporte a anexos, exportações geradas e mídias enviadas por usuários em aplicações hospedadas na plataforma.

Uma única requisição aceita arquivos de 512 bytes até 100 MB. Arquivos maiores, até **10 GiB**, passam pelo [fluxo de upload em partes](/pt-br/blob-reference/endpoint/chunked-init) ou pelo [gateway S3](/pt-br/blob-reference/s3-compatibility). Exige o escopo `blob:write`, ou um [token de upload](/pt-br/blob-reference/endpoint/upload-tokens) enviado em `Authorization`, e um plano ativo.

<Note>
  Trate o `id` retornado como **opaco**: guarde-o como veio e envie-o de volta às outras rotas. Ele começa com `pub/` ou `prv/` e pode mudar quando o arquivo muda de visibilidade ou de expiração. Arquivos legados, armazenados antes da atualização de setembro de 2026, mantêm ids sem esse prefixo, e toda rota aceita os dois.
</Note>

## Parâmetros

<ParamField body="file" type="file" placeholder="logo.png" required>
  Use FormData (`multipart/form-data`), exatamente um arquivo por requisição.<br />Envie um nome de arquivo real: a extensão armazenada vem dele (`reads.fastq.gz` continua `.fastq.gz`).
</ParamField>

<ParamField query="name" type="string" placeholder="logo" required>
  O nome do arquivo, sem extensão. De 1 a 128 caracteres: letras, dígitos, `_`, `.` e `-`, começando com uma letra, um dígito ou `_`. Não pode conter `..`.
</ParamField>

<ParamField query="prefix" type="string" placeholder="images/2026">
  O caminho da pasta do arquivo, com até 8 segmentos separados por `/` e 256 caracteres no total. Cada segmento segue o mesmo padrão de `name`, com até 64 caracteres. Uma `/` no final é ignorada.
</ParamField>

<ParamField query="private" type="boolean" default="false">
  `true` armazena o arquivo sem URL pública. Leia-o pelo [Download de Objeto](/pt-br/blob-reference/endpoint/download), por um [link de compartilhamento](/pt-br/blob-reference/endpoint/shares-create) ou pelo [gateway S3](/pt-br/blob-reference/s3-compatibility). Quando omitido, a [regra do prefixo](/pt-br/blob-reference/endpoint/settings-put) decide.
</ParamField>

<ParamField query="expire" type="string" placeholder="30d">
  Exclui o arquivo automaticamente depois desse tempo: `30` ou `30d` para dias, `6h` para horas. De 1 hora a 1825 dias (5 anos). Expirações abaixo de 7 dias exigem o plano Enterprise. Quando omitido, a regra do prefixo decide.
</ParamField>

<ParamField query="security_hash" type="boolean" default="false">
  `true` adiciona um sufixo aleatório ao nome, para que a URL não possa ser adivinhada e um novo upload nunca substitua um antigo. Arquivos privados sempre o recebem (`false` junto com `private=true` é recusado).
</ParamField>

<ParamField query="overwrite" type="boolean" default="true">
  Sem security hash, um novo upload com o mesmo nome e prefixo substitui o arquivo. `false` o recusa com `409 OBJECT_ALREADY_EXISTS`.
</ParamField>

<ParamField query="disposition" type="string" placeholder="attachment">
  `inline` (abre no navegador) ou `attachment` (download, com o nome original do arquivo).
</ParamField>

<ParamField query="auto_download" type="boolean" default="false">
  `true` faz os navegadores baixarem o arquivo em vez de abri-lo, seja qual for o tipo.
</ParamField>

<ParamField query="cache_control" type="string" placeholder="max-age=3600">
  Por quanto tempo a CDN e os navegadores mantêm o arquivo: `immutable` (1 ano), `max-age=N` com N de 60 a 31536000 segundos, ou `no-cache` (toda leitura vai ao armazenamento; somente Enterprise). Arquivos com security hash usam `immutable` por padrão. O cache nunca dura mais que a expiração do arquivo.
</ParamField>

<ParamField query="metadata" type="string" placeholder="{&#x22;order&#x22;:&#x22;8812&#x22;}">
  Um objeto JSON de valores string, retornado pelo [Informações do Objeto](/pt-br/blob-reference/endpoint/info). As chaves usam `a-z`, `0-9` e `-` (até 64 caracteres). Até 5 chaves e 512 bytes no total. Somente Pro e Enterprise.
</ParamField>

<ParamField query="checksum_sha256" type="string" placeholder="64 lowercase hex characters">
  O SHA-256 do arquivo. Quando não corresponde, o upload é recusado com `CHECKSUM_MISMATCH` e nada é armazenado.
</ParamField>

## Limites de taxa e concorrência

<Note>
  * Cada conta pode ter no máximo **4 uploads em andamento** ao mesmo tempo (`TOO_MANY_CONCURRENT_UPLOADS`, 429).
  * Os planos **Hobby** e **Standard** são limitados a **1 upload por segundo** (`RATE_LIMITED`, 429). **Pro** e **Enterprise** são isentos.
  * Uploads acima do armazenamento incluído da conta são recusados com `STORAGE_QUOTA_EXCEEDED`.
</Note>

## Tipos de arquivo

Praticamente qualquer extensão é aceita, incluindo formatos sem tipo MIME registrado (`.bam`, `.vcf`, `.fasta`, `.parquet`, `.h5`, `.npy` e assim por diante).

* O `Content-Type` servido é derivado no servidor a partir da extensão. Formatos desconhecidos são servidos como `application/octet-stream`.
* Formatos que um navegador renderiza (`.html`, `.svg`, `.xml` e similares) são sempre servidos como download.
* Executáveis e instaladores são recusados com `BLOCKED_FILE_TYPE`: `exe`, `msi`, `dll`, `bat`, `cmd`, `com`, `scr`, `cpl`, `pif`, `hta`, `vbs`, `vbe`, `jse`, `wsf`, `wsh`, `msc`, `reg`, `lnk`, `sys`, `drv`, `ps1`, `apk`, `xpi`.
* Uma [regra do prefixo](/pt-br/blob-reference/endpoint/settings-put) ou um token de upload pode restringir as extensões e o tamanho aceitos.

## Resposta

<ResponseField name="status" type="string">
  "success" se bem-sucedida, "error" caso contrário.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Alternar objeto">
    <ResponseField name="id" type="string">
      O id do objeto: `pub/<user_id>/<path>` ou `prv/<user_id>/<path>`. Trate-o como opaco.
    </ResponseField>

    <ResponseField name="private" type="boolean">
      Se o arquivo é privado.
    </ResponseField>

    <ResponseField name="url" type="string | null">
      A URL pública da CDN (`https://blob.squarecloud.dev/pub/...`), ou `null` para arquivos privados.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601">
      Quando o arquivo será excluído. Presente apenas quando ele expira.
    </ResponseField>

    <ResponseField name="size" type="number">
      O tamanho do arquivo, em bytes.
    </ResponseField>

    <ResponseField name="name" type="string">
      O nome enviado na requisição.
    </ResponseField>

    <ResponseField name="prefix" type="string">
      O prefixo, quando um foi enviado.
    </ResponseField>

    <ResponseField name="sha256" type="string">
      O SHA-256 do arquivo armazenado, em hexadecimal.
    </ResponseField>

    <ResponseField name="replaced" type="boolean">
      `true` quando o upload substituiu um arquivo existente com o mesmo nome.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl --request POST \
    --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \
    --header 'Authorization: YOUR_API_KEY' \
    --form 'file=@./logo.png'
  ```

  ```javascript JavaScript theme={"system"}
  import fs from 'node:fs';

  const form = new FormData();
  form.append('file', new Blob([fs.readFileSync('./logo.png')]), 'logo.png');

  const params = new URLSearchParams({
    name: 'logo',
    prefix: 'images',
    security_hash: 'true',
  });

  const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
    method: 'POST',
    headers: { Authorization: 'YOUR_API_KEY' },
    body: form,
  });
  ```

  ```python Python theme={"system"}
  import requests

  with open('logo.png', 'rb') as f:
      response = requests.post(
          'https://blob.squarecloud.app/v1/objects',
          headers={'Authorization': 'YOUR_API_KEY'},
          params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'},
          files={'file': ('logo.png', f, 'image/png')},
      )
  ```
</RequestExample>

<ResponseExample>
  ```json Arquivo público theme={"system"}
  {
      "status": "success",
      "response": {
          "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
          "private": false,
          "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
          "size": 416230,
          "name": "logo",
          "prefix": "images",
          "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
          "replaced": false
      }
  }
  ```

  ```json Arquivo privado theme={"system"}
  {
      "status": "success",
      "response": {
          "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf",
          "private": true,
          "url": null,
          "size": 88412,
          "name": "2026-09",
          "prefix": "invoices",
          "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
          "replaced": false
      }
  }
  ```
</ResponseExample>

## Erros

| Código | HTTP | Quando |
| - | - | - |
| `INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX` | 400 | `name` ou `prefix` não corresponde ao padrão. |
| `INVALID_OBJECT_EXPIRE` | 400 | `expire` não é uma duração de 1 hora a 1825 dias. |
| `INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_OVERWRITE` / `INVALID_STORAGE_AUTO_DOWNLOAD` | 400 | A flag não é `true` nem `false`. |
| `INVALID_OBJECT_SECURITY_HASH` | 400 | Não é um booleano, ou é `false` em um arquivo privado. |
| `INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_METADATA` / `INVALID_CHECKSUM` | 400 | O valor está fora das formas aceitas. |
| `INVALID_FILE` / `INVALID_FILE_TYPE` / `BLOCKED_FILE_TYPE` / `FILE_TYPE_NOT_ALLOWED` | 400 | A parte do arquivo está ausente, a extensão está malformada ou bloqueada, ou a regra ou o token não a permite. |
| `FILE_TOO_SMALL` | 400 | O arquivo tem menos de 512 bytes. |
| `CHECKSUM_MISMATCH` | 400 | O arquivo não corresponde a `checksum_sha256`. Nada foi armazenado. |
| `PERMISSION_DENIED` | 401 | A conta não tem um plano ativo. |
| `UPLOAD_TOKEN_USED` | 401 | O token de upload não tem mais usos. Um token expirado responde `ACCESS_DENIED`. |
| `STORAGE_QUOTA_EXCEEDED` | 403 | O upload ultrapassaria o armazenamento incluído. |
| `PREFIX_NOT_ALLOWED` | 403 | O token de upload está vinculado a outro prefixo. |
| `UPGRADE_REQUIRED` | 403 | Uma opção exige um plano superior. A `message` indica qual. |
| `ACCOUNT_BLOCKED` | 403 | A conta está bloqueada para armazenar arquivos. |
| `INVALID_CONTENT_TYPE` | 409 | A requisição não é `multipart/form-data`. |
| `OBJECT_ALREADY_EXISTS` | 409 | O nome já existe e `overwrite=false`. |
| `FILE_TOO_LARGE` | 413 | Acima de 100 MB, ou acima do tamanho permitido pela regra ou pelo token. |
| `RATE_LIMITED` / `TOO_MANY_CONCURRENT_UPLOADS` | 429 | 1 upload por segundo (Hobby e Standard), ou 4 em andamento. |
| `UPLOAD_FAILED` | 500 | O armazenamento falhou. Tente novamente. |
| `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | 503 | O armazenamento está temporariamente indisponível. Tente novamente. |

Veja [Erros](/pt-br/blob-reference/errors) para a lista completa.

## Relacionados

* SDK do Blob: [`blob.put()`](/pt-br/sdks/blob/uploads)


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