File
Upload files (base64) and attach/detach them to records
INFO
Every response arrives in the shared envelope — code, message, messages, status_code, time — with the payload in data. The tables below describe what is inside data.
POST /file/upload
Upload a file as base64. Stores it in object storage and returns the storage key (a string in data). Use that key as the file field (e.g. path, image) when creating/updating a record, or pass it to /file/attach. base64-only — no remote URL fetching (no SSRF).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
filename | string | Yes | Original file name including extension. The extension is used to derive the storage key and (if mimetype is omitted) the content type. |
content_base64 | string | Yes | File bytes encoded as base64 (no data: URI prefix). Max ~20MB after decoding. base64-only by design — the API never fetches a remote URL, so there is no SSRF surface. |
mimetype | string | No | Optional MIME type. If omitted it is inferred from the filename extension, falling back to application/octet-stream. |
{
"filename": "receipt.pdf",
"content_base64": "JVBERi0xLjQKJeLjz9MK...",
"mimetype": "application/pdf"
}Response
{
"code": 0,
"message": "Success",
"status_code": 200,
"data": "/uploads/665f.../integration/file-abc123.pdf",
"time": "2025-05-01T12:00:00Z"
}POST /file/attach
Attach an already-uploaded file (its storage key) to an existing record. Body: path (the key) plus exactly one entity FK id (e.g. transaction_id, invoice_id). The referenced record must exist and the file must already be uploaded.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
path | string | Yes | Storage key returned by /file/upload. |
type | string | No | Optional. Inferred from the file extension when omitted.. One of: image, video, audio, file |
name | string | No | Optional display name. |
note | string | No | Optional note. |
transaction_id | string | No | Attach to a finance transaction. |
invoice_id | string | No | Attach to an invoice. |
category_id | string | No | Attach to a product category. |
task_id | string | No | Attach to a task. |
purchase_id | string | No | Attach to a purchase. |
supplier_id | string | No | Attach to a supplier. |
{
"path": "/uploads/665f.../integration/file-abc123.pdf",
"type": "image",
"name": "string",
"note": "string",
"transaction_id": "string",
"invoice_id": "string",
"category_id": "string",
"task_id": "string",
"purchase_id": "string",
"supplier_id": "string"
}Response
| Field | Type | Description |
|---|---|---|
_id | string | |
path | string | |
type | string | |
size | number |
{
"code": 0,
"message": "Success",
"status_code": 200,
"data": {
"_id": "string",
"path": "string",
"type": "string",
"size": 0
},
"time": "2025-05-01T12:00:00Z"
}DELETE /file/attach/{id}
Soft-delete an attachment by its ObjectId (detach a file from a record). Returns the deleted attachment id.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Attachment ObjectId to detach |
Request body
No request body.
Response
{
"code": 0,
"message": "Success",
"status_code": 200,
"data": "string",
"time": "2025-05-01T12:00:00Z"
}This page is generated from the OpenAPI spec.