Files · Public REST API

List files in a category and scope

get/filesexperimentalSession only

Both category and scopeId are required; there is no unscoped listing. Responds 403 when the caller is not a member of the workshop identified by scopeId.

Query parameters

Name	Type	Required	Constraints	Description
category	FileCategory	Yes	enum`"grid_tile_icon""estimate_pdf"`	-
scopeId	string	Yes	-	The workshop id to list files for.

Responses

200Success

Field	Type	Required	Constraints	Description
files	array of FileRecord	Yes	-	-

Example

{
  "files": [
    {
      "id": "file-1",
      "scope": "workshop",
      "scopeId": "workshop-1",
      "category": "grid_tile_icon",
      "name": "chisel-icon.png",
      "contentType": "image/png",
      "sizeBytes": 48213,
      "uploadedByUid": "uid-1",
      "createdAt": "2026-08-05T10:15:00.000Z"
    }
  ]
}

400category or scopeId is missing or invalid
No body.
401Not authenticated
No body.
403Forbidden
No body.

Example request

curl -X GET 'https://mercastra.cloud/api/files?category=<category>&scopeId=<scopeId>' \
  -H 'Cookie: session=<session cookie>'

Upload a file

post/filesexperimentalSession only

Uploads a file for a category and stores it against the workshop identified by scopeId. The response is the stored file's own record; this endpoint never assigns the file to anything else, a later request (for example a grid button patch) references it by id. Every upload also counts against the workshop's plan storage quota (10 MB on Free, 250 MB on paid plans) and the request itself is capped at 2 MB regardless of category, on top of the category's own per-file cap. 413 covers all three limits with an empty body; nothing in the response distinguishes which one was hit. The file's actual type is detected from its bytes, not the client-supplied MIME type.

Responses

201Created

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
scope	FileScope	Yes	-	The kind of resource a file is authorized against: workshop or estimate. Both categories accepted by POST /files resolve to workshop; estimate-scoped files are created by other endpoints, not this one.
scopeId	string	Yes	-	-
category	FileCategory	Yes	-	What a file is used for. Decides the accepted content types and any per-file size cap: grid_tile_icon (an image attached to a grid button, up to 512 KB) or estimate_pdf (a generated estimate PDF, no per-file cap).
name	string	No	-	-
contentType	string	Yes	-	-
sizeBytes	integer	Yes	`minimum: -9007199254740991maximum: 9007199254740991`	-
uploadedByUid	string	Yes	-	-
createdAt	string	Yes	`format: "date-time"`	-
estimateId	string	No	-	Set only for files created against an estimate scope.

Example

{
  "id": "file-1",
  "scope": "workshop",
  "scopeId": "workshop-1",
  "category": "grid_tile_icon",
  "name": "chisel-icon.png",
  "contentType": "image/png",
  "sizeBytes": 48213,
  "uploadedByUid": "uid-1",
  "createdAt": "2026-08-05T10:15:00.000Z"
}

400category or scopeId is missing or invalid, name is longer than 255 characters, or no file was attached
No body.
401Not authenticated
No body.
403The caller is not a member of the workshop identified by scopeId
No body.
413The file exceeds the 2 MB request cap, the category's own size limit, or the workshop's storage quota
No body.
415The file's real content type is not one of the category's accepted types
No body.

Example request

curl -X POST 'https://mercastra.cloud/api/files' \
  -H 'Cookie: session=<session cookie>' \
  -H 'X-CSRF-Token: <csrf-token cookie value>'

Download a file's bytes

get/files/{fileId}experimentalSession only

Streams the stored bytes with Cache-Control: private, max-age=31536000, immutable - a file's bytes never change once uploaded, only its record can be deleted. Responds 403 when the caller does not have access to the scope owning the file and 404 when no such file exists.

Path parameters

Name	Type	Required	Constraints	Description
fileId	string	Yes	-	File id

Responses

200Success. The real Content-Type header reflects the file's actual type (one of image/jpeg, image/png, image/webp or application/pdf), not application/octet-stream.
No body.
401Not authenticated
No body.
403Forbidden
No body.
404Not found
No body.

Example request

curl -X GET 'https://mercastra.cloud/api/files/<fileId>' \
  -H 'Cookie: session=<session cookie>'