Skip to content

Latest commit

 

History

History
2129 lines (1633 loc) · 75.2 KB

ASSETS.md

File metadata and controls

2129 lines (1633 loc) · 75.2 KB
Raw
Back to Pixelbin API docs

Assets Methods

Asset Uploader Service

Methods with example and description

addCredentials

Summary: Add credentials for a transformation module.

// Promise

const promise = assets.addCredentials({
    credentials: {
        region: "ap-south-1",
        accessKeyId: "123456789ABC",
        secretAccessKey: "DUMMY1234567890",
    },
    pluginId: "awsRek",
});

// Async/Await

const data = await assets.addCredentials({
    credentials: {
        region: "ap-south-1",
        accessKeyId: "123456789ABC",
        secretAccessKey: "DUMMY1234567890",
    },
    pluginId: "awsRek",
});
Argument Type Required Description
credentials string yes Credentials of the plugin
pluginId string yes Unique identifier for the plugin this credential belongs to

Add a transformation modules's credentials for an organization.

Returned Response:

AddCredentialsResponse

Success

  Example: 
{
    "_id": "123ee789-7ae8-4336-b9bd-e4f33c049002",
    "createdAt": "2022-10-04T09:52:09.545Z",
    "updatedAt": "2022-10-04T09:52:09.545Z",
    "orgId": 23,
    "pluginId": "awsRek"
}

updateCredentials

Summary: Update credentials of a transformation module.

// Promise

const promise = assets.updateCredentials({
    pluginId: "awsRek",
    credentials: {
        region: "ap-south-1",
        accessKeyId: "123456789ABC",
        secretAccessKey: "DUMMY1234567890",
    },
});

// Async/Await

const data = await assets.updateCredentials({
    pluginId: "awsRek",
    credentials: {
        region: "ap-south-1",
        accessKeyId: "123456789ABC",
        secretAccessKey: "DUMMY1234567890",
    },
});
Argument Type Required Description
pluginId string yes ID of the plugin whose credentials are being updated
credentials string yes Credentials of the plugin

Update credentials of a transformation module, for an organization.

Returned Response:

AddCredentialsResponse

Success

  Example: 
{
    "_id": "123ee789-7ae8-4336-b9bd-e4f33c049002",
    "createdAt": "2022-10-04T09:52:09.545Z",
    "updatedAt": "2022-10-04T09:52:09.545Z",
    "orgId": 23,
    "pluginId": "awsRek"
}

deleteCredentials

Summary: Delete credentials of a transformation module.

// Promise

const promise = assets.deleteCredentials({
    pluginId: "awsRek",
});

// Async/Await

const data = await assets.deleteCredentials({
    pluginId: "awsRek",
});
Argument Type Required Description
pluginId string yes ID of the plugin whose credentials are being deleted

Delete credentials of a transformation module, for an organization.

Returned Response:

AddCredentialsResponse

Success

  Example: 
{
    "_id": "123ee789-7ae8-4336-b9bd-e4f33c049002",
    "createdAt": "2022-10-04T09:52:09.545Z",
    "updatedAt": "2022-10-04T09:52:09.545Z",
    "orgId": 23,
    "pluginId": "awsRek"
}

getFileById

Summary: Get file details with _id

// Promise

const promise = assets.getFileById({
    _id: "c9138153-94ea-4dbe-bea9-65d43dba85ae",
});

// Async/Await

const data = await assets.getFileById({
    _id: "c9138153-94ea-4dbe-bea9-65d43dba85ae",
});
Argument Type Required Description
_id string yes _id of File

Returned Response:

FilesResponse

Success

  Example: 
{
    "_id": "dummy-uuid",
    "name": "asset",
    "path": "dir",
    "fileId": "dir/asset",
    "format": "jpeg",
    "size": 1000,
    "access": "private",
    "isActive": true,
    "tags": ["tag1", "tag2"],
    "metadata": {
        "key": "value"
    },
    "url": "https://domain.com/filename.jpeg"
}

getFileByFileId

Summary: Get file details with fileId

// Promise

const promise = assets.getFileByFileId({
    fileId: "path/to/file/name",
});

// Async/Await

const data = await assets.getFileByFileId({
    fileId: "path/to/file/name",
});
Argument Type Required Description
fileId string yes Combination of path and name of file

Returned Response:

FilesResponse

Success

  Example: 
{
    "_id": "dummy-uuid",
    "name": "asset",
    "path": "dir",
    "fileId": "dir/asset",
    "format": "jpeg",
    "size": 1000,
    "access": "private",
    "isActive": true,
    "tags": ["tag1", "tag2"],
    "metadata": {
        "key": "value"
    },
    "url": "https://domain.com/filename.jpeg"
}

updateFile

Summary: Update file details

// Promise

const promise = assets.updateFile({
    fileId: "path/to/file/name",
    name: "asset",
    path: "dir",
    access: "private",
    isActive: false,
    tags: ["tag1", "tag2"],
    metadata: { key: "value" },
});

