Public API

Introduction

NetX is a Digital Asset Management application that empowers users to store, manage, and distribute their digital assets. You can use our API to access assets, folders, attribute data, collections, and views.

Getting started

JSON-RPC

Our API adheres to the JSON-RPC 2.0 spec (http://www.jsonrpc.org/specification) with a few exceptions; we do not yet support named parameters or batched calls.

From the spec: An RPC call is represented by sending a request object to a server. The request object has the following members:

  • jsonrpc: A string specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
  • method: A string containing the name of the method to be invoked. Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and MUST NOT be used for anything else.
  • params: A structured value that holds the parameter values to be used during the invocation of the method. This member MAY be omitted.
  • id: An identifier established by the client that MUST contain a string, number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null [1] and Numbers SHOULD NOT contain fractional parts [2]

We also require an extra field in the call named dataContext, which must be set to a value of "json". This will be removed in future versions.

Parameters and request options

Many of the methods in the API have an options parameter that allows you to specify pagination, sorting, and a list of data included in the return objects. For all of the code examples in this documentation, we will use a page size of 1 or 2 to save space. Here is an example of the getAssetsByFolder method illustrating the use of parameters and their options:

{
    "id":"13576991614322",
    "method":"getAssetsByFolder",
    "params":[
        "NVvdBOKjcvm2nIYt6xzN5rKGv",
        12,
        false,
        {
            "page": {
                "startIndex": 0,
                "size": 2
            },
            "data": ["asset.id", "asset.base"]
        }
    ],
    "dataContext":"json",
    "jsonrpc":"2.0"
}

This indicates that we want assets from folder id 8 (the Castles folder), we don't want assets from subfolders (recursive = false, the 3rd parameter), and that we want paging to start with the first object (startindex = 0), and include 2 items. The data option indicates that all we want are the asset id and the name (asset.id and asset.base).

sort

  • field specifies the field you want to sort on.
  • order specifies a descending or ascending sort order.

page

  • size specifies the number of items included in the response.
  • startIndex specifies the first object in the page.

data

  • This option specifies the data you want returned in the response. You can choose any combination of data options, and the API will only return the data you have selected. As we continue to extend the API, additional fields will be added. For each method, we will list the current data options throughout this documentation.

Not all options are available for every method, please see the particular method for documentation on which options you can use.

Endpoint

The endpoint URL for the API on your site is:

https://<netxinstance>.netx.net/external/api/json

API request objects are POSTed to this URL, and response objects are returned. You must use the HTTP POST verb. You cannot use GET to invoke JSON-RPC methods in the NetX API.

Authentication

authenticate

The NetX API uses session-based authentication. The result of the authenticate call, if successful, is an object containing a session key. This key will be the first parameter of every subsequent API call you make.

Parameters

Parameter Description
password Password to authenticate with
username Username to authenticate with
 

Data options

None

Returns

A session object containing the sessionKey which needs to be used for subsequent API calls.

Example

Here's an example authenticate call:

{
    "id":"13576991614322",
    "method":"authenticate",
    "params":["username", "password"],
    "dataContext":"json",
    "jsonrpc":"2.0"
}

If successful, the response object looks like this:

{
    "result": {
        "sessionKey": "NVvdBOKjcvm2nIYt6xzN5rKGv"
    },
    "id": "13576991614322",
    "jsonrpc": "2.0"
}

An error response looks like this:


{
    "id": "13576991614322",
    "error": {
        "result": "Invalid Session",
        "code": 3001,
        "data": null,
        "message": "Invalid Session"
    },
    "jsonrpc": "2.0"
}

Assets

getAssets

Gets one or more assets using their unique identifiers

Parameters

Parameter Description
sessionKey A user's active session key
assetId Array of asset IDs
options data (see data options below)

Data options

Option Description
asset.proxies
Info about the asset proxy files (thumbnail, preview, zoom)
asset.views
Info about any views attached to the asset
asset.relatedAssets
Info about assets related to the asset
asset.folders
Info about the asset's parent folders
asset.attributes
Attribute data for each asset
asset.id
Asset ID
asset.base
Asset name, creation date, import date, modification date
asset.file
File name, size, width, height, checksum, URL

Returns

A list of requested asset objects

Example

Example request:

{
    "dataContext" : "json",
    "jsonrpc" : "2.0",
    "id" : "1234567890",
    "method" : "getAssets",
    "params":[
        "aelfUY1oR2NCv2goj53jG66hI",
    	[17901, 17902, 17903],
        {
            "data": [
                "asset.base",
                "asset.file"
            ]
        }
    ]
}

Example response:

{
    "result": [
        {
            "id": 17901,
            "name": "javier-haro-ZOcW67YXtRY-unsplash",
            "fileName": "javier-haro-ZOcW67YXtRY-unsplash.jpg",
            "creationDate": 1611604502000,
            "importDate": 1611604502000,
            "modDate": 1611610786000,
            "file": {
                "name": "javier-haro-ZOcW67YXtRY-unsplash.jpg",
                "size": 1009380,
                "width": 3621,
                "height": 5431,
                "checksum": "0a03c80336f972272473cfdd85ae78f8",
                "url": "/file/asset/17901/original/attachment"
            },
            "proxies": null,
            "views": null,
            "relatedAssets": null,
            "folders": null,
            "attributes": null
        },
        {
            "id": 17902,
            "name": "herr-bohn-Gn_FJNiH9Zo-unsplash",
            "fileName": "herr-bohn-Gn_FJNiH9Zo-unsplash.jpg",
            "creationDate": 1611611525000,
            "importDate": 1611611525000,
            "modDate": 1611684259000,
            "file": {
                "name": "herr-bohn-Gn_FJNiH9Zo-unsplash.jpg",
                "size": 2579970,
                "width": 3000,
                "height": 3882,
                "checksum": "a35333cd953278ae5b1ae14dde3b780a",
                "url": "/file/asset/17902/original/attachment"
            },
            "proxies": null,
            "views": null,
            "relatedAssets": null,
            "folders": null,
            "attributes": null
        },
        {
            "id": 17903,
            "name": "ryunosuke-kikuno-WGxMAt33azU-unsplash",
            "fileName": "ryunosuke-kikuno-WGxMAt33azU-unsplash.jpg",
            "creationDate": 1611691557000,
            "importDate": 1611691557000,
            "modDate": 1611691564000,
            "file": {
                "name": "ryunosuke-kikuno-WGxMAt33azU-unsplash.jpg",
                "size": 3361551,
                "width": 4024,
                "height": 6048,
                "checksum": "7954114f75f7efbb377fcd10bf1bc7af",
                "url": "/file/asset/17903/original/attachment"
            },
            "proxies": null,
            "views": null,
            "relatedAssets": null,
            "folders": null,
            "attributes": null
        }
    ],
    "id": "1234567890",
    "jsonrpc": "2.0"
}

getAssetsByFolder

Returns asset objects contained in a specific folder (and its subfolders, optionally).

Parameters

Parameter Description
options
page, data (see data options below)
sessionKey
A user's active session key
folderId
A folder's unique identifier
recursive
If true, assets found in descendants of the requested folder are included in the result.

Data options

Property Description
asset.proxies
Info about the asset proxy files (thumbnail, preview, zoom)
asset.views
Info about any views attached to the asset
asset.relatedAssets
Info about assets related to the asset
asset.folders
Info about the asset's parent folders
asset.attributes
Attribute data for each asset
asset.id
Asset ID
asset.base
Asset name, creation date, import date, modification date
asset.file
File name, size, width, height, checksum, URL

Returns

A page of asset objects.

Example

Example request:

{
    "id":"13576991614322",
    "method":"getAssetsByFolder",
    "params":[
        "NVvdBOKjcvm2nIYt6xzN5rKGv",
        12,
        false,
        {
            "page": {
                "startIndex": 0,
                "size": 2
            },
            "data": ["asset.id", "asset.base"]
        }
    ],
    "dataContext":"json",
    "jsonrpc":"2.0"
}

Example response:

{
    "result": {
        "results": [
            {
                "id": 39,
                "name": "Alcázar de Segovia",
                "file": null,
                "proxies": null,
                "views": null
            },
            {
                "id": 40,
                "name": "Alnwick Castle",
                "file": null,
                "proxies": null,
                "views": null
            }
        ],
        "size": 62
    },
    "id": "13576991614322",
    "jsonrpc": "2.0"
}

Here is the same call, with a different set of options:

{
    "id":"13576991614322",
    "method":"getAssetsByFolder",
    "params":[
        "NVvdBOKjcvm2nIYt6xzN5rKGv",
        12,
        false,
        {
            "page": {
                "startIndex": 2,
                "size": 2
            },
            "data": ["asset.id", "asset.base", "asset.file", "asset.proxies"]
        }
    ],
    "dataContext":"json",
    "jsonrpc":"2.0"
}

And the response:

{
    "result": {
        "results": [
            {
                "id": 41,
                "name": "Château de Chambord",
                "file": {
                    "name": "Architecture-Chambord-Castle-France.jpg",
                    "size": 559423,
                    "width": 1600,
                    "height": 1200,
                    "url": "/file/asset/41/original/attachment"
                },
                "proxies": [
                    {
                        "name": "Thumbnail",
                        "file": {
                            "name": "Château de Chambord-thumbnail.jpg",
                            "size": 5584,
                            "width": null,
                            "height": null,
                            "url": "/view/0000/t_41.jpg"
                        }
                    },
                    {
                        "name": "Preview",
                        "file": {
                            "name": "Château de Chambord-preview.jpg",
                            "size": 59074,
                            "width": 500,
                            "height": 375,
                            "url": "/view/0000/p_41.jpg"
                        }
                    },
                    {
                        "name": "Zoom",
                        "file": {
                            "name": "Château de Chambord-zoom.jpg",
                            "size": 210869,
                            "width": null,
                            "height": null,
                            "url": "/zoom/0000/z_41.jpg"
                        }
                    }
                ],
                "views": null
            },
            {
                "id": 42,
                "name": "Arg-é Bam",
                "file": {
                    "name": "arg-e-bam.jpg",
                    "size": 69922,
                    "width": 550,
                    "height": 372,
                    "url": "/file/asset/42/original/attachment"
                },
                "proxies": [
                    {
                        "name": "Thumbnail",
                        "file": {
                            "name": "Arg-é Bam-thumbnail.jpg",
                            "size": 4443,
                            "width": null,
                            "height": null,
                            "url": "/view/0000/t_42.jpg"
                        }
                    },
                    {
                        "name": "Preview",
                        "file": {
                            "name": "Arg-é Bam-preview.jpg",
                            "size": 41956,
                            "width": 500,
                            "height": 338,
                            "url": "/view/0000/p_42.jpg"
                        }
                    },
                    {
                        "name": "Zoom",
                        "file": {
                            "name": "Arg-é Bam-zoom.jpg",
                            "size": 113834,
                            "width": null,
                            "height": null,
                            "url": "/zoom/0000/z_42.jpg"
                        }
                    }
                ],
                "views": null
            }
        ],
        "size": 62
    },
    "id": "13576991614322",
    "jsonrpc": "2.0"
}

addAssetToFolder

Adds an asset to a specific parent folder.

Parameters

Parameter Description
options page, data (see data options below)
sessionKey A user's active session key
assetId ID of the asset added to the folder
folderId ID of the folder the asset is added to
 

Data options

Option Description
asset.proxies Info about the asset proxy files (thumbnail, preview, zoom)
asset.views Info about any views attached to the asset
asset.relatedAssets Info about assets related to the asset
asset.folders Info about the asset's parent folders
asset.attributes Attribute data for each asset
asset.id Asset ID
asset.base Asset name, creation date, import date, modification date
asset.file File name, size, width, height, checksum, URL
 

Returns

An updated asset object.

Example

Example request:

{
  "id": "7444760565671519",
  "method": "addAssetToFolder",
  "params": [
    "XRuSs5eS02WkSFNx70Wo1sGBi",
    71,
    23,
    {
      "data": [
        "asset.id",
        "asset.base",
        "asset.file",
        "asset.folders"
      ]
    }
  ],
  "dataContext": "json",
  "jsonrpc": "2.0"
}

Example response:

{
  "result": {
    "id": 71,
    "name": "logo-image-small",
    "file": {
      "name": "logo-image-small.jpg",
      "size": 3249,
      "width": 155,
      "height": 155,
      "url": "/file/asset/71/original/attachment"
    },
    "proxies": null,
    "views": null,
    "relatedAssets": null,
    "folders": [
      {
        "id": 22,
        "name": "New Category",
        "description": "",
        "path": "API Testing/New Category",
        "children": null
      },
      {
        "id": 23,
        "name": "Folder 1",
        "description": "",
        "path": "API Testing/Folder 1",
        "children": null
      }
    ]
  },
  "id": "7444760565671519",
  "jsonrpc": "2.0"
}

removeAssetFromFolder

Removes an asset from its parent folder.

Parameters

Parameter Description
options
page, data (see data options below)
sessionKey
A user's active session key
assetId
ID of the asset removed from the folder
folderId
ID of the folder the asset is removed from

Data options

Option Description
asset.proxies
 Info about the asset proxy files (thumbnail, preview, zoom)
asset.views
Info about any views attached to the asset
asset.relatedAssets
Info about assets related to the asset
asset.folders
Info about the asset's parent folders
asset.attributes
Attribute data for each asset
asset.id
Asset ID
asset.base
Asset name, creation date, import date, modification date
asset.file
File name, size, width, height, checksum, URL

Returns

An updated asset object.

Example

Example request:

{
  "id": "7445197747158073",
  "method": "removeAssetFromFolder",
  "params": [
    "XRuSs5eS02WkSFNx70Wo1sGBi",
    71,
    23,
    {
      "data": [
        "asset.id",
        "asset.base",
        "asset.file",
        "asset.folders"
      ]
    }
  ],
  "dataContext": "json",
  "jsonrpc": "2.0"
}

Example response:

{
  "result": {
    "id": 71,
    "name": "logo-image-small",
    "file": {
      "name": "logo-image-small.jpg",
      "size": 3249,
      "width": 155,
      "height": 155,
      "url": "/file/asset/71/original/attachment"
    },
    "proxies": null,
    "views": null,
    "relatedAssets": null,
    "folders": [
      {
        "id": 22,
        "name": "New Category",
        "description": "",
        "path": "API Testing/New Category",
        "children": null
      }
    ]
  },
  "id": "7445197747158073",
  "jsonrpc": "2.0"
}

versionAsset

Locates a previously uploaded file and checks it in as a new version of the specified asset. The file for the new version MUST have already been uploaded.

Parameters

Parameter Description
notes
Notes about the new version
sessionKey
A user's active session key
assetId
ID of the asset to version
fileName
Name of the uploaded file

Data options

None

Returns

An empty object.

deleteAsset

Deletes an existing asset.

Parameters

Parameter Description
assetId
ID of the asset to delete
sessionKey
A user's active session key

Data options

None

Returns

An empty object.

Folders

getFolderById

Finds a folder with a given ID

Parameters

Month Savings
sessionKey
A user's active session key
folderId
The folder's unique identifier
options
data (see data options below)

Data options

Parameter Description
folder.id
Folder ID
folder.base
Folder name, description, and full path (individual folders are separated with a forward slash)
folder.children
Info about the folder's child assets and subfolders

Returns

A folder object

Example

Example request:

{
  "id": "13576991614322",
  "method": "getFolderById",
  "params": [
    "V3tNpm4hCo9Xy1TAqvlBzmN76",
    "37",
    {
      "data": [
        "folder.id",
        "folder.base",
        "folder.children"
      ]
    }
  ],
  "dataContext": "json",
  "jsonrpc": "2.0"
}

Example response:

{
    "result": {
        "id": 37,
        "name": "Logos",
        "description": "",
        "path": "Logos",
        "children": {
            "assetCount": 24,
            "folderCount": 5
        }
    },
    "id": "13576991614322",
    "jsonrpc": "2.0"
}

getFoldersByParent

Lists the folders with a given folder as a parent.

Parameters

Parameter Description
sessionKey
A user's active session key
parentId
The parent folder's ID
options
page, data (see data options below)

Data options

Option Description
folder.id
Folder ID
folder.base
Folder name, description, and full path (individual folders are separated with a forward slash)
folder.children
Info about the folder's child assets and folders

Returns

A page of folder objects.

Example

Example request:

{
    "id":"13576991614322",
    "method":"getFoldersByParent",
    "params":[
        "NVvdBOKjcvm2nIYt6xzN5rKGv",
        1,
        {
            "page": {
                "startIndex": 0,
                "size": 10
            },
            "data": ["folder.id", "folder.base"]
        }
    ],
    "dataContext":"json",
    "jsonrpc":"2.0"
}

Example response:

{
    "result": {
        "results": [
            {
                "id": 2,
                "name": "Getting Started",
                "description": "",
                "path": "Getting Started"
            },
            {
                "id": 9,
                "name": "Marketing",
                "description": "",
                "path": "Marketing"
            },
            {
                "id": 7,
                "name": "Object Collection",
                "description": "",
                "path": "Object Collection"
            },
            {
                "id": 8,
                "name": "Archives",
                "description": "",
                "path": "Archives"
            },
            {
                "id": 12,
                "name": "Castles",
                "description": "",
                "path": "Castles"
            }
        ],
        "size": 5
    },
    "id": "13576991614322",
    "jsonrpc": "2.0"
}

getFoldersByNameFilter

Lists the folders with names that contain a given filter string.

Parameters

Paramater Description
sessionKey
A user's active session key
filter
A case-insensitive name filter
options
page, data (see data options below)

Data options

Option Description
folder.id
Folder ID
folder.base
Folder name, description, and full path (individual folders are separated with a forward slash)
folder.children
Info about the folder's child assets and folders

Returns

A page of folder objects.

Example

Example request:

{
    "id":"13576991614322",
    "method":"getFoldersByNameFilter",
    "params":[
        "NVvdBOKjcvm2nIYt6xzN5rKGv",
        "Cas",
        {
            "page": {
                "startIndex": 0,
                "size": 10
            },
            "data": ["folder.id", "folder.base"]
        }
    ],
    "dataContext":"json",
    "jsonrpc":"2.0"
}

Example response:

{
    "result": {
        "results": [
            {
                "id": 12,
                "name": "Castles",
                "description": "",
                "path": "Castles"
            }
        ],
        "size": 1
    },
    "id": "13576991614322",
    "jsonrpc": "2.0"
}

getFolderByPath

Finds a folder with a given path.

Parameters

Parameter Description
sessionKey
A user's active session key
path
A forward-slash-separated path.
options
data (see data options below)

Data options

Month Savings
folder.children
Info about the folder's child assets and folders
folder.id
Folder ID
folder.base
Folder name, description, and full path (individual folders are separated with a forward slash)

Returns

A folder object.

Example

Example request:

{
  "id": "13576991614322",
  "method": "getFolderByPath",
  "params": [
    "WtwehfQAZJM11lyhl87igurmF",
    "Portraits",
    {
      "data": [
        "folder.id",
        "folder.base",
        "folder.children"
      ]
    }
  ],
  "dataContext": "json",
  "jsonrpc": "2.0"
}

Example response:

{
    "result": {
        "id": 35,
        "name": "Portraits",
        "description": "",
        "path": "Portraits",
        "children": {
            "assetCount": 7,
            "folderCount": 1
        }
    },
    "id": "13576991614322",
    "jsonrpc": "2.0"
}

createFolderFromPath

Creates a new folder with a given path.

Parameters

Parameter Description
sessionKey
A user's active session key
path
A forward-slash-separated path.
options
data (see data options below)
 

Data options

Month Savings
folder.id
Folder ID
folder.base
Folder name, description, and full path (individual folders are separated with a forward slash)
folder.children
Info about the folder's child assets and folders
 

Returns

The new folder object.

Example

Example request:

{
  "id": "13576991614322",
  "method": "createFolderFromPath",
  "params": [
    "WtwehfQAZJM11lyhl87igurmF",
    "Portraits/Color/Pets",
    {
      "data": [
        "folder.id",
        "folder.base",
        "folder.children"
      ]
    }
  ],
  "dataContext": "json",
  "jsonrpc": "2.0"
}

Example response:

{
    "result": {
        "id": 79,
        "name": "Pets",
        "description": "",
        "path": "Portraits/Color/Pets",
        "children": {
            "assetCount": 0,
            "folderCount": 0
        }
    },
    "id": "13576991614322",
    "jsonrpc": "2.0"
}

Attributes

getAssetAttributes

Retrieves the specified asset's custom attribute values.

Parameters

Parameter Description
assetId
ID of asset to retrieve attributes from
sessionKey
A user's active session key

Data options

None

Returns

Attributes for the specified asset.

Example

Example request:

{
    "id":"13576991614322",
    "method":"getAssetAttributes",
    "params":[
        "FCEApNVV4qshgeKFtMGM2Hdoq",
        12
    ],
    "dataContext":"json",
    "jsonrpc":"2.0"
}

Example response

{
    "result": {
        "Year": [
            "1120"
        ],
        "Country": [
            "Spain"
        ]
    },
    "id": "13576991614322",
    "jsonrpc": "2.0"
}

setAssetAttributes

Updates custom attribute values for the specified asset.

Parameters

Parameter Description
assetId
ID of asset being updated
attributes
Custom attributes to update with
sessionKey
A user's active session key

Data options

None

Returns

An empty object.

Example

Example request:

{
    "id":"13576991614322",
    "method":"setAssetAttributes",
    "params":[
        "FCEApNVV4qshgeKFtMGM2Hdoq",
        12,
        {
            "Year": [
                "1200"
            ],
            "Country": [
                "España"
            ]
        }
    ],
    "dataContext":"json",
    "jsonrpc":"2.0"
}

Example response:

{
    "result": {},
    "id": "13576991614322",
    "jsonrpc": "2.0"
}

updateAsset

Updates asset filename and/or name.

Parameters

Parameter Description
sessionKey
A user's active session key
view
An asset's writable data
options
data (see data options below)

Data options

Option Description
asset.proxies
Info about the asset proxy files (thumbnail, preview, zoom)
asset.views
Info about any views attached to the asset
asset.relatedAssets
Info about assets related to the asset
asset.folders
Info about the asset's parent folders
asset.attributes
Attribute data for each asset
asset.id
Asset ID
asset.base
Asset name, creation date, import date, modification date
asset.file
File name, size, width, height, checksum, URL

Access level

Managers and above.

Returns

The updated asset object.

Example

Example request:

{
    "dataContext" : "json",
    "jsonrpc" : "2.0",
    "id" : "72038957398403",
    "method" : "updateAsset",
    "params":[
        {
            "id": 593,
            "name": "updated-via-api",
            "fileName": "updated-via-api.jpg"
        },
        {
          "data": [
            "asset.base"
          ]
        }
    ]
}

Example response:

{
    "result": {
        "id": 593,
        "name": "updated-via-api",
        "fileName": "updated-via-api.jpg",
        "creationDate": 1313466823000,
        "importDate": 1582069576000,
        "modDate": 1600271644000,
        "file": null,
        "proxies": null,
        "views": null,
        "relatedAssets": null,
        "folders": null,
        "attributes": null
    },
    "id": "72038957398403",
    "jsonrpc": "2.0"
}

getAssetsByQuery

The getAssetsByQuery method finds assets that match a complex search query. A query is made up of one or more clauses; each clause contains an operator and a criterion. A criterion is one of five different objects, each with its own behavior.

Parameters

Month Savings
sessionKey
A user's active session key
query
A selection of search clauses
options
sort, page, data (see data options below)

Operators

Operator Description
and
Matched assets are added to the result set; unmatched assets are removed from the result set
or
Matched assets are added to the result set
not
Matched assets are removed from the result set

Criteria

Criterion Description
folder
Matches assets based on their folder membership
subquery
Matches assets using a complete query
exact
Matches assets with an exact term in a field or attribute
contains
Matches assets with a partial term in a field or attribute that contains text (dates or numbers not supported)
range
Matches assets with a term that falls between two bounds in a field or attribute. Either bound can be omitted to create a greater-than/less-than criterion. Each bound can be either inclusive or exclusive.

Fields

Field Description
fileHeight
File height, in pixels
fileName
File Name
fileSize
File size, in bytes
fileType
File format, as extension
fileWidth
File width, in pixels
importDate
Import date, in milliseconds since Epoch
keywords
Search terms indexed as keywords on the asset
modDate
Last modified date, in milliseconds since Epoch
name
The asset name created in NetX, without extension
assetId
Asset ID
creationDate
File creation date, in milliseconds since Epoch
fileChecksum
File's MD5 checksum, generated by NetX

Data options

Option Description
asset.proxies
Info about the asset proxy files (thumbnail, preview, zoom)
asset.views
Info about any views attached to the asset
asset.relatedAssets
Info about assets related to the asset
asset.folders
Info about the asset's parent folders
asset.attributes
Attribute data for each asset
asset.id
Asset ID
asset.base
Asset name, creation date, import date, modification date
asset.file
File name, size, width, height, checksum, URL

Returns

A page of asset objects.

Example

Here's an example that includes all query components; we'll break it down further below:

{
    "dataContext": "json",
    "jsonrpc": "2.0",
    "id": "GET_ASSETS_BY_QUERY_EXAMPLE",
    "method": "getAssetsByQuery",
    "params": [
        {
            "query": [
                {
                    "operator": "and",
                    "exact": {
                        "attribute": "Color",
                        "value": "Red"
                    }
                },
                {
                    "operator": "and",
                    "folder": {
                        "folderId": 100,
                        "recursive": false
                    }
                }
            ]
        },
        {
            "sort": {
                "field": "name",
                "order": "asc"
            },
            "page": {
                "startIndex": 0,
                "size": 10
            },
            "data": [
                "asset.id",
                "asset.base",
                "asset.attributes"
            ]
        }
    ]
}

Query At its core, a search request is a query. A query matches a set of assets using one or more search clauses.

Using a custom attribute, find assets in folder 100 that are red:


"query": [
    {
        "operator": "and",
        "exact": {
            "attribute": "Color",
            "value": "Red"
        }
    },
    {
        "operator": "and",
        "folder": {
            "folderId": 100,
            "recursive": false
        }
    }
]

Clause A clause matches a set of assets and specifies how those matched assets should impact the result of the overall query.

Using a custom attribute, add red assets to the result set:

{
    "operator": "and",
    "exact": {
        "attribute": "Color",
        "value": "Red"
    }
}

Operator The operator defines how the assets matched by a clause should be combined with assets matched by any other clauses to create the set of assets matched by the entire query.

"operator": "and"

Criterion A criterion matches a set of assets. Different criteria match assets in different ways.

Exact Using a system field, find all JPG assets:

"exact": {
    "field": "fileType",
    "value": "jpg"
}

Using a custom attribute, find all assets that are in the public domain:

"exact": {
    "attribute": "Public domain",
    "value": "true"
}

Contains Using a system field, find assets that mention trees:

"contains": {
    "field": "keywords",
    "value": "tree"
}

Using a custom attribute, find assets that mention buildings:

"contains": {
    "attribute": "Description",
    "value": "building"
}

Range Using a system field, find all assets imported after 2020-09-16T15:00:00.000Z:

"range": {
    "field": "importDate",
    "min": "1600268400000",
    "max": null,
    "includeMin": false,
    "includeMax": true
}

Using a custom attribute, find high priority assets:

"range": {
    "attribute": "Priority",
    "min": "1",
    "max": "3",
    "includeMin": true,
    "includeMax": true
}

Folder Find assets that are children of folder 28:

"folder": {
    "folderId": 28,
    "recursive": false
}

Subquery Using a custom attribute, find red assets in folder 100:

"subquery": {
    "query": [
        {
            "operator": "and",
            "exact": {
                "attribute": "Color",
                "value": "Red"
            }
        },
        {
            "operator": "and",
            "folder": {
                "folderId": 100,
                "recursive": false
            }
        }
    ]
}

Upload assets

Importing new assets is a two step process:

  1. Upload the file to NetX
  2. Call the createAssetFromFile method

Step 1: Upload the file*

In order to import anything you must first upload your file to the server. This is done by uploading your file to the following URL:

https://<netxinstance>.netx.net/servlet/FileUploader

This system follows the RFC 1867 standard (http://www.ietf.org/rfc/rfc1867.txt). There are many open source implementations of this protocol, including the Apache FileUpload project (http://commons.apache.org/fileupload/).

The only addition to the above standard (RFC 1867) is that the calling user must have already authenticated, or the call must pass a "sessionKey" parameter with the upload with a corresponding valid sessionKey value. Without a valid sessionKey or authenticated session, the file uploaded will be discarded.

In using this scheme, the file name is critically important: the uploaded file name must match the name used in the subsequent import call exactly (and by the same session or sessionKey).

In addition to Filename and sessionKey, you'll need to specify the target category in which to import; this is designated with the "folderId" parameter.

Here is an example upload (POST) payload to the FileUploader endpoint, where the name of the file is logo-image-small.png, and it is being uploaded to a folder with the ID of 22:

------------ae0cH2KM7Ef1gL6KM7Ef1gL6cH2ae0
Content-Disposition: form-data; name="Filename"
 
logo-image-small.png
------------ae0cH2KM7Ef1gL6KM7Ef1gL6cH2ae0
Content-Disposition: form-data; name="sessionKey"
 
qbbqFksgdDVuXONpDqQbX8qBP
------------ae0cH2KM7Ef1gL6KM7Ef1gL6cH2ae0
Content-Disposition: form-data; name="categoryId"
 
22
------------ae0cH2KM7Ef1gL6KM7Ef1gL6cH2ae0
Content-Disposition: form-data; name="Filedata"; filename="logo-image-small.png"
Content-Type: application/octet-stream
 
 
------------ae0cH2KM7Ef1gL6KM7Ef1gL6cH2ae0
Content-Disposition: form-data; name="Upload"
 
Submit Query
------------ae0cH2KM7Ef1gL6KM7Ef1gL6cH2ae0--

Step 2: Call the createAssetFromFile method

Please note that the following parameter values are the same for both step 1 and step 2:

  • sessionKey
  • fileName
  • folderId

This allows NetX to properly associate the uploaded file with the upload call.

Please note the following:

  1. Step 1 MUST be complete before you make the createAssetFromFile call. This means you MUST wait for an HTTP status code of 200 to be returned from step 1 before proceeding to step 2.
  2. If you are using Hydra, you can import to any node you want. However, for each asset imported, step 1 and step 2 MUST be performed on the same node.
  3. The user you are using to make API calls MUST have permission to import assets into the category.

Parameters

Parameter Description
options
data (see data options below)
sessionKey
A user's active session key
fileName
A collection of search criteria
folderId
Parent folder ID for the new asset

Data options

Option Description
asset.proxies
Info about the asset proxy files (thumbnail, preview, zoom)
asset.views
Info about any views attached to the asset
asset.relatedAssets
Info about assets related to the asset
asset.folders
Info about the asset's parent folders
asset.attributes
Attribute data for each asset
asset.id
Asset ID
asset.base
Asset name, creation date, import date, modification date
asset.file
File name, size, width, height, checksum, URL

Returns

The new asset object.

Example

Example request:

{
  "id": "7441158495944158",
  "method": "createAssetFromFile",
  "params": [
    "qbbqFksgdDVuXONpDqQbX8qBP",
    "logo-image-small.png",
    22,
    {
      "data": [
        "asset.id",
        "asset.base",
        "asset.file"
      ]
    }
  ],
  "dataContext": "json",
  "jsonrpc": "2.0"
}

Example response:

{
  "result": {
    "id": 71,
    "name": "logo-image-small",
    "file": {
      "name": "logo-image-small.png",
      "size": 3249,
      "width": null,
      "height": null,
      "url": "/file/asset/71/original/attachment"
    },
    "proxies": null,
    "views": null,
    "relatedAssets": null
  },
  "id": "7441158495944158",
  "jsonrpc": "2.0"
}

Views

createViewFromFile

This call is similar to the createAssetFromFile call in that the file must be uploaded to NetX before this call is made, with the same caveats and restrictions. Please see Upload the file for details.

Parameters

Month Savings
options
data (see data options below)
sessionKey
A user's active session key
fileName
Name of the file
view
A user's active session key

Data options

Option Description
view.id
The view's unique ID
view.name
View name
view.file
An optional description of the view
 

Returns

The new view object.

Example

Example request:

{
  "id": "7530249697533316",
  "method": "createViewFromFile",
  "params": [
    "bCuhAegEZyJ66sWM7n95EUMbq",
    "view_1.png",
    {
      "id": 0,
      "name": "New View",
      "description": "Test View",
      "assetId": 71
    },
    {
      "data": [
        "view.id",
        "view.base",
        "view.file"
      ]
    }
  ],
  "dataContext": "json",
  "jsonrpc": "2.0"
}

Example response:

{
  "result": {
    "id": 80,
    "name": "New View",
    "description": "Test View",
    "assetId": 71,
    "file": {
      "name": "view_80.png",
      "size": 14576,
      "width": 500,
      "height": 500,
      "url": "/assetViews/0000/71/view_80.png"
    }
  },
  "id": "7530249697533316",
  "jsonrpc": "2.0"
}

getViewById

Finds the view with a given ID.

Parameters

Parameter Description
sessionKey
A user's active session key
viewId
A view's unique ID
options
data (see data options below)

Data options

Parameter  Description
view.id
The view's unique ID
view.base
View name
view.file
An optional description of the view

Returns

A view object.

Example

Example request:

{
  "id": "7530871356090573",
  "method": "getViewById",
  "params": [
    "bCuhAegEZyJ66sWM7n95EUMbq",
    80,
    {
      "data": [
        "view.id",
        "view.base",
        "view.file"
      ]
    }
  ],
  "dataContext": "json",
  "jsonrpc": "2.0"
}

Example response:

{
  "result": {
    "id": 80,
    "name": "New View",
    "description": "Test View",
    "assetId": 71,
    "file": {
      "name": "view_80.png",
      "size": 14576,
      "width": 500,
      "height": 500,
      "url": "/assetViews\0000/71/view_80.png"
    }
  },
  "id": "7530871356090573",
  "jsonrpc": "2.0"
}

getViewsByAsset

Finds views with a given parent asset.

Parameters

Parameter Description
sessionKey
A user's active session key
assetId
An asset's unique ID
options
page data (see data options below)

Data options

Option Description
view.id
The view's unique ID
view.base
View name
view.file
An optional description of the view

Returns

A page of view objects.

Example

Example request:

{
  "id": "7531198788138214",
  "method": "getViewsByAsset",
  "params": [
    "bCuhAegEZyJ66sWM7n95EUMbq",
    71,
    {
      "page": {
        "startIndex": 0,
        "size": 10
      },
      "data": [
        "view.id",
        "view.base",
        "view.file"
      ]
    }
  ],
  "dataContext": "json",
  "jsonrpc": "2.0"
}

Example response:

{
  "result": {
    "results": [
      {
        "id": 79,
        "name": "previewXMP",
        "description": "Asset Metadata",
        "assetId": 71,
        "file": {
          "name": "view_79.xmp",
          "size": 1796,
          "width": null,
          "height": null,
          "url": "/assetViews/0000/71/view_79.xmp"
        }
      },
      {
        "id": 80,
        "name": "New View",
        "description": "Test View",
        "assetId": 71,
        "file": {
          "name": "view_80.png",
          "size": 14576,
          "width": 500,
          "height": 500,
          "url": "/assetViews/0000/71/view_80.png"
        }
      },
      {
        "id": 81,
        "name": "New View 2",
        "description": "Test View 2",
        "assetId": 71,
        "file": {
          "name": "view_81.png",
          "size": 91392,
          "width": 2000,
          "height": 2000,
          "url": "/assetViews/0000/71/view_81.png"
        }
      }
    ],
    "size": 3
  },
  "id": "7531198788138214",
  "jsonrpc": "2.0"
}

updateView

Updates a view's writable data.

Parameters

Parameter Description
sessionKey
A user's active session key
view
A view's writable data
options
data (see data options below)

Data options

Option Description
view.id
The view's unique ID
view.base
View name
view.file
An optional description of the view

Returns

The updated view object.

Example

Example request:

{
  "id": "7531572488802793",
  "method": "updateView",
  "params": [
    "bCuhAegEZyJ66sWM7n95EUMbq",
    {
      "id": 80,
      "name": "New View Name",
      "description": "New View Description",
      "assetId": 71,
      "file": {
        "name": "view_80.png",
        "size": 14576,
        "width": 500,
        "height": 500,
        "url": "/assetViews/0000/71/view_80.png"
      }
    },
    {
      "data": [
        "view.id",
        "view.base",
        "view.file"
      ]
    }
  ],
  "dataContext": "json",
  "jsonrpc": "2.0"
}

Example response:

{
  "result": {
    "id": 80,
    "name": "New View Name",
    "description": "New View Description",
    "assetId": 71,
    "file": {
      "name": "view_80.png",
      "size": 14576,
      "width": 500,
      "height": 500,
      "url": "/assetViews/0000/71/view_80.png"
    }
  },
  "id": "7531572488802793",
  "jsonrpc": "2.0"
}

deleteView

Deletes the view with a given ID.

Parameters

Parameter Description
viewId
A view's unique ID
sessionKey
A user's active session key
 

Data options

None

Returns

An empty object.

Example

Example request:

{
  "id": "7531866794686999",
  "method": "deleteView",
  "params": [
    "bCuhAegEZyJ66sWM7n95EUMbq",
    80,
    null
  ],
  "dataContext": "json",
  "jsonrpc": "2.0"
}

Example response:

{
  "result": {
     
  },
  "id": "7531866794686999",
  "jsonrpc": "2.0"
}

Collections

getCollectionsByUser

Retrieves collection objects a user has a minimum of Viewer permissions for.

Parameters

Parameter Description
sessionKey
A user's active session key
userId
ID of the user to retrieve collections for
options
page data (see data options below)

Data options

Option Description
collection.id
The collections's unique ID
collection.base
Collection name and item count

Returns

A page of collection objects.

getAssetsByCollection

Retrieves assets contained in a specific collection.

Parameters

Parameter Description
sessionKey
A user's active session key
collectionId
id of the collection to return contents of
options
page data (see data options below)

Data options

Option Description
asset.proxies
Info about the asset proxy files (thumbnail, preview, zoom)
asset.views
Info about any views attached to the asset
asset.relatedAssets
Info about assets related to the asset
asset.folders
Info about the asset's parent folders
asset.attributes
Attribute data for each asset
asset.id
Asset ID
asset.base
Asset name, creation date, import date, modification date
asset.file
File name, size, width, height, checksum, URL

Returns

A page of asset objects.

Was this article helpful?
0 out of 0 found this helpful