Skip to main content
The Media API gives you programmatic access to the NodeForgeCMS media library — the centralised store for all images, documents, and binary files used across your site. You can list existing assets to build custom pickers or integrations, and upload new files directly from your application or CI pipeline. Uploaded files are stored on the server and their paths are returned immediately for use in article coverImage fields or any other content reference. All media endpoints require a valid Bearer token.

​
List Media Files

Returns a paginated list of all files in the media library. Requires a valid Bearer token. 
GET /api/media?page=1&limit=20
Authorization: Bearer YOUR_TOKEN

​
Query Parameters

​
page
number
Page number to retrieve. Defaults to 1.
​
limit
number
Number of items to return per page. Defaults to 10.

​
Response

{
  "code": 200,
  "data": {
    "list": [
      {
        "id": 1,
        "filename": "hero-image.jpg",
        "path": "/uploads/hero-image.jpg",
        "size": 245760,
        "mimeType": "image/jpeg",
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ],
    "total": 24
  },
  "message": "success"
}
FieldTypeDescription
idnumberUnique media file identifier
filenamestringOriginal filename as stored on the server
pathstringServer-relative path to the file (use this in article coverImage fields)
sizenumberFile size in bytes
mimeTypestringMIME type of the file (e.g. image/jpeg, image/png)
createdAtstringISO 8601 upload timestamp
totalnumberTotal number of files in the media library

​
Upload a File

Uploads a new file to the media library. Requires a valid Bearer token. The request must be sent as multipart/form-data with the binary file attached under the file field. 
POST /api/media/upload
Authorization: Bearer YOUR_TOKEN
Content-Type: multipart/form-data

file: <binary file data>

​
cURL Example

curl -X POST https://yourdomain.com/api/media/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/image.jpg"

​
Request Body

​
file
file
required
The binary file to upload, sent as a multipart/form-data field named file. The filename and MIME type are inferred from the submitted file.

​
Response

{
  "code": 200,
  "data": {
    "id": 25,
    "filename": "image.jpg",
    "path": "/uploads/image.jpg",
    "url": "https://yourdomain.com/uploads/image.jpg"
  },
  "message": "success"
}
FieldTypeDescription
idnumberUnique ID assigned to the new media record
filenamestringStored filename (may be normalised or de-duplicated by the server)
pathstringServer-relative path — use this value in article coverImage and other content fields
urlstringFully-qualified public URL to access the uploaded file directly
Supported file types: JPEG (.jpg, .jpeg), PNG (.png), GIF (.gif), and WebP (.webp). Uploads of unsupported MIME types will be rejected with a 400 error. The default maximum file size is 10 MB per upload — contact your system administrator to adjust this limit in the server configuration. Large images are not automatically resized; optimise images before uploading for best front-end performance.

​
Delete a Media File

Permanently removes a file from the media library and deletes it from the server filesystem. Requires a valid Bearer token. 
DELETE /api/media/25
Authorization: Bearer YOUR_TOKEN

​
Path Parameters

​
id
number
required
The numeric ID of the media file to delete.

​
Response

{
  "code": 200,
  "data": null,
  "message": "success"
}
Deleting a media file removes it from the filesystem immediately. Any articles or pages that reference the deleted file’s path will display broken images. Check all content referencing the file before deleting it.