// Async/Await

const data = await assets.updateFile({
    fileId: "path/to/file/name",
    name: "asset",
    path: "dir",
    access: "private",
    isActive: false,
    tags: ["tag1", "tag2"],
    metadata: { key: "value" },
});
Argument Type Required Description
fileId string yes Combination of path and name
name string no Name of the file
path string no Path of the file
access AccessEnum no Access level of asset, can be either public-read or private
isActive boolean no Whether the file is active
tags [string] no Tags associated with the file
metadata string no Metadata associated with the file

Returned Response:

FilesResponse

Success

  Example: 
{
    "_id": "dummy-uuid",
    "name": "asset",
    "path": "dir",
    "fileId": "dir/asset",
    "format": "jpeg",
    "size": 1000,
    "access": "private",
    "isActive": true,
    "tags": ["tag1", "tag2"],
    "metadata": {
        "key": "value"
    },
    "url": "https://domain.com/filename.jpeg"
}

deleteFile

Summary: Delete file

// Promise

const promise = assets.deleteFile({
    fileId: "path/to/file/name",
});

// Async/Await

const data = await assets.deleteFile({
    fileId: "path/to/file/name",
});
Argument Type Required Description
fileId string yes Combination of path and name

Returned Response:

FilesResponse

Success

  Example: 
{
    "_id": "dummy-uuid",
    "name": "asset",
    "path": "dir",
    "fileId": "dir/asset",
    "format": "jpeg",
    "size": 1000,
    "access": "private",
    "isActive": true,
    "tags": ["tag1", "tag2"],
    "metadata": {
        "key": "value"
    },
    "url": "https://domain.com/filename.jpeg"
}

deleteFiles

Summary: Delete multiple files

// Promise

const promise = assets.deleteFiles({
    ids: ["_id_1", "_id_2", "_id_3"],
});

// Async/Await

const data = await assets.deleteFiles({
    ids: ["_id_1", "_id_2", "_id_3"],
});
Argument Type Required Description
ids [string] yes Array of file _ids to delete

Returned Response:

[FilesResponse]

Success

  Example: 
[
    {
        "_id": "dummy-uuid",
        "name": "asset",
        "path": "dir",
        "fileId": "dir/asset",
        "format": "jpeg",
        "size": 1000,
        "access": "private",
        "isActive": true,
        "tags": ["tag1", "tag2"],
        "metadata": {
            "key": "value"
        },
        "url": "https://domain.com/filename.jpeg"
    }
]

createFolder

Summary: Create folder

// Promise

const promise = assets.createFolder({
    name: "subDir",
    path: "dir",
});

// Async/Await

const data = await assets.createFolder({
    name: "subDir",
    path: "dir",
});
Argument Type Required Description
name string yes Name of the folder
path string no Path of the folder

Create a new folder at the specified path. Also creates the ancestors if they do not exist.

Returned Response:

FoldersResponse

Success - List of all created folders

  Example: 
{
    "_id": "dummy-uuid",
    "name": "subDir",
    "path": "dir",
    "isActive": true
}

getFolderDetails

Summary: Get folder details

// Promise

const promise = assets.getFolderDetails({
    path: "dir1/dir2",
    name: "dir",
});

// Async/Await

const data = await assets.getFolderDetails({
    path: "dir1/dir2",
    name: "dir",
});
Argument Type Required Description
path string no Folder path
name string no Folder name

Get folder details

Returned Response:

exploreItem

Success

  Example: 
[
    {
        "_id": "dummy-uuid",
        "createdAt": "2022-10-05T10:43:04.117Z",
        "updatedAt": "2022-10-05T10:43:04.117Z",
        "name": "asset2",
        "type": "file",
        "path": "dir",
        "fileId": "dir/asset2",
        "format": "jpeg",
        "size": 1000,
        "access": "private",
        "metadata": {},
        "height": 100,
        "width": 100
    }
]

updateFolder

Summary: Update folder details

// Promise

const promise = assets.updateFolder({
    folderId: "path/to/folder/name",
    isActive: false,
});

// Async/Await

const data = await assets.updateFolder({
    folderId: "path/to/folder/name",
    isActive: false,
});
Argument Type Required Description
folderId string yes combination of path and name
isActive boolean no whether the folder is active

Update folder details. Eg: Soft delete it by making isActive as false. We currently do not support updating folder name or path.

Returned Response:

FoldersResponse

Success

  Example: 
{
    "_id": "dummy-uuid",
    "name": "subDir",
    "path": "dir",
    "isActive": true
}

deleteFolder

Summary: Delete folder

// Promise

const promise = assets.deleteFolder({
    _id: "c9138153-94ea-4dbe-bea9-65d43dba85ae",
});

// Async/Await

