Skip to main content
POST
Upload Large File - Step 1: Sign
Use este endpoint sempre que o arquivo for maior que 32 MB. Para arquivos de até 32 MB, o endpoint single-shot POST /files é mais simples e continua suportado.

Como funciona

O corpo do arquivo é enviado diretamente do cliente para o Google Cloud Storage usando uma URL PUT assinada V4 de curta duração — os bytes nunca passam pelo servidor da API, o que permite que o endpoint aceite arquivos de até 200 MB. Um único upload são três chamadas do cliente:
  1. POST /v2/files/sign — a API gera uma URL PUT assinada para o GCS válida por ~15 minutos e retorna os headers que o cliente deve repetir no PUT.
  2. PUT do corpo do arquivo diretamente para a uploadUrl retornada. O PUT carrega exatamente os headers de requiredHeaders — nem mais, nem menos — eles estão vinculados à assinatura V4, então um header faltando, extra ou diferente faz o GCS rejeitar o PUT com 403.
  3. POST /v2/files/register — a API verifica o tamanho do objeto enviado contra o que você declarou no /sign, move-o server-side da área de staging temporária para o local final, faz deduplicação por hash de conteúdo, e retorna o FileDTO padrão (mesmo formato de POST /files).

Etapa 2 — PUT direto para o Google Cloud Storage

Envie exatamente os headers retornados em requiredHeaders (atualmente Content-Type e x-goog-if-generation-match):
cURL
O GCS retorna 200 em caso de sucesso. O header x-goog-if-generation-match: 0 torna o PUT create-only — re-execuções retornam 412 Precondition Failed.

Etapa 3 — registrar o upload

Após o PUT ser bem-sucedido, finalize o upload. O tamanho declarado não precisa ser enviado de novo — o servidor lembra o size que você declarou no /sign (por ~16 minutos) e o compara com o objeto realmente enviado:
cURL
Retorna 201 com o FileDTO padrão. Se um arquivo com conteúdo idêntico já existir no workspace, a API retorna 200 com o FileDTO do arquivo existente em vez de criar uma duplicata. O campo opcional process funciona exatamente como em POST /files.

Arquivos suportados

Os mesmos de POST /files — Texto, Word, Planilha, PDF, Excel, PowerPoint, Imagem, Vídeo, Áudio e mais de 30 extensões de código.

Limites

  • Tamanho máximo por upload: 200 MB
  • Um arquivo por fluxo (execute as três etapas novamente para arquivos adicionais)
  • Limite de armazenamento: 30 arquivos

Erros

Cabeçalhos

integer
obrigatório
ID do workspace. Obrigatório a partir de 01/09/2026. Até lá, se omitido, usa o workspace selecionado do usuário (deprecated). Após a data, ausência → 422.

Autorizações

Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Cabeçalhos

x-workspace-id
integer
obrigatório

Workspace ID. Required as of 2026-09-01. Until then, if omitted, the user's selected workspace is used (deprecated). After the cutoff, a missing header returns 422.

Corpo

application/json
filename
string
obrigatório

Original filename including extension (e.g. report.pdf). Used to derive the stored extension.

content_type
string
obrigatório

MIME type of the file. Bound into the signed URL - the client MUST PUT with exactly this Content-Type header.

size
integer
obrigatório

Declared file size in bytes. The server remembers this value and /register rejects the upload if the actual uploaded object is larger than declared. Hard maximum: 200 MB (209715200 bytes).

Resposta

Signed PUT URL minted.

uploadUrl
string<uri>

Pre-signed Google Cloud Storage PUT URL. Valid for ~15 minutes.

objectPath
string

GCS object path the file will land at. Pass this back to POST /v2/files/register.

requiredHeaders
object

Headers the client MUST send on the PUT - bound into the V4 signature. Contains exactly Content-Type (the value you declared) and x-goog-if-generation-match: 0 (create-only). Send these headers verbatim and do not add others.

finalUrl
string<uri>

Short-lived signed download URL (~3 hours) for the uploaded object. For a durable reference, use the url field of the FileDTO returned by POST /v2/files/register.