Upload files

• Multipart upload sends the file to the Eigenpal app. Maintained clients use it while the complete request fits the deployment’s configured body limit.
• Storage-direct upload is selected for larger files when enabled and sends bytes directly to object storage instead of through a web function.

​

Archive capability matrix

​

File references: runs vs dataset archives

​

Storage-direct upload

curl https://api.eigenpal.com/v1/files/uploads \
  -H "Authorization: Bearer $EIGENPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "invoice.pdf",
    "contentType": "application/pdf",
    "size": 10485760
  }'

• uploadId and the reserved fileId
• an expiring url
• exact headers to include in the PUT
• expiresAt and maxFileSizeBytes

curl -X POST \
  "https://api.eigenpal.com/v1/files/uploads/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $EIGENPAL_API_KEY"

curl -X DELETE \
  "https://api.eigenpal.com/v1/files/uploads/$UPLOAD_ID" \
  -H "Authorization: Bearer $EIGENPAL_API_KEY"

​

Resumable multipart (multi-GB ZIP)

# 1. Create the session (size is metadata only — do not send the object here)
curl https://api.eigenpal.com/v1/files/uploads \
  -H "Authorization: Bearer $EIGENPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "bundle.bin",
    "contentType": "application/zip",
    "size": 5368709120
  }'

# 2. Resume: GET the authoritative part list
curl "https://api.eigenpal.com/v1/files/uploads/$UPLOAD_ID/parts" \
  -H "Authorization: Bearer $EIGENPAL_API_KEY"

# 3. Presign one missing part, PUT bytes to the returned URL, repeat
curl -X POST \
  "https://api.eigenpal.com/v1/files/uploads/$UPLOAD_ID/parts" \
  -H "Authorization: Bearer $EIGENPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"partNumber": 3}'

# 4. Complete from the server's part list (do not send client ETags)
curl -X POST \
  "https://api.eigenpal.com/v1/files/uploads/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $EIGENPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl https://api.eigenpal.com/v1/runs \
  -H "Authorization: Bearer $EIGENPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "wf_...",
    "input": {
      "bundle": { "$fileId": "file_..." }
    }
  }'

​

Multipart upload

curl https://api.eigenpal.com/v1/files \
  -H "Authorization: Bearer $EIGENPAL_API_KEY" \
  -F "file=@invoice.pdf"

​

Deployment behavior

1. A file within deployment.multipartMaxBytes returns transport: "multipart".
2. A larger file returns a signed upload when direct storage is enabled and reachable.
3. A local or private-storage deployment returns transport: "multipart" regardless of size when direct storage is disabled.
4. A failed signed transfer is retried as a signed transfer; clients do not automatically send the same large file through multipart.

deployment:
  multipartMaxBytes: 20971520 # 20 MiB

​

Run pre-uploads (purpose: run-input)

• TypeScript: new EigenpalClient({ multipartMaxBytes: 20 * 1024 * 1024 })
• Python: EigenpalClient(multipart_max_bytes=20 * 1024 * 1024)
• All maintained clients and the CLI: EIGENPAL_MULTIPART_MAX_BYTES=20971520

​

Studio builder attachments (purpose: builder-attachment)

​

Cleanup operation

• production has one Vercel Cron HTTP invocation every 15 minutes;
• staging reuses the existing daily reset workflow and makes one request before replacing its database;
• each invocation ends after its request, and creates no background task or service;
• one failed object does not abort other rows; its persisted cleanupAttemptedAt moves it out of the next batch for 15 minutes;
• a failed invocation leaves rows in the database for the next invocation, while bucket lifecycle removes old noncurrent versions as defense in depth.

​

Downloads

• When direct transfer is enabled, responses above deployment.multipartMaxBytes redirect to a short-lived exact-key signed storage GET that preserves safe Content-Type and Content-Disposition.
• On local/on-prem deployments, the API streams the bytes as before.
• Dynamically generated ZIP downloads (run artifact zip, dataset export) materialize to a cleanup-safe temporary object when needed, then redirect the same way.
• Cloud run-artifact ZIP assembly is capped at 32 MiB of uncompressed input so the Vercel function stays within memory and duration. The API checks cumulative object sizes (known metadata and/or storage HEAD) before downloading bodies; oversized sets return 413 with artifacts_zip_too_large — download files individually via GET /v1/runs/{id}/artifacts/{path}, or pass a smaller files= subset. On-prem/local keep a higher in-process ceiling.
• Cloud dataset export assembly uses the same 32 MiB source-byte budget and returns 413 dataset_too_large before downloading an oversized storage object. Export a selected example subset when the full dataset exceeds the limit.

​

API origins

EIGENPAL_API_KEY=eig_live_... \
EIGENPAL_BASE_URL=http://localhost:3000 \
bun smoke:direct-file-transfers

EIGENPAL_API_KEY=eig_live_... \
EIGENPAL_BASE_URL=https://sapi.eigenpal.com \
bun smoke:direct-file-transfers