const data = await assets.deleteFolder({
    _id: "c9138153-94ea-4dbe-bea9-65d43dba85ae",
});
Argument Type Required Description
_id string yes _id of folder to be deleted

Delete folder and all its children permanently.

Returned Response:

FoldersResponse

Success

  Example: 
{
    "_id": "dummy-uuid",
    "name": "subDir",
    "path": "dir",
    "isActive": true
}

getFolderAncestors

Summary: Get all ancestors of a folder

// Promise

const promise = assets.getFolderAncestors({
    _id: "c9138153-94ea-4dbe-bea9-65d43dba85ae",
});

// Async/Await

const data = await assets.getFolderAncestors({
    _id: "c9138153-94ea-4dbe-bea9-65d43dba85ae",
});
Argument Type Required Description
_id string yes _id of the folder

Get all ancestors of a folder, using the folder ID.

Returned Response:

GetAncestorsResponse

Success

  Example: 
{
    "folder": {
        "_id": "dummy-uuid",
        "name": "subDir",
        "path": "dir1/dir2",
        "isActive": true
    },
    "ancestors": [
        {
            "_id": "dummy-uuid-2",
            "name": "dir1",
            "path": "",
            "isActive": true
        },
        {
            "_id": "dummy-uuid-2",
            "name": "dir2",
            "path": "dir1",
            "isActive": true
        }
    ]
}

listFiles

Summary: List and search files and folders.

// Promise

const promise = assets.listFiles({
    name: "cat",
    path: "cat-photos",
    format: "jpeg",
    tags: ["cats", "animals"],
    onlyFiles: "false",
    onlyFolders: "false",
    pageNo: "1",
    pageSize: "10",
    sort: "name",
});

// Async/Await

const data = await assets.listFiles({
    name: "cat",
    path: "cat-photos",
    format: "jpeg",
    tags: ["cats", "animals"],
    onlyFiles: "false",
    onlyFolders: "false",
    pageNo: "1",
    pageSize: "10",
    sort: "name",
});
Argument Type Required Description
name string no Find items with matching name
path string no Find items with matching path
format string no Find items with matching format
tags [string] no Find items containing these tags
onlyFiles boolean no If true will fetch only files
onlyFolders boolean no If true will fetch only folders
pageNo number no Page No.
pageSize number no Page Size
sort string no Key to sort results by. A "-" suffix will sort results in descending orders.

List all files and folders in root folder. Search for files if name is provided. If path is provided, search in the specified path.

Returned Response:

ListFilesResponse

Success

  Example: 
{
    "items": [
        {
            "_id": "dummy-uuid",
            "name": "dir",
            "type": "folder"
        },
        {
            "_id": "dummy-uuid",
            "name": "asset2",
            "type": "file",
            "path": "dir",
            "fileId": "dir/asset2",
            "format": "jpeg",
            "size": 1000,
            "access": "private"
        },
        {
            "_id": "dummy-uuid",
            "name": "asset1",
            "type": "file",
            "path": "dir",
            "fileId": "dir/asset1",
            "format": "jpeg",
            "size": 1000,
            "access": "private"
        }
    ],
    "page": {
        "type": "number",
        "size": 4,
        "current": 1,
        "hasNext": false
    }
}

listFilesPaginator

Summary: Paginator for listFiles

Paginator exposes hasNext and next methods to paginate through pages.

const paginator = assets.listFilesPaginator({
    name: "cat",
    path: "cat-photos",
    format: "jpeg",
    tags: ["cats", "animals"],
    onlyFiles: "false",
    onlyFolders: "false",
    pageSize: "10",
    sort: "name",
});
while (paginator.hasNext()) {
    const { items, page } = await paginator.next();
    console.log(page.current); // 1
    console.log(page.hasNext); // false
    console.log(page.size); // 3
    console.log(items.length); // 3
}
Argument Type Required Description
name string no Find items with matching name
path string no Find items with matching path
format string no Find items with matching format
tags [string] no Find items containing these tags
onlyFiles boolean no If true will fetch only files
onlyFolders boolean no If true will fetch only folders
pageSize number no Page Size
sort string no Key to sort results by. A "-" suffix will sort results in descending orders.

List all files and folders in root folder. Search for files if name is provided. If path is provided, search in the specified path.

Returned Response:

ListFilesResponse

Success

  Example: 
{
    "items": [
        {
            "_id": "dummy-uuid",
            "name": "dir",
            "type": "folder"
        },
        {
            "_id": "dummy-uuid",
            "name": "asset2",
            "type": "file",
            "path": "dir",
            "fileId": "dir/asset2",
            "format": "jpeg",
            "size": 1000,
            "access": "private"
        },
        {
            "_id": "dummy-uuid",
            "name": "asset1",
            "type": "file",
            "path": "dir",
            "fileId": "dir/asset1",
            "format": "jpeg",
            "size": 1000,
            "access": "private"
        }
    ],
    "page": {
        "type": "number",
        "size": 4,
        "current": 1,
        "hasNext": false
    }
}

