Skip to main content
POST
Upload Large File - Step 1: Sign
Use este endpoint siempre que el archivo sea mayor a 32 MB. Para archivos de hasta 32 MB, el endpoint single-shot POST /files es más simple y sigue siendo soportado.

Cómo funciona

El cuerpo del archivo se sube directamente desde el cliente a Google Cloud Storage usando una URL PUT firmada V4 de corta duración — los bytes nunca pasan por el servidor de la API, lo que permite que el endpoint acepte archivos de hasta 200 MB. Una sola carga son tres llamadas desde el cliente:
  1. POST /v2/files/sign — la API genera una URL PUT firmada para GCS válida por ~15 minutos y devuelve los headers que el cliente debe repetir en el PUT.
  2. PUT del cuerpo del archivo directamente a la uploadUrl devuelta. El PUT lleva exactamente los headers de requiredHeaders — ni más, ni menos — están vinculados a la firma V4, así que un header faltante, extra o distinto hace que GCS rechace el PUT con 403.
  3. POST /v2/files/register — la API verifica el tamaño del objeto subido contra lo que declaraste en /sign, lo mueve server-side del área de staging temporal a su ubicación final, deduplica por hash de contenido, y devuelve el FileDTO estándar (mismo formato que POST /files).

Paso 2 — PUT directo a Google Cloud Storage

Envíe exactamente los headers devueltos en requiredHeaders (actualmente Content-Type y x-goog-if-generation-match):
cURL
GCS devuelve 200 en caso de éxito. El header x-goog-if-generation-match: 0 hace el PUT create-only — reintentos devuelven 412 Precondition Failed.

Paso 3 — registrar la carga

Después de que el PUT termine con éxito, finalice la carga. El tamaño declarado no necesita enviarse de nuevo — el servidor recuerda el size que declaraste en /sign (por ~16 minutos) y lo compara con el objeto realmente subido:
cURL
Devuelve 201 con el FileDTO estándar. Si un archivo con contenido idéntico ya existe en el workspace, la API devuelve 200 con el FileDTO del archivo existente en lugar de crear un duplicado. El campo opcional process funciona exactamente igual que en POST /files.

Archivos soportados

Los mismos que POST /files — Texto, Word, Hoja de cálculo, PDF, Excel, PowerPoint, Imagen, Video, Audio y más de 30 extensiones de código.

Límites

  • Tamaño máximo por carga: 200 MB
  • Un archivo por flujo (ejecute las tres etapas otra vez para archivos adicionales)
  • Límite de almacenamiento: 30 archivos

Errores

Encabezados

integer
requerido
ID del workspace. Obligatorio a partir del 01/09/2026. Hasta entonces, si se omite, se usa el workspace seleccionado del usuario (deprecated). Después de la fecha, ausencia → 422.

Autorizaciones

Authorization
string
header
requerido

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

Encabezados

x-workspace-id
integer
requerido

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.

Cuerpo

application/json
filename
string
requerido

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

content_type
string
requerido

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

size
integer
requerido

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

Respuesta

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.