Subir Archivo Grande
Sube archivos de hasta 200 MB. El cliente envía el cuerpo del archivo directamente a Google Cloud Storage con una URL PUT firmada de corta duración, y después registra la carga en la API.
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: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.PUTdel cuerpo del archivo directamente a lauploadUrldevuelta. El PUT lleva exactamente los headers derequiredHeaders— 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 con403.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 elFileDTOestándar (mismo formato que POST /files).
Paso 2 — PUT directo a Google Cloud Storage
Envíe exactamente los headers devueltos enrequiredHeaders (actualmente Content-Type y x-goog-if-generation-match):
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 elsize que declaraste en /sign (por ~16 minutos) y lo compara con el objeto realmente subido:
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
Autorizaciones
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Encabezados
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
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).
Respuesta
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.