getDefaultAssetForPlayground

Summary: Get default asset for playground

// Promise

const promise = assets.getDefaultAssetForPlayground();

// Async/Await

const data = await assets.getDefaultAssetForPlayground();

Get default asset for playground

Returned Response:

UploadResponse

Success

  Example: 
{
    "isActive": true,
    "orgId": "1",
    "type": "file",
    "name": "abc.jpeg",
    "path": "/xyz",
    "fileId": "xyz/abc.jpeg",
    "format": "jpeg",
    "size": 100,
    "tags": null,
    "metadata": null,
    "access": "public-read",
    "width": null,
    "height": null,
    "meta": {},
    "context": null,
    "assetType": null,
    "isOriginal": true,
    "_id": "35675e3a-5dd8-4b19-a611-1cb64e676c5e",
    "url": "https://cdn.pixelbin.io/v2/dummy-cloudname/original/xyz/abc.jpeg"
}

getModules

Summary: Get all transformation modules

// Promise

const promise = assets.getModules();

// Async/Await

const data = await assets.getModules();

Get all transformation modules.

Returned Response:

TransformationModulesResponse

Success

  Example: 
{
    "delimiters": {
        "operationSeparator": "~",
        "parameterSeparator": ":"
    },
    "plugins": {
        "erase": {
            "identifier": "erase",
            "name": "EraseBG",
            "description": "EraseBG Background Removal Module",
            "credentials": {
                "required": false
            },
            "operations": [
                {
                    "params": {
                        "name": "Industry Type",
                        "type": "enum",
                        "enum": ["general", "ecommerce"],
                        "default": "general",
                        "identifier": "i",
                        "title": "Industry type"
                    },
                    "displayName": "Remove background of an image",
                    "method": "bg",
                    "description": "Remove the background of any image"
                }
            ],
            "enabled": true
        }
    },
    "presets": [
        {
            "_id": "dummy-id",
            "createdAt": "2022-02-14T10:06:17.803Z",
            "updatedAt": "2022-02-14T10:06:17.803Z",
            "isActive": true,
            "orgId": "265",
            "presetName": "compressor",
            "transformation": "t.compress(q:95)",
            "archived": false
        }
    ]
}

getModule

Summary: Get Transformation Module by module identifier

// Promise

const promise = assets.getModule({
    identifier: "t",
});

// Async/Await

const data = await assets.getModule({
    identifier: "t",
});
Argument Type Required Description
identifier string yes identifier of Transformation Module

Get Transformation Module by module identifier

Returned Response:

TransformationModuleResponse

Success

  Example: 
{
    "identifier": "erase",
    "name": "EraseBG",
    "description": "EraseBG Background Removal Module",
    "credentials": {
        "required": false
    },
    "operations": [
        {
            "params": {
                "name": "Industry Type",
                "type": "enum",
                "enum": ["general", "ecommerce"],
                "default": "general",
                "identifier": "i",
                "title": "Industry type"
            },
            "displayName": "Remove background of an image",
            "method": "bg",
            "description": "Remove the background of any image"
        }
    ],
    "enabled": true
}

addPreset

Summary: Add a preset.

// Promise

const promise = assets.addPreset({
    presetName: "pre-set_1",
    transformation: "t.resize(w:$w,h:$h)~t.extract()",
    params: { w: { type: "integer", default: 200 }, h: { type: "integer", default: 400 } },
});

// Async/Await

const data = await assets.addPreset({
    presetName: "pre-set_1",
    transformation: "t.resize(w:$w,h:$h)~t.extract()",
    params: { w: { type: "integer", default: 200 }, h: { type: "integer", default: 400 } },
});
Argument Type Required Description
presetName string yes Name of the preset
transformation string yes A chain of transformations, separated by ~
params string no Parameters object for transformation variables

Add a preset for an organization.

Returned Response:

AddPresetResponse

Success

  Example: 
{
    "orgId": 23,
    "presetName": "pre-set_1",
    "transformation": "t.resize(w:$w,h:$h)~t.extract()",
    "params": {
        "w": {
            "type": "integer",
            "default": 200
        },
        "h": {
            "type": "integer",
            "default": 400
        }
    },
    "_id": "821c6816-3cbb-40fd-8629-0098007fc949",
    "createdAt": "2024-03-21T10:35:47.822Z",
    "updatedAt": "2024-03-21T10:35:47.822Z",
    "isActive": true,
    "archived": false
}

getPresets

Summary: Get presets for an organization

// Promise

const promise = assets.getPresets({
    pageNo: "1",
    pageSize: "5",
    name: "t_0",
    transformation: "t.resize(a:0)",
    archived: "false",
    sort: ["updatedAt"],
});

// Async/Await

