Magentrix Static Assets REST API v3.0 - Manage Files and Folders

The Static Assets REST API provides comprehensive endpoints for managing static files and folders within your Magentrix application's asset directory. These endpoints allow you to programmatically upload files, download assets, organize folder structures, and manage static resources such as images, stylesheets, JavaScript files, fonts, and other files.

Overview

Static assets are files stored in your Magentrix instance that support your application's functionality and presentation. The Static Assets REST API enables programmatic management of these resources through a RESTful interface, allowing developers to automate file operations, build asset management tools, and integrate with CI/CD pipelines.

What you can do with this API:

• Upload single or multiple files programmatically
• Download individual files or batch download as ZIP archives
• Create, rename, and delete folders and files
• Copy and move assets between directories
• List and filter assets by file type
• Manage images, CSS, JavaScript, fonts, and other web resources

All asset operations are performed within the /Contents/Assets/ directory structure of your Magentrix instance, ensuring secure and organized file management.

Authentication & Authorization

All Static Assets API endpoints require authentication via Bearer token. Additionally, the authenticated user must have either:

• Administrator privileges, OR
• "Asset Manager" permission assigned to their security role

Include the authentication token in the request header:

Authorization: Bearer {access_token}

💡 Note: See Get access token for details on obtaining your access token.

Quick Start Guide

Here's a typical workflow for managing static assets via the API:

1. Authenticate - Obtain your access token using your API key
2. List Assets - Browse existing files and folders in a directory
3. Upload Files - Add new assets to your instance
4. Organize - Create folders, move or copy files as needed
5. Download - Retrieve files individually or as batch ZIP downloads

Example: Upload and organize an image

# Step 1: Upload an image
curl POST 'https://{domain}/api/3.0/staticassets?path=/contents/assets/images'
  -H 'Authorization: Bearer {access_token}'
  -H 'Content-Type: multipart/form-data'
  -F 'file=@logo.png'

# Step 2: List assets to verify upload
curl GET 'https://{domain}/api/3.0/staticassets?path=/contents/assets/images'
  -H 'Authorization: Bearer {access_token}'

# Step 3: Move to a subfolder if needed
curl POST 'https://{domain}/api/3.0/staticassets/move?path=/contents/assets/images&targetPath=/contents/assets/images/logos&names=logo.png'
  -H 'Authorization: Bearer {access_token}'

Base URL

All Static Assets endpoints use the following base URL pattern:

https://{domain}/api/3.0/staticassets

Replace {domain} with your Magentrix instance domain.

Supported File Types

The API supports the following file categories:

Image Files

.gif, .png, .bmp, .jpg, .jpeg, .ico, .svg, .webp

Text and Script Files

.xml, .css, .js, .txt, .json, .md

Advanced Editable Files

.json, .xml, .css, .js, .txt, .ascx, .htm, .html

Font Files

.woff2, .woff, .eot, .ttf

Content Negotiation

The API supports content negotiation and can return responses in both JSON and XML formats based on the Accept header:

• application/json (default)
• application/xml

API Endpoints Summary

Asset Path Structure

All asset paths follow the structure: /Contents/Assets/...

Paths are case-insensitive and automatically normalized by the API.

API Endpoints

List Assets

Retrieves a list of files and folders in the specified directory. Use this endpoint to browse asset directories, filter by file type, and build file management interfaces.

Common use cases: Asset browsers, file pickers, directory navigation, inventory management

Endpoint:GET /api/3.0/staticassets

Query Parameters

Request Example

curl GET 'https://{domain}/api/3.0/staticassets?path=/contents/assets/images&fileTypes=jpg,png,gif'
  -H 'Authorization: Bearer {access_token}'
  -H 'Accept: application/json'

Response Example (JSON)

HTTP 200 OK

{
  "CurrentPath": "/contents/assets/images",
  "Assets": [
    {
      "Name": "thumbnails",
      "Type": "Folder",
      "Path": "/contents/assets/images/thumbnails",
      "Extention": null
    },
    {
      "Name": "logo.png",
      "Type": "File",
      "Path": "/contents/assets/images/logo.png",
      "Extention": "png",
      "Size": 15420
    }
  ]
}

Upload Assets

Uploads one or more files to the specified directory. Supports batch uploads with multiple files in a single request. Ideal for deployment automation, content migration, and bulk file operations.

Common use cases: Deployment pipelines, batch image uploads, content migration, build artifact deployment

Endpoint:POST /api/3.0/staticassets

Query Parameters

Request Headers

Content-Type: multipart/form-data

Request Example

