Files · Publiczne REST API

List files in a category and scope

get/filesexperimentalWymagana sesja

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.

Parametry zapytania

Nazwa	Typ	Wymagane	Ograniczenia	Opis
category	FileCategory	Tak	enum`"grid_tile_icon""estimate_pdf"`	-
scopeId	string	Tak	-	The workshop id to list files for.

Odpowiedzi

200Success

Pole	Typ	Wymagane	Ograniczenia	Opis
files	array of FileRecord	Tak	-	-

Przykład

{
  "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
Brak treści.
401Not authenticated
Brak treści.
403Forbidden
Brak treści.

Przykładowe żądanie

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

Upload a file

post/filesexperimentalWymagana sesja

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.

Odpowiedzi

201Created

Pole	Typ	Wymagane	Ograniczenia	Opis
id	string	Tak	-	-
scope	FileScope	Tak	-	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	Tak	-	-
category	FileCategory	Tak	-	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	Nie	-	-
contentType	string	Tak	-	-
sizeBytes	integer	Tak	`minimum: -9007199254740991maximum: 9007199254740991`	-
uploadedByUid	string	Tak	-	-
createdAt	string	Tak	`format: "date-time"`	-
estimateId	string	Nie	-	Set only for files created against an estimate scope.

Przykład

{
  "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
Brak treści.
401Not authenticated
Brak treści.
403The caller is not a member of the workshop identified by scopeId
Brak treści.
413The file exceeds the 2 MB request cap, the category's own size limit, or the workshop's storage quota
Brak treści.
415The file's real content type is not one of the category's accepted types
Brak treści.

Przykładowe żądanie

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}experimentalWymagana sesja

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.

Parametry ścieżki

Nazwa	Typ	Wymagane	Ograniczenia	Opis
fileId	string	Tak	-	File id

Odpowiedzi

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.
Brak treści.
401Not authenticated
Brak treści.
403Forbidden
Brak treści.
404Not found
Brak treści.

Przykładowe żądanie

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