const data = await assets.getPresets({
    pageNo: "1",
    pageSize: "5",
    name: "t_0",
    transformation: "t.resize(a:0)",
    archived: "false",
    sort: ["updatedAt"],
});
Argument Type Required Description
pageNo number no Page number
pageSize number no Page size
name string no Preset name
transformation string no Transformation applied
archived boolean no Indicates whether the preset is archived or not
sort [string] no Sort the results by a specific key

Retrieve presets for a specific organization.

Returned Response:

GetPresetsResponse

Success

  Example: 
{
    "items": [
        {
            "_id": "f1ae2fc0-a931-4cef-bd1a-3644dad5ae9b",
            "createdAt": "2024-03-21T10:45:06.623Z",
            "updatedAt": "2024-03-21T10:45:06.623Z",
            "isActive": true,
            "orgId": 23,
            "presetName": "t_0",
            "transformation": "t.resize(a:0)",
            "archived": false,
            "params": {}
        },
        {
            "_id": "b40a03f1-7fa5-42b1-8cc6-ffe84c9e6629",
            "createdAt": "2024-03-21T10:45:06.637Z",
            "updatedAt": "2024-03-21T10:45:06.637Z",
            "isActive": true,
            "orgId": 23,
            "presetName": "t_1",
            "transformation": "t.resize(a:1)",
            "archived": false,
            "params": {}
        }
    ],
    "page": {
        "type": "number",
        "size": 2,
        "current": 1,
        "hasNext": true,
        "itemTotal": 10
    }
}

updatePreset

Summary: Update a preset.

// Promise

const promise = assets.updatePreset({
    presetName: "p1",
    archived: true,
});

// Async/Await

const data = await assets.updatePreset({
    presetName: "p1",
    archived: true,
});
Argument Type Required Description
presetName string yes Name of the preset to be updated
archived boolean yes Indicates if the preset has been archived

Update a preset of an organization.

Returned Response:

AddPresetResponse

Success

  Example: 
{
    "orgId": 23,
    "presetName": "pre-set_1",
    "transformation": "t.resize(w:$w,h:$h)~t.extract()",
    "params": {
        "w": {
            "type": "integer",
            "default": 200
        },
        "h": {
            "type": "integer",
            "default": 400
        }
    },
    "_id": "821c6816-3cbb-40fd-8629-0098007fc949",
    "createdAt": "2024-03-21T10:35:47.822Z",
    "updatedAt": "2024-03-21T10:35:47.822Z",
    "isActive": true,
    "archived": true
}

deletePreset

Summary: Delete a preset.

// Promise

const promise = assets.deletePreset({
    presetName: "pre-set_1",
});

// Async/Await

const data = await assets.deletePreset({
    presetName: "pre-set_1",
});
Argument Type Required Description
presetName string yes Name of the preset to be deleted

Delete a preset of an organization.

Returned Response:

AddPresetResponse

Success

  Example: 
{
    "orgId": 23,
    "presetName": "pre-set_1",
    "transformation": "t.resize(w:$w,h:$h)~t.extract()",
    "params": {
        "w": {
            "type": "integer",
            "default": 200
        },
        "h": {
            "type": "integer",
            "default": 400
        }
    },
    "_id": "821c6816-3cbb-40fd-8629-0098007fc949",
    "createdAt": "2024-03-21T10:35:47.822Z",
    "updatedAt": "2024-03-21T10:35:47.822Z",
    "isActive": true,
    "archived": false
}

getPreset

Summary: Get a preset.

// Promise

const promise = assets.getPreset({
    presetName: "p1",
});

// Async/Await

const data = await assets.getPreset({
    presetName: "p1",
});
Argument Type Required Description
presetName string yes Name of the preset to be fetched

Get a preset of an organization.

Returned Response:

AddPresetResponse

Success

  Example: 
{
    "orgId": 23,
    "presetName": "p1",
    "transformation": "t.resize(w:$w,h:$h)~t.extract()",
    "params": {
        "w": {
            "type": "integer",
            "default": 200
        },
        "h": {
            "type": "integer",
            "default": 400
        }
    },
    "_id": "821c6816-3cbb-40fd-8629-0098007fc949",
    "createdAt": "2024-03-21T10:35:47.822Z",
    "updatedAt": "2024-03-21T10:35:47.822Z",
    "isActive": true,
    "archived": false
}

fileUpload

Summary: Upload File

// Promise
const fs = require("fs");
const promise = assets.fileUpload({
    file: fs.createReadStream("your-file-path"),
    path: "path/to/containing/folder",
    name: "filename",
    access: "public-read",
    tags: ["tag1", "tag2"],
    metadata: {},
    overwrite: false,
    filenameOverride: true,
});