curl POST 'https://{domain}/api/3.0/staticassets?path=/contents/assets/images'
  -H 'Authorization: Bearer {access_token}'
  -H 'Content-Type: multipart/form-data'
  -F 'file=@image1.jpg'
  -F 'file=@image2.png'

Success Response

HTTP 200 OK

{
  "Success": true,
  "UploadedFiles": [
    {
      "Name": "image1.jpg",
      "Size": 25600,
      "Path": "/contents/assets/images/image1.jpg"
    },
    {
      "Name": "image2.png",
      "Size": 18430,
      "Path": "/contents/assets/images/image2.png"
    }
  ],
  "Errors": []
}

Error Response

HTTP 200 OK (Partial Success)

{
  "Success": false,
  "UploadedFiles": [],
  "Errors": [
    "Failed to upload invalid-file.xyz: Unsupported file type for static assets: .xyz"
  ]
}

Download Assets

Downloads one or more files from your Magentrix instance. Single files are returned directly with appropriate content type; multiple files are automatically packaged as a ZIP archive for convenient batch download.

Common use cases: Asset backup, file exports, batch downloads, archive creation, file retrieval

Endpoint:GET /api/3.0/staticassets/download

Query Parameters

Single File Request Example

curl GET 'https://{domain}/api/3.0/staticassets/download?path=/contents/assets/images&names=logo.png'
  -H 'Authorization: Bearer {access_token}'
  -o logo.png

Multiple Files Request Example

curl GET 'https://{domain}/api/3.0/staticassets/download?path=/contents/assets/css&names=style.css,theme.css,print.css'
  -H 'Authorization: Bearer {access_token}'
  -o assets.zip

Response

• Single file: Returns the file with appropriate Content-Type and Content-Disposition headers
• Multiple files: Returns a ZIP file named assets.zip

Create Folder

Creates a new folder in the specified directory.

Endpoint:POST /api/3.0/staticassets/folder

Query Parameters

Request Example

curl POST 'https://{domain}/api/3.0/staticassets/folder?path=/contents/assets&name=new-folder'
  -H 'Authorization: Bearer {access_token}'

Response Example (JSON)

HTTP 201 Created

{
  "Name": "new-folder",
  "Path": "/contents/assets/new-folder",
  "Type": "Folder"
}

Rename Asset

Renames a file or folder.

Endpoint:PUT /api/3.0/staticassets/rename

Query Parameters

Request Example

curl PUT 'https://{domain}/api/3.0/staticassets/rename?path=/contents/assets/images&oldName=old-logo.png&newName=company-logo.png'
  -H 'Authorization: Bearer {access_token}'

Response Example (JSON)

HTTP 200 OK

{
  "Success": true,
  "OldName": "old-logo.png",
  "NewName": "company-logo.png",
  "Path": "/contents/assets/images/company-logo.png"
}

Delete Assets

Deletes one or more files or folders.

Endpoint:DELETE /api/3.0/staticassets

Query Parameters

Request Example

curl DELETE 'https://{domain}/api/3.0/staticassets?path=/contents/assets/temp&names=old-file.txt,unused-folder,obsolete-image.jpg'
  -H 'Authorization: Bearer {access_token}'

Response Example (JSON)

HTTP 200 OK

{
  "Success": true,
  "DeletedItems": [
    {
      "Name": "old-file.txt",
      "Type": "File"
    },
    {
      "Name": "unused-folder",
      "Type": "Folder"
    },
    {
      "Name": "obsolete-image.jpg",
      "Type": "File"
    }
  ],
  "Errors": []
}

Copy Assets

Copies files or folders to a different location.

Endpoint:POST /api/3.0/staticassets/copy

Query Parameters

Request Example

curl POST 'https://{domain}/api/3.0/staticassets/copy?path=/contents/assets/images&targetPath=/contents/assets/backup&names=logo.png,banner.jpg'
  -H 'Authorization: Bearer {access_token}'

Response Example (JSON)

HTTP 200 OK

{
  "Success": true,
  "CopiedItems": [
    {
      "Name": "logo.png",
      "Type": "File",
      "TargetPath": "/contents/assets/backup/logo.png"
    },
    {
      "Name": "banner.jpg",
      "Type": "File",
      "TargetPath": "/contents/assets/backup/banner.jpg"
    }
  ],
  "Errors": []
}

Move Assets

Moves files or folders to a different location.

Endpoint:POST /api/3.0/staticassets/move

Query Parameters

Request Example

curl POST 'https://{domain}/api/3.0/staticassets/move?path=/contents/assets/temp&targetPath=/contents/assets/archive&names=old-styles.css,deprecated-scripts'
  -H 'Authorization: Bearer {access_token}'

Response Example (JSON)

HTTP 200 OK

