Update documentation content

2026-03-15 05:32:05 +01:00
parent 7d10f030f3
commit c0b92596ec
30 changed files with 1840 additions and 29 deletions
@@ -0,0 +1,99 @@
+---
+title: API Media POST | Datasquirel docs
+description: Upload a media file via the Datasquirel API
+page_title: Media POST
+page_description: Upload images and files to your Datasquirel media storage programmatically.
+---
+
+## Overview
+
+Use the Media POST endpoint to upload one or more files to your media storage. Files are stored in the folder you specify, and image thumbnails are generated automatically.
+
+## npm Package
+
+```javascript
+import datasquirel from "@moduletrace/datasquirel";
+import fs from "fs";
+
+// Read the file and convert to base64
+const fileBuffer = fs.readFileSync("./photo.jpg");
+const base64 = fileBuffer.toString("base64");
+
+const result = await datasquirel.media.add({
+    media: [
+        {
+            name: "photo.jpg",
+            base64: `data:image/jpeg;base64,${base64}`,
+        },
+    ],
+    folder: "profile-images",
+    type: "image",
+    apiKey: process.env.DATASQUIREL_API_KEY,
+});
+
+console.log(result.payload); // Uploaded media object(s)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `media` | `array` | Yes | Array of files to upload. Each item has a `name` and `base64` string |
+| `folder` | `string` | No | Destination folder name. Created automatically if it does not exist |
+| `type` | `string` | Yes | File type — `"image"`, `"video"`, `"audio"`, or `"file"` |
+| `apiKey` | `string` | No | API key. Falls back to `DATASQUIREL_API_KEY` |
+
+### media Array Items
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | The file name including extension (e.g. `"photo.jpg"`) |
+| `base64` | `string` | Base64-encoded file data. Must include the data URL prefix (e.g. `data:image/jpeg;base64,...`) |
+
+## REST API
+
+```
+POST /api/v1/media
+```
+
+**Headers:**
+```
+Authorization: Bearer YOUR_API_KEY
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+    "media": [
+        {
+            "name": "photo.jpg",
+            "base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
+        }
+    ],
+    "folder": "profile-images",
+    "type": "image"
+}
+```
+
+## Response
+
+```json
+{
+    "success": true,
+    "payload": [
+        {
+            "id": 23,
+            "name": "photo.jpg",
+            "folder": "profile-images",
+            "url": "https://your-instance.com/media/profile-images/photo.jpg"
+        }
+    ]
+}
+```
+
+## Notes
+
+- A **Full Access** API key is required. Read-only keys cannot upload files.
+- Image thumbnails are generated automatically and stored alongside the original.
+- Uploading a file with the same name as an existing file in the same folder will overwrite it if `update: true` is passed.