// Async/Await
const fs = require("fs");
const data = await assets.fileUpload({
    file: fs.createReadStream("your-file-path"),
    path: "path/to/containing/folder",
    name: "filename",
    access: "public-read",
    tags: ["tag1", "tag2"],
    metadata: {},
    overwrite: false,
    filenameOverride: true,
});
Argument Type Required Description
file file yes Asset file
path string no Path where you want to store the asset
name string no Name of the asset, if not provided name of the file will be used. Note - The provided name will be slugified to make it URL safe
access AccessEnum no Access level of asset, can be either public-read or private
tags [string] no Asset tags
metadata string no Asset related metadata
overwrite boolean no Overwrite flag. If set to true will overwrite any file that exists with same path, name and type. Defaults to false.
filenameOverride boolean no If set to true will add unique characters to name if asset with given name already exists. If overwrite flag is set to true, preference will be given to overwrite flag. If both are set to false an error will be raised.

Upload File to Pixelbin

Returned Response:

UploadResponse

Success

  Example: 
{
    "_id": "dummy-uuid",
    "name": "asset",
    "path": "dir",
    "fileId": "dir/asset",
    "format": "jpeg",
    "size": 1000,
    "access": "private",
    "isActive": true,
    "tags": ["tag1", "tag2"],
    "metadata": {
        "key": "value"
    },
    "url": "https://domain.com/filename.jpeg"
}

urlUpload

Summary: Upload Asset with url

// Promise

const promise = assets.urlUpload({
    url: "www.dummy.com/image.png",
    path: "path/to/containing/folder",
    name: "filename",
    access: "public-read",
    tags: ["tag1", "tag2"],
    metadata: {},
    overwrite: false,
    filenameOverride: true,
});

// Async/Await

const data = await assets.urlUpload({
    url: "www.dummy.com/image.png",
    path: "path/to/containing/folder",
    name: "filename",
    access: "public-read",
    tags: ["tag1", "tag2"],
    metadata: {},
    overwrite: false,
    filenameOverride: true,
});
Argument Type Required Description
url string yes Asset URL
path string no Path where you want to store the asset
name string no Name of the asset, if not provided name of the file will be used. Note - The provided name will be slugified to make it URL safe
access AccessEnum no Access level of asset, can be either public-read or private
tags [string] no Asset tags
metadata string no Asset related metadata
overwrite boolean no Overwrite flag. If set to true will overwrite any file that exists with same path, name and type. Defaults to false.
filenameOverride boolean no If set to true will add unique characters to name if asset with given name already exists. If overwrite flag is set to true, preference will be given to overwrite flag. If both are set to false an error will be raised.

Upload Asset with url

Returned Response:

UploadResponse

Success

  Example: 
{
    "_id": "dummy-uuid",
    "name": "asset",
    "path": "dir",
    "fileId": "dir/asset",
    "format": "jpeg",
    "size": 1000,
    "access": "private",
    "isActive": true,
    "tags": ["tag1", "tag2"],
    "metadata": {
        "key": "value"
    },
    "url": "https://domain.com/filename.jpeg"
}

createSignedUrl

Summary: S3 Signed URL upload

// Promise

const promise = assets.createSignedUrl({
    name: "filename",
    path: "path/to/containing/folder",
    format: "jpeg",
    access: "public-read",
    tags: ["tag1", "tag2"],
    metadata: {},
    overwrite: false,
    filenameOverride: true,
});

// Async/Await

const data = await assets.createSignedUrl({
    name: "filename",
    path: "path/to/containing/folder",
    format: "jpeg",
    access: "public-read",
    tags: ["tag1", "tag2"],
    metadata: {},
    overwrite: false,
    filenameOverride: true,
});
Argument Type Required Description
name string no name of the file
path string no Path of the file
format string no Format of the file
access AccessEnum no Access level of asset, can be either public-read or private
tags [string] no Tags associated with the file.
metadata string no Metadata associated with the file.
overwrite boolean no Overwrite flag. If set to true will overwrite any file that exists with same path, name and type. Defaults to false.
filenameOverride boolean no If set to true will add unique characters to name if asset with given name already exists. If overwrite flag is set to true, preference will be given to overwrite flag. If both are set to false an error will be raised.

For the given asset details, a S3 signed URL will be generated, which can be then used to upload your asset.

Returned Response:

SignedUploadResponse

Success

  Example: 
{
    "s3PresignedUrl": {
        "url": "https://domain.com/xyz",
        "fields": {
            "field1": "value",
            "field2": "value"
        }
    }
}

createSignedUrlV2

Summary: Signed multipart upload

// Promise

const promise = assets.createSignedUrlV2({
    name: "filename",
    path: "path/to/containing/folder",
    format: "jpeg",
    access: "public-read",
    tags: ["tag1", "tag2"],
    metadata: {},
    overwrite: false,
    filenameOverride: true,
    expiry: 3000,
});

// Async/Await