{
  "Success": true,
  "MovedItems": [
    {
      "Name": "old-styles.css",
      "Type": "File",
      "TargetPath": "/contents/assets/archive/old-styles.css"
    },
    {
      "Name": "deprecated-scripts",
      "Type": "Folder",
      "TargetPath": "/contents/assets/archive/deprecated-scripts"
    }
  ],
  "Errors": []
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:

Error Response Format

When an error occurs, the API returns an error response with details:

{
  "message": "Error description",
  "success": false
}

For operations with partial success or failure (HTTP 206):

{
  "Success": false,
  "ProcessedItems": [
    {
      "Name": "file1.txt",
      "Type": "File"
    }
  ],
  "Errors": [
    "Failed to process file2.txt: File not found",
    "Failed to process file3.txt: Permission denied"
  ]
}

Best Practices

Path Handling

• All paths must be within the /Contents/Assets/ directory structure
• Paths are case-insensitive
• Use forward slashes (/) as path separators
• Avoid trailing slashes in path parameters

File Type Validation

• File type validation is enforced on uploads and renames
• Always check supported file types before uploading
• Use the fileTypes parameter when listing assets to filter results

Batch Operations

• Folder operations (copy/move) are recursive and include all contents
• The API creates destination directories automatically when moving assets
• ZIP downloads are automatically generated for multiple file requests

Error Handling

• Always check the Success field in responses
• Review the Errors array for detailed failure information
• Handle partial success scenarios (HTTP 206) appropriately

Common Use Cases

Asset Management Dashboard

# List all assets in a specific folder
curl GET 'https://{domain}/api/3.0/staticassets?path=/contents/assets/images'
  -H 'Authorization: Bearer {access_token}'

Batch Image Upload

# Upload multiple images at once
curl POST 'https://{domain}/api/3.0/staticassets?path=/contents/assets/gallery'
  -H 'Authorization: Bearer {access_token}'
  -H 'Content-Type: multipart/form-data'
  -F 'file=@photo1.jpg'
  -F 'file=@photo2.jpg'
  -F 'file=@photo3.jpg'

Asset Backup

# Copy entire folder contents to backup location
curl POST 'https://{domain}/api/3.0/staticassets/copy?path=/contents/assets/production&targetPath=/contents/assets/backup&names=styles,scripts,images'
  -H 'Authorization: Bearer {access_token}'

Download Multiple Files

# Download multiple CSS files as ZIP
curl GET 'https://{domain}/api/3.0/staticassets/download?path=/contents/assets/css&names=main.css,theme.css,responsive.css'
  -H 'Authorization: Bearer {access_token}'
  -o styles.zip

What's Next?

• Get your API Key
• Get access token
• Managing Static Assets in IDE

Frequently Asked Questions

What file types can I upload using the Static Assets API?

The API supports images (PNG, JPG, GIF, SVG, WEBP), scripts (JS, CSS), text files (TXT, JSON, MD, XML), HTML files (HTML, HTM, ASCX), and fonts (WOFF, WOFF2, TTF, EOT).

Do I need special permissions to use the Static Assets API?

Yes, you need either Administrator privileges or the "Asset Manager" permission assigned to your security role. All requests must include a valid Bearer authentication token.

Can I upload multiple files at once?

Yes, the upload endpoint supports multipart/form-data requests with multiple files. All files will be processed in a single API call, and the response will indicate which files succeeded and which failed.

How do I download multiple files as a ZIP?

Use the download endpoint with a comma-separated list of file names in the names parameter. The API automatically creates a ZIP archive when multiple files are requested.

Are folder operations recursive?

Yes, when you copy, move, or delete a folder, all of its contents (including nested folders and files) are processed recursively.

What happens if I try to upload an unsupported file type?

The API will reject unsupported file types and return an error message indicating that the file extension is not allowed. The response will include details in the Errors array.

Can I use this API to manage files outside the /Contents/Assets/ directory?

No, all operations are restricted to the /Contents/Assets/ directory structure for security reasons. Attempts to access paths outside this directory will fail.

How do I handle errors when multiple operations are performed?

Check the Success field in the response. If false, examine the Errors array for detailed error messages. For partial success scenarios (HTTP 206), both ProcessedItems and Errors arrays will contain relevant information.

Is the API case-sensitive for file paths?

No, paths are case-insensitive and automatically normalized by the API. However, it's recommended to use consistent casing for better code maintainability.

Can I use this API for automated deployment pipelines?

Yes, the Static Assets API is ideal for CI/CD pipelines, automated deployments, and bulk asset management. Use it to upload build artifacts, update stylesheets, deploy JavaScript bundles, and manage other static resources programmatically.