File Management API

These endpoints manage files and media in your EverShop store. All file management endpoints require admin authentication.

File Operations

Browse Files

Lists the contents of a directory. The path after /files/ specifies which directory to browse. Sub-directories and files are returned in separate keys: folders is a flat list of directory names, files carries a name and a servable URL.

Request Schema (application/json)

No request body required

GET/api/files/{path}

cURL

curl
  -H "Accept: application/json"
  -H "Authorization: Bearer <admin JWT token>"
  https://<your domain>/api/files/{path}

JavaScript

fetch('https://<your domain>/api/files/{path}', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer <admin JWT token>'
  }
})
  .then(response => response.json())
  .then(data => {
    if(data.error) {
      // Handle the error
    } else {
      // Handle the data
    }
  })
  .catch(error => {
    // Handle the error
  });

Sample Of Response

{
"data": {
  "folders": [
    "thumbnails"
  ],
  "files": [
    {
      "name": "product-image.jpg",
      "url": "/assets/catalog/products/product-image.jpg"
    }
  ]
}
}

---

Upload File

Uploads one or more files to the specified directory. Send them as multipart form data under the field name images — up to 20 per request. The path segment must match ^[a-zA-Z0-9_/-]+$.

Request Schema (application/json)

No request body required

POST/api/files/{path}

cURL

curl
  -H "Accept: application/json"
  -H "Authorization: Bearer <admin JWT token>"
  --data-raw '<JSON DATA>'
  https://<your domain>/api/files/{path}

JavaScript

fetch('https://<your domain>/api/files/{path}', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer <admin JWT token>'
  },
  body: <JSON DATA>
})
  .then(response => response.json())
  .then(data => {
    if(data.error) {
      // Handle the error
    } else {
      // Handle the data
    }
  })
  .catch(error => {
    // Handle the error
  });

Sample Of Response

{
"data": {
  "files": [
    {
      "name": "uploaded-file.pdf",
      "mimetype": "application/pdf",
      "size": 102400,
      "url": "/assets/documents/uploaded-file.pdf"
    }
  ]
}
}

---

Delete File

Deletes a file at the specified path.

Request Schema (application/json)

No request body required

DELETE/api/files/{path}

cURL

curl
  -H "Accept: application/json"
  -H "Authorization: Bearer <admin JWT token>"
  https://<your domain>/api/files/{path}

JavaScript

fetch('https://<your domain>/api/files/{path}', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer <admin JWT token>'
  }
})
  .then(response => response.json())
  .then(data => {
    if(data.error) {
      // Handle the error
    } else {
      // Handle the data
    }
  })
  .catch(error => {
    // Handle the error
  });

Sample Of Response

{
"data": {
  "path": "catalog/my-image.png"
}
}

---

Image Operations

Upload Image

Identical to POST /api/files/{path} except that every uploaded file must have an image/* mimetype — anything else is rejected with 400 Only images are allowed.

No processing happens on upload: files are written as received. There is no resizing and no thumbnail generation. (Resizing is done on read by the storefront image processor, from the original.)

Request Schema (application/json)

No request body required

POST/api/images/{path}

cURL

curl
  -H "Accept: application/json"
  -H "Authorization: Bearer <admin JWT token>"
  --data-raw '<JSON DATA>'
  https://<your domain>/api/images/{path}

JavaScript

fetch('https://<your domain>/api/images/{path}', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer <admin JWT token>'
  },
  body: <JSON DATA>
})
  .then(response => response.json())
  .then(data => {
    if(data.error) {
      // Handle the error
    } else {
      // Handle the data
    }
  })
  .catch(error => {
    // Handle the error
  });

Sample Of Response

{
"data": {
  "files": [
    {
      "name": "product-photo.jpg",
      "mimetype": "image/jpeg",
      "size": 88120,
      "url": "/assets/catalog/products/product-photo.jpg"
    }
  ]
}
}

---

Folder Operations

Create Folder

Creates a new directory in the media storage.

Request Schema (application/json)

Field Name	Field Type	Required
path	string	Yes

POST/api/folders

cURL

curl
  -H "Accept: application/json"
  -H "Authorization: Bearer <admin JWT token>"
  --data-raw '<JSON DATA>'
  https://<your domain>/api/folders

JavaScript

fetch('https://<your domain>/api/folders', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer <admin JWT token>'
  },
  body: <JSON DATA>
})
  .then(response => response.json())
  .then(data => {
    if(data.error) {
      // Handle the error
    } else {
      // Handle the data
    }
  })
  .catch(error => {
    // Handle the error
  });

Sample Of Response

{
"data": {
  "path": "catalog/new-folder",
  "name": "new-folder"
}
}