const data = await assets.createSignedUrlV2({
    name: "filename",
    path: "path/to/containing/folder",
    format: "jpeg",
    access: "public-read",
    tags: ["tag1", "tag2"],
    metadata: {},
    overwrite: false,
    filenameOverride: true,
    expiry: 3000,
});
Argument Type Required Description
name string no name of the file
path string no Path of containing folder.
format string no Format of the file
access AccessEnum no Access level of asset, can be either public-read or private
tags [string] no Tags associated with the file.
metadata string no Metadata associated with the file.
overwrite boolean no Overwrite flag. If set to true will overwrite any file that exists with same path, name and type. Defaults to false.
filenameOverride boolean no If set to true will add unique characters to name if asset with given name already exists. If overwrite flag is set to true, preference will be given to overwrite flag. If both are set to false an error will be raised.
expiry number no Expiry time in seconds for the signed URL. Defaults to 3000 seconds.

For the given asset details, a presigned URL will be generated, which can be then used to upload your asset in chunks via multipart upload.

Returned Response:

SignedUploadV2Response

Success

  Example: 
{
    "presignedUrl": {
        "url": "https://api.pixelbin.io/service/public/assets/v1.0/signed-multipart?pbs=8b49e6cdd446be379aa4396e1a&pbe=1700600070390&pbt=92661&pbo=143209&pbu=5fe187e8-8649-4546-9a28-ff551839e0f5",
        "fields": {
            "x-pixb-meta-assetdata": "{\"orgId\":1,\"type\":\"file\",\"name\":\"filename.jpeg\",\"path\":\"\",\"fileId\":\"filename.jpeg\",\"format\":\"jpeg\",\"s3Bucket\":\"erase-erase-erasebg-assets\",\"s3Key\":\"uploads/floral-sun-9617c8/original/a34f1d3-28bf-489c-9aff-cc549ac9e003.jpeg\",\"access\":\"public-read\",\"tags\":[],\"metadata\":{\"source\":\"signedUrl\",\"publicUploadId\":\"5fe187e8-8649-4546-9a28-ff551839e0f5\"},\"overwrite\":false,\"filenameOverride\":false}"
        }
    }
}

Schemas

folderItem

Properties Type Nullable Description
_id string no Id of the folder item
orgId number no Organization Id
name string no Name of the folder item
path string no Path of the folder item
type string no Type of the item. file or folder

exploreItem

Properties Type Nullable Description
_id string no id of the exploreItem
orgId number no Organization Id
name string no name of the item
type string no Type of item whether file or folder
path string no Path of the folder item
fileId string no FileId associated with the item. path+name
format string no Format of the file
size number no Size of the file in bytes
access AccessEnum no Access level of asset, can be either public-read or private
s3Bucket string no Bucket Name
s3Key string no s3 path of file

page

Properties Type Nullable Description
type string yes Type of page
size number yes Number of items on the page
current number yes Current page number.
hasNext boolean yes Whether the next page exists.
itemTotal number yes Total number of items.

exploreResponse

Properties Type Nullable Description
items [exploreItem] yes exploreItems in current page
page page yes page details

ListFilesResponse

Properties Type Nullable Description
items [exploreItem] no exploreItems in current page
page page no page details

FileUploadRequest

Properties Type Nullable Description
file file yes Asset file
path string no Path where you want to store the asset
name string no Name of the asset, if not provided name of the file will be used. Note - The provided name will be slugified to make it URL safe
access AccessEnum no Access level of asset, can be either public-read or private
tags [string] no Asset tags
metadata string no Asset related metadata
overwrite boolean no Overwrite flag. If set to true will overwrite any file that exists with same path, name and type. Defaults to false.
filenameOverride boolean no If set to true will add unique characters to name if asset with given name already exists. If overwrite flag is set to true, preference will be given to overwrite flag. If both are set to false an error will be raised.

UrlUploadRequest

Properties Type Nullable Description
url string yes Asset URL
path string no Path where you want to store the asset
name string no Name of the asset, if not provided name of the file will be used. Note - The provided name will be slugified to make it URL safe
access AccessEnum no Access level of asset, can be either public-read or private
tags [string] no Asset tags
metadata string no Asset related metadata
overwrite boolean no Overwrite flag. If set to true will overwrite any file that exists with same path, name and type. Defaults to false.
filenameOverride boolean no If set to true will add unique characters to name if asset with given name already exists. If overwrite flag is set to true, preference will be given to overwrite flag. If both are set to false an error will be raised.

UploadResponse

Properties Type Nullable Description
_id string yes _id of the item
fileId string yes FileId associated with the item. path+name
name string yes name of the item
path string yes path to the parent folder
format string yes format of the file
size number yes size of file in bytes
access AccessEnum yes Access level of asset, can be either public-read or private
tags [string] no tags associated with the item
metadata string no metadata associated with the item
url string no url of the item
thumbnail string no url of item thumbnail

SignedUploadRequest

