Upload de Arquivo Grande
Envie arquivos de até 200 MB. O cliente faz upload do corpo do arquivo diretamente para o Google Cloud Storage usando uma URL PUT assinada de curta duração, e depois registra o upload na API.
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: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.PUTdo corpo do arquivo diretamente para auploadUrlretornada. O PUT carrega exatamente os headers derequiredHeaders— nem mais, nem menos — eles estão vinculados à assinatura V4, então um header faltando, extra ou diferente faz o GCS rejeitar o PUT com403.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 oFileDTOpadrão (mesmo formato de POST /files).
Etapa 2 — PUT direto para o Google Cloud Storage
Envie exatamente os headers retornados emrequiredHeaders (atualmente Content-Type e x-goog-if-generation-match):
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 osize que você declarou no /sign (por ~16 minutos) e o compara com o objeto realmente enviado:
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
Autorizações
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Cabeçalhos
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
Original filename including extension (e.g. report.pdf). Used to derive the stored extension.
MIME type of the file. Bound into the signed URL - the client MUST PUT with exactly this Content-Type header.
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.
Pre-signed Google Cloud Storage PUT URL. Valid for ~15 minutes.
GCS object path the file will land at. Pass this back to POST /v2/files/register.
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.
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.