/files/upload-url

Live

Get a 5-minute presigned upload for a drawing, PO or photo

Records the file against its entity (entityType + entityId) and returns a presigned S3 POST that lives 5 minutes. Send upload.fields as multipart form fields, then the bytes as the last field file, to upload.url; the file never passes through Core. S3 itself refuses a different Content-Type or more bytes than sizeBytes. The file starts PENDING; a check job marks it READY (usually within seconds of the upload) or REJECTED, and only a READY file can be downloaded. Needs Authorization: Bearer <app token>, the file.upload permission and an Idempotency-Key: a retry by the same person with the same key returns the same file with a fresh signature while the upload can still finish in time. Types: JPEG, PNG, WebP, PDF, CSV, XLSX, DXF, STEP, with a name ending in the type's extension. Up to 25 MiB a file; 500 uploads or 2 GiB per shop in any 24 hours.

POST/files/upload-url

Who can call this. file.upload: owner, admin, accountant, supervisor, QC (operators: own jobs, once job cards exist).

Headers

Required Optional

X-Request-IdstringOptional
Your id for this request (8–128 characters of A–Z a–z 0–9 . _ : -). Echoed back in the response header and in every error, so you can quote it when reporting a problem. Core makes one if you send none.
Example: app-7f3c2a9e-checkout

Returns

A small JSON object; see the response examples on the right.

Errors

Code	HTTP	When
`FILE_TOO_LARGE`	`413`	`sizeBytes` is over the 25 MiB upload limit.
`FILE_TYPE_NOT_ALLOWED`	`415`	`contentType` is not a JPEG, PNG or WebP photo, PDF, CSV, XLSX, DXF or STEP file.
`VALIDATION_FAILED`	`400`	Input failed Zod or route schema validation. `details` lists each field path and problem.
`FILE_QUOTA_EXCEEDED`	`429`	The shop asked for more than 500 uploads or 2 GiB in the last 24 hours. The limit frees up as the day rolls on.
`FORBIDDEN`	`403`	Signed in, but the role or tenant does not allow the action.
`IDEMPOTENCY_KEY_REQUIRED`	`400`	A write from a device or retry-prone client was sent without the `Idempotency-Key` header.
`UNAUTHENTICATED`	`401`	No session, or the token is missing, expired or invalid.

Every error has the same body. See Errors.

Rate limit tier

Tier: per user. Over the limit you get RATE_LIMITED (HTTP 429) with a Retry-After header. See Response handling.

curl -X POST http://127.0.0.1:3000/files/upload-url \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {{tokenApp}}" \ -H "Idempotency-Key: {{\$guid}}" \ -d '{"entityType":"job_card","entityId":"0192f0c1-0000-7000-8000-0000000000c1","name":"Flange drawing rev B.pdf","contentType":"application/pdf","sizeBytes":482113}'

{ "file": { "id": "0192f0c1-0000-7000-8000-0000000000f1", "entityType": "job_card", "entityId": "0192f0c1-0000-7000-8000-0000000000c1", "name": "Flange drawing rev B.pdf", "contentType": "application/pdf", "sizeBytes": 482113, "status": "PENDING" }, "upload": { "url": "https://files-bucket.s3.ap-south-1.amazonaws.com/", "fields": { "Content-Type": "application/pdf", "bucket": "files-bucket", "X-Amz-Algorithm": "AWS4-HMAC-SHA256", "X-Amz-Credential": "SYNTHETICKEYID/20261013/ap-south-1/s3/aws4_request", "X-Amz-Date": "20261013T053000Z", "key": "t/0192f0c1-0000-7000-8000-00000000000a/2026/0192f0c1-7a3e-7c11-9f0e-5b2d8c1e4b01", "Policy": "eyJleHBpcmF0aW9uIjoiMjAyNi0xMC0xM1QwNTozNTowMFoifQ==", "X-Amz-Signature": "0000000000000000000000000000000000000000000000000000000000000000" }, "expiresAt": "2026-10-13T05:35:00.000Z" } }