Properties Type Nullable Description
name string no name of the file
path string no Path of the file
format string no Format of the file
access AccessEnum no Access level of asset, can be either public-read or private
tags [string] no Tags associated with the file.
metadata string no Metadata associated with the file.
overwrite boolean no Overwrite flag. If set to true will overwrite any file that exists with same path, name and type. Defaults to false.
filenameOverride boolean no If set to true will add unique characters to name if asset with given name already exists. If overwrite flag is set to true, preference will be given to overwrite flag. If both are set to false an error will be raised.

SignedUploadResponse

Properties Type Nullable Description
s3PresignedUrl PresignedUrl yes signedDetails for upload with frontend sdk

PresignedUrl

Properties Type Nullable Description
url string no presigned url for upload
fields string no signed fields to be sent along with request

FilesResponse

Properties Type Nullable Description
_id string yes _id of the file
name string yes name of the file
path string yes path to the parent folder of the file
fileId string yes FileId associated with the item. path+name
format string yes format of the file
size number yes size of the file in bytes
access AccessEnum yes Access level of file, can be either public-read or private
isActive boolean yes Whether the file is active
tags [string] no Tags associated with the file
metadata string no Metadata associated with the file
url string no url of the file
thumbnail string no url of the thumbnail of the file

UpdateFileRequest

Properties Type Nullable Description
name string no Name of the file
path string no Path of the file
access AccessEnum no Access level of asset, can be either public-read or private
isActive boolean no Whether the file is active
tags [string] no Tags associated with the file
metadata string no Metadata associated with the file

FoldersResponse

Properties Type Nullable Description
_id string yes _id of the folder
name string yes name of the folder
path string yes path to the parent folder of the folder
isActive boolean yes whether the folder is active

CreateFolderRequest

Properties Type Nullable Description
name string yes Name of the folder
path string no Path of the folder

UpdateFolderRequest

Properties Type Nullable Description
isActive boolean no whether the folder is active

DeleteMultipleFilesRequest

Properties Type Nullable Description
ids [string] yes Array of file _ids to delete

Delimiter

Properties Type Nullable Description
operationSeparator string no separator to separate operations in the url pattern
parameterSeparator string no separator to separate parameters used with operations in the url pattern

AddCredentialsRequest

Properties Type Nullable Description
credentials string yes Credentials of the plugin
pluginId string yes Unique identifier for the plugin this credential belongs to

UpdateCredentialsRequest

Properties Type Nullable Description
credentials string yes Credentials of the plugin

AddCredentialsResponse

Properties Type Nullable Description
credentials string no

GetAncestorsResponse

Properties Type Nullable Description
folder folderItem no
ancestors [FoldersResponse] no

AddPresetRequest

Properties Type Nullable Description
presetName string yes Name of the preset
transformation string yes A chain of transformations, separated by ~
params string no Parameters object for transformation variables

AddPresetResponse

Properties Type Nullable Description
presetName string no Name of the preset
transformation string no A chain of transformations, separated by ~
params string no Parameters object for transformation variables
archived boolean no Indicates if the preset has been archived
orgId number no Organization Id
isActive boolean no Indicates if the preset is active
createdAt string no Preset creation ISO timestamp
updatedAt string no Preset update ISO timestamp

UpdatePresetRequest

Properties Type Nullable Description
archived boolean yes Indicates if the preset has been archived

GetPresetsResponse

Properties Type Nullable Description
items [AddPresetResponse] yes
page page yes page details

TransformationModuleResponse

Properties Type Nullable Description
identifier string no identifier for the plugin type
name string no name of the plugin
description string no description of the plugin
credentials string no credentials, if any, associated with the plugin
operations [any] no supported operations in the plugin
enabled boolean no whether the plugin is enabled

TransformationModulesResponse

Properties Type Nullable Description
delimiters Delimiter no Delimiter for parsing plugin schema
plugins [String: TransformationModuleResponse] no Transformations currently supported by the pixelbin
presets [any] no List of saved presets

SignedUploadRequestV2

Properties Type Nullable Description
name string no name of the file
path string no Path of containing folder.
format string no Format of the file
access AccessEnum no Access level of asset, can be either public-read or private
tags [string] no Tags associated with the file.
metadata string no Metadata associated with the file.
overwrite boolean no Overwrite flag. If set to true will overwrite any file that exists with same path, name and type. Defaults to false.
filenameOverride boolean no If set to true will add unique characters to name if asset with given name already exists. If overwrite flag is set to true, preference will be given to overwrite flag. If both are set to false an error will be raised.
expiry number no Expiry time in seconds for the signed URL. Defaults to 3000 seconds.

SignedUploadV2Response

Properties Type Nullable Description
presignedUrl PresignedUrlV2 yes Presigned URL for uploading asset in chunks

PresignedUrlV2

Properties Type Nullable Description
url string no Presigned URL for uploading asset in chunks
fields [String: string] no signed fields to be sent along with request

Enums

AccessEnum

Type : string

Name Value Description
public-read public-read public-read
private private private