NAV Navbar
C# Ruby

Introduction

This is the OpenAsset API Reference.

Each category will be dedicated to a resource and endpoint exposed by our API. At the start of each category we will list the Resource Model Object including an example on the right hand side. The articles following the object will contain examples on how to Create, Update or Delete the object.

We will provide examples in C# and Ruby which leverage our publicly available REST Libraries.

You can find more information about these libraries here:

Authentication

In order to access restricted resources in the API, you will need to provide your credentials (and have the correct permissions). The credentials should be encoded using Base64 with the following format: username:password

The Base64 encoded string should then be included in the request header with the following syntax:

Authorization: Basic <base64(username:password)>

HTTP Verbs

The following verbs are available unless otherwise specified:

Verb Description
HEAD When used against a resource, it will return only the HTTP header info. This is essentially a GET method with the body stripped.
GET Retrieve resources.
POST Creating new resources and/or performing actions
PUT Replacing and/or updating a resource.
DELETE Deleting a resource.
MERGE Merging a resource.

Data Types

The REST API documentation describes value types using the following data types as descriptions:

Name Description
string Alphanumeric characters, limits are specified if they are exceeded in a response error message. Default limit is 256 characters.
text Alphanumeric characters. Used to represent larger amounts of text. The default limit is 65535 characters.
integer Whole number.
boolean True represented by 1 and False represented by 0.
enum These are set values, usually strings. They will be described in greater detail when mentioned.
hash Generated by OpenAsset. This is a unique hash represented by a Hex string.
operator Used to describe a search operator, these are: AND/OR
datetime Datetime represented in the following format: YYYYMMDDhhmmss

Parameters

Parameter Value Type Usage Default
<field_name> <field_value_type> This will be explained in more detail for each verb. Essentially every field returned by the API is searchable as a parameter in the query. See filtering none
limit integer This is used to limit the amount of results returned by a query. 10
offset integer This is used to offset the results returned, i.e. offset=5 will show results starting from the 6th result (hiding the first 5). 0
textMatching string Change the way in which text matching is performed. See filtering The options are: contains, exact​​, wildcard contains
orderBy string[,string] Change the order in which results are returned. The direction can also be manipulated. Below is are some examples:idDesc​ididAsc​codeDescIt's important to note that the direction is attached on to the end of the value and is case sensitive. This parameter can take multiple arguments. none
displayFields string[,string] This parameter allows you to define which fields to return for your particular object. This is obviously Verb dependent. none
filterBy array / object / json string This is used for advanced filtering operations. See filtering none

Filtering

Basic Filters

Basic parameter filtering is available for most endpoints, and can be utilized by adding the parameter into the URL of the HTTP request itself. Each item on the URL is treated as an AND operation in conjunction with the other filters. For a specific parameter, you may either give an Array or comma delimited list as an OR operation for that parameter.

Numeric and Date Operators

Operator Examples Description
- 1-5, 2019/01/01-2019/01/31 Range of numbers or dates, including the first and last value given
< or <= <5, <=2018/01/01 Less than, less than or equal to a given number or date
> or >= >100, >=2019/01/01 Greater than, greater than or equal to a given number
! !5, !2018/12/25 Not equal to that number or date

Text Matching

For all basic filtering parameters, the textMatching parameter can have the value of exact, contains, or wildcard. The parameter will default to contains.

URL Arrays and Objects

Some simple value to URL examples:

a = {
    "b": 1,
    "c": 2
}

becomes

https://example.openasset.com/REST/1/Headers?a[b]=1&a[c]=2



d = ["test", 15, "hello", "world"]

becomes

https://example.openasset.com/REST/1/Headers?d[]=test&d[]=15&d[]=hello&d[]=world

Parameters can be sent as arrays or objects. Normally this is used to send an array of values for an OR basic filter instead of comma delimited. The jQuery XHR library will do this automatically to any JS object/array sent as a parameter but for other languages you will have to manually do this.

To make a parameter into an array or object, you just need to repeatedly add the parameter to the URL.

Arrays

parameter[0]= value& parameter[1]= value2

Objects

parameter[a]= value& parameter[b]= value2

It is possible to nest objects - Nesting objects requires doubling up of the index as follows:

parameter[a][ ]= value& parameter[b][ ]= value2

Advanced Filters

Search for the string 'test' anywhere within name or code

filterBy = [
    {
        "name": "*test*"
    },
    {
        "code": "*test*"
    }
];

More advanced filters can be done by adding the filterBy parameter to any given request. By passing a JSON array or object to this parameter, you can define complex rules of AND and OR when filtering results. For making this parameter easier to work with, you can also pass a JSON string representation of the filter to this parameter.

By default, an array is treated as an OR operation and the key/value pairs of an object are treated as an AND operation. You may use the special values -or or -and to change this behavior. Within an object, use them for a key to another array or object to set that array or object's behavior. For an array, if -or or -and is the first value in the array, they change the behavior for the rest of that particular array.

The same numeric and date operators above apply to those types of values. Text searching only uses the wildcard mode described.

Headers

The REST API employs several custom HTTP Headers to aid the user. These are described below.

Header Description
X-SessionKey Key used to persist a session across calls.
X-Full-Results-Count Number of total results in the system.
X-Display-Results-Count Number of results being returned.
X-Offset If the results are offset, this is the offset start point.
X-Timing Time taken to process the action.
X-Username Name of the user (if authenticated).
X-User-Id Id of the user (if authenticated).
X-OpenAsset-Version Version number of OpenAsset being called.
X-Ignored-Fields These are fields that were ignored during a PUT or POST action; i.e. these fields have not been updated.

Albums

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Query Parameters: Albums

Example JSON Object:

{
    "all_users_can_modify": 0,
    "approved_company_album": 1,
    "can_modify": 0,
    "code": "d80287b09c072265afeaba9cab51b8cf",
    "company_album": 0,
    "created": "20110818161655",
    "description": "",
    "id": 1,
    "locked": 0,
    "my_album": 0,
    "name": "Album 1",
    "private_image_count": "0,0,0,0,0,0,0",
    "public_image_count": "0,0,0,0,0,0,0",
    "share_with_all_users": 0,
    "shared_album": 0,
    "unapproved_image_count": "0,0,0,0,0,0,0",
    "updated": "0",
    "user_id": 5
}
Parameter Type Description
all_users_can_modify boolean Whether this album can be modified by all users. Default value is false.
approved_company_album boolean Whether this album is an approved company album. Default value is false.
can_modify boolean Whether this user can modify this album.
code string Unique identifier for code for the album.
company_album boolean Whether this is a company album.
created datetime Date this album was created.
description string A string associated with the description of the album.
id integer The unique ID of the album
locked boolean Whether this album is locked. Default value is false.
my_album boolean Whether this album belongs to the current user.
name string The name of this album.
private_image_count string A string of integers (comma delimited) representing the private images in this album, per category.
public_image_count string A string of integers (comma delimited) representing the public images in this album, per category.
share_with_all_users boolean Whether this album has been shared with all users.
shared_album boolean Whether this album has been shared with anyone.
unapproved_image_count string A string of integers (comma delimited) representing the uploaded but not yet approved images in this album, per category.
updated datetime The last time this album was updated.
user_id integer The unique ID of the user that owns this album.

Get All Albums

This endpoint retrieves 10 albums by default. To get ALL albums on the endpoint add 'limit=0' to the request.

Example query:

private static List<Album> GetAlbums()
        {
            RESTOptions<Album> options = new RESTOptions<Album>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Album>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
albums = @@butler.get_albums

HTTP Request

GET https://example.openasset.com/REST/1/Albums

To get all albums on the instance:

GET https://example.openasset.com/REST/1/Albums?limit=0

Get a Specific Album

This endpoint retrieves a specific Album.

Example query - Get album ID 41:

private static List<Album> GetAlbums()
        {
            RESTOptions<Album> options = new RESTOptions<Album>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Album>(41);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
albums = @@butler.get_albums(options)

HTTP Request

GET https://example.openasset.com/REST/1/Albums/:id

URL Parameters

Parameter Description
ID The ID of the Album to retrieve

Update a Specific Album

Certain attributes of a Album noun can be updated. Below are the different attributes that can be updated:

Update the description of a album.

// Create a new album object
Album albumItem = new Album();

// Set the id to an existing image in OpenAsset
albumItem.Id = 41;

// Updating its description field
albumItem.name = "Updated Name!!";

// Make a PUT request by setting the last parameter as FALSE
Album responseAlbum = conn.SendObject<Album>(albumItem, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
options.add_option('name', 'Updated name!!')
albums = @@butler.update_albums(options)

HTTP Request

PUT https://example.openasset.com/REST/1/Albums/:id

Attributes that can be updated

Parameter Type Description
all_users_can_modify boolean Whether this album can be modified by all users. Default value is false.
approved_company_album boolean Whether this album is an approved company album. Default value is false.
company_album boolean Whether this is a company album.
description string A string associated with the description of the album.
locked boolean Whether this album is locked. Default value is false.
name string The name of this album.
share_with_all_users boolean Whether this album has been shared with all users.
files int/array[integers] The file(s) to include in the album. Accepts an array of file ids as well.

Updating Multiple Albums

PUT Request:

[
    {
        "id": 40,
        "description": "we're updating the description of this album"
    },
    {
        "id": 420,
        "name": "We're updating the name of this album"
    }
]

PUT (Truncated) Example Response:

[
    {
        "id": 40,
        "_http_header_X_Ignored_Fields": "id",
        "description": "we're updating the description of this album",
        "http_status_code": 200
    },
    {
        "id": 420,
        "_http_header_X_Ignored_Fields": "id",
        "name": "We're updating the name of this album",
        "http_status_code": 200
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/Albums/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new Album

This endpoint allows creation of albums. The minimum required parameters to include in a new Album POST request are:

Parameter Types Description
name string The string associated with the display name of this album.
// Create a new album object
Album albumItem = new Album();

// Set the name of the album.
albumItem.Name = "This is my album name";

// Make a POST request by setting the last parameter as TRUE
conn.SendObject<Album>(albumItem, true);
require 'openasset-rest-client'
client = OpenAsset::RestClient.new("url","username","password")
my_new_album = Albums.new("This is my album name")
client.create_albums(my_new_album)

HTTP Request

POST https://example.openasset.com/REST/1/Albums/

Delete a Specific Album

This endpoint allows deletion of albums.

HTTP Request

// Create a new album object
Album albumItem = new Album();

// Set the id to an existing image in OpenAsset
albumItem.Id = 41;

// Send the Album object to the DeleteObject method
conn.DeleteObject(noun);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')

# Any method below would work.
butler.delete_albums([41,42,43])
butler.delete_albums(['41','42','43'])
butler.delete_albums(41)
butler.delete_albums('41')

DELETE https://example.openasset.com/REST/1/Albums/:id

or

DELETE https://example.openasset.com/REST/1/Albums?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the album to delete

Merge Albums

MERGE Request:

[
    {
        "id": 40
    },
    {
        "id": 42
    }
]

or

[
    40,
    42
]

This endpoint allows the merging of one or more Albums into a single Album. This targets a single Album, with the body being an array of IDs or objects containing the ID of the albums you want merged with the original Album.

The response is the individual object GET after the merge request has completed.

HTTP Request

MERGE https://example.openasset.com/REST/1/Albums/:id

AspectRatios

Available HTTP Verbs include:

GET

Query Parameters: AspectRatios

Example JSON Object:

{
        "id": 1,
        "code": "landscape",
        "label": "Landscape"
    }
Parameter Type Description
id integer The unique ID of this AspectRatio
code string The code associated with this AspectRatio
label string The display string associated with this AspectRatio

Get All AspectRatios

This endpoint retrieves 10 aspect ratios by default. To get ALL aspect ratios on the endpoint add 'limit=0' to the request.

Example query:

private static List<AspectRatio> GetAspectRatios()
        {
            RESTOptions<AspectRatio> options = new RESTOptions<AspectRatio>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com", 
                "username", 
                "password"
            );
            return conn.GetObjects<AspectRatio>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
aspectRatios = @@butler.aspectRatios

HTTP Request

GET https://example.openasset.com/REST/1/AspectRatios

To get all aspect ratios on the instance:

GET https://example.openasset.com/REST/1/AspectRatios?limit=0

Get a Specific AspectRatio

This endpoint retrieves a specific AspectRatio.

Example query - Get aspectratio ID 41:

private static List<AspectRatio> GetAspectRatios()
        {
            RESTOptions<AspectRatio> options = new RESTOptions<AspectRatio>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com", 
                "username", 
                "password"
            );
            return conn.GetObjects<AspectRatio>(1);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
aspectRatios = @@butler.get_aspectRatios(1)

HTTP Request

GET https://example.openasset.com/REST/1/AspectRatios/:id

URL Parameters

Parameter Description
ID The ID of the AspectRatio to retrieve

Categories

Available HTTP Verbs include:

GET

PUT

Query Parameters: Categories

Example JSON Object:

{
    "alive": 1,
    "code": "Projects",
    "default_access_level": 2,
    "default_rank": 5,
    "description": "",
    "display_order": 1,
    "id": 1,
    "maximum_rank": 10,
    "name": "Projects",
    "projects_category": 1,
    "updated": "20190522184317"
}
Parameter Type Description
alive boolean Whether this category is enabled or disabled.
code string The unique identifying code for this category.
default_access_level string The default access level for any files uploaded to this category.
default_rank integer The default rank for any files uploaded to this category.
description string A string describing this category.
display_order integer The numerical order in which to display this category on the Categories page. The lower the number, the higher it's priority.
id integer The unique ID for this category.
maximum_rank integer The maximum allowed numerical rank for images uploaded to this category.
name string The Name given to this Category.
projects_category boolean Whether this is a Projects category.
updated datetime When the category information was last updated.

Get All Categories

This endpoint retrieves 10 categories by default. To get ALL categories on the endpoint add 'limit=0' to the request.

Example query:

private static List<Category> GetCategories()
        {
            RESTOptions<Category> options = new RESTOptions<Category>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Category>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
categories = @@butler.get_categories

HTTP Request

GET https://example.openasset.com/REST/1/Categories

To get all categories on the instance:

GET https://example.openasset.com/REST/1/Categories?limit=0

Get a Specific Category

This endpoint retrieves a specific Category.

Example query - Get categorie ID 41:

private static List<Category> GetCategories()
        {
            RESTOptions<Category> options = new RESTOptions<Category>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Category>(41);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
categories = @@butler.get_categories(options)

HTTP Request

GET https://example.openasset.com/REST/1/Categories/:id

URL Parameters

Parameter Description
ID The ID of the Category to retrieve

Update a Specific Category

Certain attributes of a Category noun can be updated. Below are the different attributes that can be updated:

Update the description of a category.

// Create a new category object
Category categoryItem = new Category();

// Set the id to an existing image in OpenAsset
categoryItem.Id = 41;

// Updating its description field
categoryItem.Name = "New Name";

// Make a PUT request by setting the last parameter as FALSE
Category responseCategory = conn.SendObject<Category>(categoryItem, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
options.add_option('name', 'New Name')
categorys = @@butler.update_categorys(options)

HTTP Request

PUT https://example.openasset.com/REST/1/Categories/:id

Attributes that can be updated

Parameter Type Description
alive boolean Whether this category is enabled or disabled.
default_access_level string The default access level for any files uploaded to this category.
default_rank integer The default rank for any files uploaded to this category.
description string A string describing this category.
display_order integer The numerical order in which to display this category on the Categories page. The lower the number, the higher it's priority.
name string The Name given to this Category.

Updating Multiple Categories

PUT Request:

[
    {
        "id": 1,
        "name": "Category1 Name Change!",
        "description": "We updated the Description of Projects Category",
        "alive": 1
    },
    {
        "id": 2,
        "description": "Another update!",
        "alive": 1
    },
    {
        "id": 3,
        "alive": 0
    }
]

PUT (Truncated) Example Response:

[
    {
        "name": "Category1 Name Change!",
        "_http_header_X_Ignored_Fields": "id",
        "id": 1,
        "description": "We updated the Description of Projects Category",
        "alive": 1,
        "http_status_code": 200
    },
    {
        "name": "Reference",
        "_http_header_X_Ignored_Fields": "id",
        "id": 2,
        "description": "Another update!",
        "alive": 1,
        "http_status_code": 200
    },
    {
        "name": "Staff",
        "_http_header_X_Ignored_Fields": "id",
        "id": 3,
        "description": "",
        "alive": 0,
        "http_status_code": 200
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/Categories/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

CopyrightHolders

Available HTTP Verbs include:

GET

POST

PUT

MERGE

Query Parameters: CopyrightHolders

Example JSON Object:

{
    "copyright_policy_id": 0,
    "id": 1,
    "name": "OpenAsset",
    "updated": "20190211141701"
}
Parameter Type Description
copyright_policy_id integer The ID of the CopyrightPolicy associated with this CopyrightHolder. Value is 0 if no associated Policy.
id integer The unique ID of this CopyrightPolicy
name string The display name for this CopyrightHolder.
updated datetime When this CopyrightHolder was last updated.

Get All CopyrightHolders

This endpoint retrieves 10 CopyrightHolders by default. To get ALL CopyrightHolders on the endpoint add 'limit=0' to the request.

Example query:

private static List<CopyrightHolder> GetCopyrightHolders()
        {
            RESTOptions<CopyrightHolder> options = new RESTOptions<CopyrightHolder>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<CopyrightHolder>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
copyrightHolders = @@butler.copyrightHolders

HTTP Request

GET https://example.openasset.com/REST/1/CopyrightHolders

To get all CopyrightHolders on the instance:

GET https://example.openasset.com/REST/1/CopyrightHolders?limit=0

Get a Specific CopyrightHolders

This endpoint retrieves a specific CopyrightHolders.

Example query - Get copyrightholder ID 41:

private static List<CopyrightHolder> GetCopyrightHolders()
        {
            RESTOptions<CopyrightHolder> options = new RESTOptions<CopyrightHolder>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<CopyrightHolder>(1);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
copyrightHolders = @@butler.get_copyrightHolders(1)

HTTP Request

GET https://example.openasset.com/REST/1/CopyrightHolders/:id

URL Parameters

Parameter Description
ID The ID of the CopyrightHolder to retrieve

Update a Specific CopyrightHolder

Certain attributes of a CopyrightHolder noun can be updated. Below are the different attributes that can be updated:

Parameter Types Description
name string The string associated with the display name of this CopyrightHolder.
copyright_policy_id integer The unique ID of the copyright policy to associate with this Copyright Holder

Update the name of a copyrightholder.

CopyrightHolder copyrightHolderObject = new CopyrightHolder();

copyrightHolderObject.id   = 1;
copyrightHolderObject.name = "New name for this CopyrightHolder!";

CopyrightHolder responseCopyrightHolder = conn.SendObject<CopyrightHolder>(copyrightHolderObject, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '1')
options.add_option('name', 'New name for this CopyrightHolder!')
copyrightHolders = @@butler.update_copyrightHolders(options)

HTTP Request

PUT https://example.openasset.com/REST/1/CopyrightHolders/:id

Attributes that can be updated

Parameter Type Description
copyright_policy_id integer The ID of the CopyrightPolicy associated with this CopyrightHolder. Value is 0 if no associated Policy.
name string The display name for this CopyrightHolder.

Updating Multiple CopyrightHolders

PUT Request:

[
    {
        "id": 40,
        "copyright_policy_id": 4
    },
    {
        "id": 420,
        "name": "We're updating the name of this CopyrightHolder"
    }
]

PUT (Truncated) Example Response:

[
    {
        "name": "Tim Apple",
        "_http_header_X_Ignored_Fields": "id",
        "id": 1,
        "copyright_policy_id": 0,
        "http_status_code": 200
    },
    {
        "name": "Steve Microsoft",
        "_http_header_X_Ignored_Fields": "id",
        "id": 2,
        "copyright_policy_id": 1,
        "http_status_code": 200
    }
]
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/CopyrightHolders/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new CopyrightHolder

This endpoint allows creation of CopyrightHolders. Below are the required minimum parameters to POST:

Parameter Type Description
name string The display name associated with this CopyrightHolder
copyright_policy_id integer The CopyrightPolicy that this CopyrightHolder is associated with.
// Create a new copyrightHolder object
CopyrightHolder copyrightHolderItem = new CopyrightHolder();

//Set the name of the copyright
copyrightHolderItem.Name = "Tim Apple";
copyrightHolderItem.Copyright_policy_id = 1;
// Make a POST request by setting the last parameter as TRUE
conn.SendObject<CopyrightHolder>(copyrightHolder, true);

HTTP Request

POST https://example.openasset.com/REST/1/CopyrightHolders/

Merge CopyrightHolders

MERGE Request:

[
    {
        "id": 40
    },
    {
        "id": 42
    }
]

or

[
    40,
    42
]

This endpoint allows the merging of one or more CopyrightHolders into a single CopyrightHolder. This targets a single CopyrightHolder with the body being an array of ids or objects containing the id of what you want merged.

The response is the individual object GET after the merge request is completed.

HTTP Request

MERGE https://example.openasset.com/REST/1/CoprightHolders/:id

CopyrightPolicies

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Query Parameters: CopyrightPolicies

Example JSON Object:

{
    "code": "9610d09b1fedfbdfd80ed1a620a6fba4",
    "description": "",
    "id": 1,
    "name": "This is a new policy",
    "updated": "20190614200024"
}
Parameter Type Description
code string Unique code associated with this CopyrightPolicy
description string A description associated with this CopyrightPolicy
id integer The unique ID for this CopyrightPolicy
name string The display name for this CopyrightPolicy
updated datetime The last time this CopyrightPolicy was updated.

Get All CopyrightPolicies

This endpoint retrieves 10 CopyrightPolicies by default. To get ALL CopyrightPolicies on the endpoint add 'limit=0' to the request.

Example query:

private static List<CopyrightPolicy> GetCopyrightPolicys()
        {
            RESTOptions<CopyrightPolicy> options = new RESTOptions<CopyrightPolicy>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<CopyrightPolicy>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
copyrightPolicies = @@butler.copyrightPolicies

HTTP Request

GET https://example.openasset.com/REST/1/CopyrightPolicies

To get all CopyrightPolicies on the instance:

GET https://example.openasset.com/REST/1/CopyrightPolicies?limit=0

Get a Specific CopyrightPolicies

This endpoint retrieves a specific CopyrightPolicies.

Example query - Get CopyrightPolicy ID 41:

private static List<CopyrightPolicy> GetCopyrightPolicies()
        {
            RESTOptions<CopyrightPolicy> options = new RESTOptions<CopyrightPolicy>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<CopyrightPolicy>(1);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
copyrightPolicies = @@butler.get_copyrightPolicies(1)

HTTP Request

GET https://example.openasset.com/REST/1/CopyrightPolicies/:id

URL Parameters

Parameter Description
ID The ID of the CopyrightPolicies to retrieve

Update a Specific CopyrightPolicies

Update the description of a CopyrightPolicy.

CopyrightPolicy copyrightPolicyObject = new CopyrightPolicy();

copyrightPolicyObject.id   = 1;
copyrightPolicyObject.name = "New name for this CopyrightPolicy!";

CopyrightPolicy responseCopyrightPolicy = conn.SendObject<CopyrightPolicy>(copyrightPolicyObject, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '1')
options.add_option('name', 'New name for this CopyrightPolicy!')
copyrightPolicies = @@butler.update_copyright_policies(options)

Certain attributes of a CopyrightPolicies noun can be updated. Below are the different attributes that can be updated:

Parameter Types Description
name string The string associated with the display name of this Copyright Policy
description string The description associated with this Copyright policy.

Updating Multiple CopyrightPolicies

PUT Request:

[
    {
        "id": 40,
        "description": "we're updating the description of this album"
    },
    {
        "id": 420,
        "name": "We're updating the name of this album"
    }
]

PUT (Truncated) Example Response:

[
    {
        "id": 40,
        "_http_header_X_Ignored_Fields": "id",
        "description": "we're updating the description of this album",
        "http_status_code": 200
    },
    {
        "id": 420,
        "_http_header_X_Ignored_Fields": "id",
        "name": "We're updating the name of this album",
        "http_status_code": 200
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/Albums/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new CopyrightPolicy

// Create a new copyrightPolicy object
CopyrightPolicy copyrightPolicyItem = new CopyrightPolicy();

//Set the name of the copyright
copyrightPolicyItem.Name = "This is my Copyright policy";

// Make a POST request by setting the last parameter as TRUE
conn.SendObject<CopyrightPolicy>(copyrightPolicy, true);

This endpoint allows creation of CopyrightPolicies. Below are the required minimum parameters to POST:

Parameter Type Description
name string The display name associated with this CopyrightPolicy

HTTP Request

POST https://example.openasset.com/REST/1/CopyrightPolicy/

Delete a Specific CopyrightPolicies

This endpoint allows DELETES of CopyrightPolicies.

HTTP Request

// Create a new copyrightPolicy object
CopyrightPolicy copyrightPolicyItem = new CopyrightPolicy();

// Set the id to an existing image in OpenAsset
copyrightPolicyItem.Id = 41;

// Send the CopyrightPolicy object to the DeleteObject method
conn.DeleteObject(noun);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')

# Any method below would work.
butler.delete_copyright_policy([41,42,43])
butler.delete_copyright_policy(['41','42','43'])
butler.delete_copyright_policy(41)
butler.delete_copyright_policy('41')

DELETE https://example.openasset.com/REST/1/CopyrightPolicies/:id

or

DELETE https://example.openasset.com/REST/1/CopyrightPolicies?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the CopyrightPolicy to delete

Merge CopyrightPolicies

MERGE Request:

[
    {
        "id": 40
    },
    {
        "id": 42
    }
]

or

[
    40,
    42
]

This endpoint allows the merging of one or more CopyrightPolicies into a single CopyrightPolicy. This targets a single CopyrightPolicy with the body being an array of ids or objects containing the id of what you want merged.

The response is the individual object GET after the merge request is completed.

HTTP Request

MERGE https://example.openasset.com/REST/1/CoprightPolicies/:id

Employees

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Query Parameters: Employees

Example JSON Object:

{
    "alive": 1,
    "code": "Code123",
    "created": "20150102030405",
    "first_name": "John",
    "descriptor": "John Doe",
    "id": "",
    "last_name": "Doe",
    "updated": ""
}
Parameter Type Description
alive bool Whether the project is enabled (1), or disabled (0).
code string Unique identifying string for this Employee object.
created datetime The time at which this employee object was created.
first_name string String of the first name of this Employee object.
descriptor string Default concatenation of first_name and last_name.
last_name string String of the last name of this Employee Object.
updated datetime The last time this employee object was updated.

Get All Employees

This endpoint retrieves 10 employees by default. To get ALL employees on the endpoint add 'limit=0' to the request.

Example query:

HTTP Request

GET https://example.openasset.com/REST/1/Employees

To get all employees on the instance:

GET https://example.openasset.com/REST/1/Employees?limit=0

Get a Specific Employee

This endpoint retrieves a specific Employee.

Example query - Get employee ID 41:

HTTP Request

GET https://example.openasset.com/REST/1/Employees/:id

URL Parameters

Parameter Description
ID The ID of the Employee to retrieve

Update a Specific Employee

Certain attributes of a Employee noun can be updated. Below are the different attributes that can be updated:

Update the description of a employee.

HTTP Request

PUT https://example.openasset.com/REST/1/Employees/:id

Create a new Employee

This endpoint allows for the creation of new Employees. The minimum required parameters to include in an Employee POST request are:

Delete a Specific Employee

This endpoint allows DELETES of employees.

HTTP Request

DELETE https://example.openasset.com/REST/1/Employees/:id

or

DELETE https://example.openasset.com/REST/1/Employees?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the employee to delete

Fields

Available HTTP Verbs Inlucde:

GET

POST

PUT

DELETE

Query Parameters: Fields

Example JSON Object:

{
    "alive": 1,
    "built_in": 0,
    "cardinality": 1,
    "code": "Client",
    "description": "",
    "display_order": 5,
    "field_display_type": "suggestion",
    "field_type": "project",
    "id": 1,
    "include_on_info": 0,
    "include_on_search": 1,
    "name": "Client",
    "protected": 0,
    "regex": "",
    "regex_description": "",
    "required": 0,
    "rest_code": "Client",
    "updated": "20180726164253"
}
Enumerables Description
suggestion The front-end will automatically try to suggest possible inputs for this field.
fixedSuggestion The front-end will automatically try to suggest possible inputs for this field, but you cannot create new inputs.
option Select style drop down.
singleLine Text will be displayed over a single line.
multiLine Text will be displayed over multiple lines. Can use paragraph breaks.
date A calendar Date field
Parameter Type Description
alive boolean Whether this field is enabled or disabled.
built_in boolean Whether this field is a custom field or a built in field.
cardinality integer The number of possible entries/values on this field. Currently defaults to 1.
code string Unique string for identifying the Field.
description string A description of this field's intended purpose.
display_order integer The order in which this field is displayed in different areas of the product. Such as the Projects page and Fields list page.
field_display_type enum The manner in which this field displays its information
field_type enum The object type this field is associated with: either an Image, Project or Employee object.
id integer The unique ID associated with this Field.
include_on_info boolean Denotes whether this field will be hidden from the front-end information pages.
include_on_search boolean Whether this field will be taken into consideration when utilizing the main search feature.
name string The display name of this field.
protected boolean Whether this is a protected field. Usually reserved for critical fields such as Builtin fields.
regex string The values must match this regex string to be valid.
regex_description string A description of the regex requirement.
required boolean Whether this field is required for any POST requests or not.
rest_code string The rest API code associated with this Field.
updated datetime The last time this field was updated.

Get All Fields

This endpoint retrieves 10 fields by default. To get ALL fields on the endpoint add 'limit=0' to the request.

Example query:

private static List<Field> GetFields()
        {
            RESTOptions<Field> options = new RESTOptions<Field>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Field>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
fields = @@butler.fields

HTTP Request

GET https://example.openasset.com/REST/1/Fields

To get all fields on the instance:

GET https://example.openasset.com/REST/1/Fields?limit=0

Get a Specific Field

This endpoint retrieves a specific Field.

Example query - Get field ID 41:

private static List<Field> GetFields()
        {
            RESTOptions<Field> options = new RESTOptions<Field>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Field>(1);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
fields = @@butler.get_fields(1)

HTTP Request

GET https://example.openasset.com/REST/1/Fields/:id

URL Parameters

Parameter Description
ID The ID of the Field to retrieve

Update a Specific Field

Certain attributes of a Field noun can be updated. Below are the different attributes that can be updated:

HTTP Request

PUT https://example.openasset.com/REST/1/Fields/:id

Attributes that can be updated

Update the description of a field.

Field fieldObject = new Field();

fieldObject.id   = 1;
fieldObject.name = "New name for this Field!";

Field responseField = conn.SendObject<Field>(fieldObject, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '1')
options.add_option('name', 'New name for this Field!')
fields = @@butler.update_fields(options)
Parameter Type Description
alive boolean Whether this field is enabled or disabled.
description string The description of this field's intended purpose.
name string The display name for this field.
display_order integer The order in which this field is displayed in different areas of the product. Such as the Projects page and Fields list page.

Updating Multiple Fields

PUT Request:

[
    {
        "id": 1,
        "name": "New Name 1",
        "description": "We've updated the description"
    },
    {
        "id": 2,
        "display_order": 6,
        "name": "New Name2",
        "description": "We've updated the description here too!"
    }
]

PUT (Truncated) Example Response:

[
    {
        "name": "New Name 1",
        "_http_header_X_Ignored_Fields": "id",
        "id": 1,
        "description": "We've updated the description",
        "http_status_code": 200
    },
    {
        "name": "New Name2",
        "_http_header_X_Ignored_Fields": "id",
        "id": 2,
        "description": "We've updated the description here too!",
        "http_status_code": 200
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/Fields/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new Field

This endpoint allows creation of Fields. Below are the required minimum parameters to include in a POST:

Parameter Type Description Enumerable Values
name string The display name associated with this string.
field_type enum The type of field, for either Files, Projects or Employees 'image'
field_display_type enum The manner in which this field represents data on the front end. 'suggestion'
// Create a new Field
Field FieldItem = new Field();

//Set the name of the Field
Field.Name = "New File Field!";
Field.Field_type = 'image';
Field.Field_display_type = 'singleLine';

// Make a POST request by setting the last parameter as TRUE
conn.SendObject<Field>(Field, true);

HTTP Request

POST https://example.openasset.com/REST/1/Fields/

Delete a Specific Field

This endpoint allows DELETES of fields.

HTTP Request

DELETE https://example.openasset.com/REST/1/Fields/:id

or

DELETE https://example.openasset.com/REST/1/Fields?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the field to delete

Files

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Query Parameters: Files

Example JSON Object:

[
    {
        "access_level": 2,
        "alternate_store_id": 0,
        "caption": "",
        "category_id": 1,
        "click_count": 3,
        "contains_audio": 0,
        "contains_video": 0,
        "copyright_holder_id": 2,
        "created": "20160211000000",
        "description": "Example File",
        "download_count": 0,
        "duration": 0,
        "filename": "A0063.jpg",
        "id": 41,
        "md5_at_upload": "ccdcd858037048deccce266e6f213044",
        "md5_now": "",
        "original_filename": "A0063_N1.jpg",
        "photographer_id": 1,
        "processing_failures": 0,
        "project_id": 5,
        "rank": 5,
        "recheck": 0,
        "replaced": "0",
        "replaced_user_id": 0,
        "rotate_degrees": 0,
        "rotation_since_upload": 0,
        "similarity_indexed": "0",
        "updated": "20160218162818",
        "uploaded": "20150211142618",
        "user_id": 3,
        "video_frames_per_second": 0
    }
]
Attribute Type Description
access_level integer The access level of a file object
alternate_store_id integer The ID of the store where this file is located
caption string The associated caption for this file
category_id integer The ID of the Category this file belongs to
click_count integer The number of times this file has been accessed via the front-end
contains_audio boolean Whether this file contains audio
contains_video boolean Whether this file contains video
copyright_holder_id integer The ID of the Copyright Holder associated with this file
created timestamp The time (in seconds) the file was created. This information is often pulled from the file's metadata on upload.
description string The description for this file
download_count integer the number of times this file has been dowloaded
duration integer If the file is a video, the duration in seconds of the file.
filename string The current name of the file within the OpenAsset System
id integer The unique ID for the file
md5_at_upload string The unique MD5 hash of the file
original_filename string The original filename for this file befoer it was imported into OpenAsset
photographer_id integer The ID of the Photographer associated with this file
processing_failures integer The number of times this file has failed to process
project_id integer The ID of the project this file is associated with. If this is a reference file, this value is 0
rank integer The rank assigned to this file
replaced timestamp The time in seconds when this file was replaced, or 0 if it has never been replaced
replaced_User_id integer The ID of the User that replaced this file, or 0 if it has never been replaced
rotate_degrees integer The degrees by which the file has been rotated, or 0 if the file has never been rotated
rotation_since_upload integer The amount of rotations done since the file has b een uploaded, or 0 if it has never been rotated
similarity_indexed date the time in seconds when the file was indexed by the Image Similarity Service
updated date The Time in seconds when the file was last updated.
user_id integer The ID of the user that uploaded the file
video_frames_per_second integer The Frames per second of this file if it is a video, or 0 if it is not a video

Get All Files

This endpoint retrieves 10 files by default. To get ALL files on the endpoint add 'limit=0' to the request.

Example query:

private static List<File> GetFiles()
        {
            RESTOptions<File> options = new RESTOptions<File>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<File>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
files = @@butler.get_files

HTTP Request

GET https://example.openasset.com/REST/1/Files

To get all files on the instance:

GET https://example.openasset.com/REST/1/Files?limit=0

Get a Specific File

This endpoint retrieves a specific File.

Example query - Get file ID 41:

private static List<File> GetFiles()
        {
            RESTOptions<File> options = new RESTOptions<File>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<File>(41);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
files = @@butler.get_files(options)

HTTP Request

GET https://example.openasset.com/REST/1/Files/:id

URL Parameters

Parameter Description
ID The ID of the File to retrieve

Update a Specific File

Certain attributes of a File noun can be updated. Below are the different attributes that can be updated:

Update the description of a file.

// Create a new file object
File fileItem = new File();

// Set the id to an existing image in OpenAsset
fileItem.Id = 41;

// Updating its description field
fileItem.Description = "Updated Description!!";

// Make a PUT request by setting the last parameter as FALSE
File responseFile = conn.SendObject<File>(fileItem, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
options.add_option('description', 'Updated Description!!')
files = @@butler.update_files(options)

HTTP Request

PUT https://example.openasset.com/REST/1/Files/:id

Attributes that can be updated

Parameter Type Description
access_level integer: 1-3 The access level on the file. Possible values 1-3.
caption string The caption associated with this file. Visible on File info page.
copyright_holder_id int The ID of the Copyright Holder associated with this file
description string The description associated with this file. Visible on the File Info page.
photographer_id integer The ID of the Photographer associated with this file
rank integer The rank of this file. Possible values are dynamic and dependent on custom settings for your instance.
rotate_degrees enum: 0, 90, 180, 270 Triggers a rotation of the file.

Updating Multiple Files

PUT Request:

[
    {
        "id": 55,
        "description": "OpenAsset REST API Dcouments Screenshot!",
        "filename": "A0063_N15.jpg",
        "caption": "Cool Docs!"
    },
    {
        "id": 56,
        "description": "OpenAsset Screenshots!",
        "photographer_id": 2,
        "filename": "A0063_N16.jpg",
        "caption": "More caption updating!"
    }
]

PUT (Truncated) Example Response:

[
    {
        "_http_header_X_Ignored_Fields": "id,filename",
        "id": 55,
        "description": "OpenAsset REST API Dcouments Screenshot!",
        "photographer_id": 1,
        "caption": "Cool Docs!",
        "filename": "A0063_N15.jpg",
        "http_status_code": 200
    },
    {
        "_http_header_X_Ignored_Fields": "id,filename",
        "id": 56,
        "description": "OpenAsset Screenshots!",
        "photographer_id": 2,
        "caption": "More caption updating!",
        "filename": "A0063_N16.jpg",
        "http_status_code": 200
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/Files/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new File:

This endpoint allows for the creation of new Files. The minimum required parameters to include in a POST request for this endpoint are the following:

Form-data required parameters:

Form Data Field Name Field Value
file An array of physical files to be uploaded to the system.
_jsonBody The JSON object to POST with the minimum requirements as below.

JSON body required parameters

Parameter Types Description
category_id integer The Category ID to upload this file to.
original_filename string This MUST match the filename in the file parameter.
project_id int If uploading to a project based category, this is required. If uploading to a reference category, this parameter can be omitted.

HTTP Request

POST https://example.openasset.com/REST/1/Files/

Delete a Specific File

This endpoint allows DELETES of files.

HTTP Request

// Create a new file object
File fileItem = new File();

// Set the id to an existing image in OpenAsset
fileItem.Id = 41;

// Send the File object to the DeleteObject method
conn.DeleteObject(noun);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')

# Any method below would work.
butler.delete_files([41,42,43])
butler.delete_files(['41','42','43'])
butler.delete_files(41)
butler.delete_files('41')

DELETE https://example.openasset.com/REST/1/Files/:id

or

DELETE https://example.openasset.com/REST/1/Files?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the file to delete

Nested Nouns

Groups

GET

POST

PUT

DELETE

Query Parameters: Groups

Example JSON Object:

{
    "alive": 1,
    "default_for_new_users": 0,
    "expires": 0,
    "expiry_date": "20370101010101",
    "hidden": 0,
    "id": 1,
    "name": "Administrator"
}
Parameter Type Description
alive boolean Whether the group is enabled or disabled.
default_for_new_users boolean Whether this group is automatically assigned as the default group for newly created users.
expires boolean Whether this groups will expire on the date and time listed under expiry_date.
expiry_date datetime Date and time when this group will expire and become disabled.
hidden boolean Whether this group is visible users.
id integer The unique ID associated with this Group.
name string The display name associated with this Group.

Get All Groups

This endpoint retrieves 10 groups by default. To get ALL groups on the endpoint add 'limit=0' to the request.

Example query:

private static List<Group> GetGroups()
        {
            RESTOptions<Group> options = new RESTOptions<Group>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Group>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
groups = @@butler.groups

HTTP Request

GET https://example.openasset.com/REST/1/Groups

To get all groups on the instance:

GET https://example.openasset.com/REST/1/Groups?limit=0

Get a Specific Group

This endpoint retrieves a specific Group.

Example query - Get group ID 41:

private static List<Group> GetGroups()
        {
            RESTOptions<Group> options = new RESTOptions<Group>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Group>(1);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
groups = @@butler.get_groups(1)

HTTP Request

GET https://example.openasset.com/REST/1/Groups/:id

URL Parameters

Parameter Description
ID The ID of the Group to retrieve

Update a Specific Group

Certain attributes of a Group noun can be updated. Below are the different attributes that can be updated:

Update the description of a group.

Group groupObject = new Group();

groupObject.id   = 1;
groupObject.name = "New name for this Group!";

Group responseGroup = conn.SendObject<Group>(groupObject, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '1')
options.add_option('name', 'New name for this Group!')
groups = @@butler.update_groups(options)

HTTP Request

PUT https://example.openasset.com/REST/1/Groups/:id

Attributes that can be updated

Parameter Type Description
alive boolean Whether the group is enabled or disabled.
default_for_new_users boolean Whether this group is automatically assigned as the default group for newly created users.
expires boolean Whether this groups will expire on the date and time listed under expiry_date.
expiry_date datetime Date and time when this group will expire and become disabled.
name string The display name associated with this Group.

Updating Multiple Groups

PUT Request:

[
    {
        "id": 40,
        "alive": 0
    },
    {
        "id": 420,
        "name": "Limited Permissions Group"
    }
]

PUT (Truncated) Example Response:

[
    {
        "id": 40,
        "_http_header_X_Ignored_Fields": "id",
        "alive": 0,
        "http_status_code": 200
    },
    {
        "id": 420,
        "_http_header_X_Ignored_Fields": "id",
        "name": "Limited Permissions Group",
        "http_status_code": 200
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/Groups/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new Group

This endpoint allows for the creation of new Groups. The minimum required parameters to include in a Group POST request are the following:

Parameter Type Description
name string The string associated with the display name of the group.

HTTP Request

POST https://example.openasset.com/REST/1/Groups/

Delete a Specific Group

This endpoint allows DELETES of groups.

HTTP Request

// Create a new group object
Group groupItem = new Group();

// Set the id to an existing image in OpenAsset
groupItem.Id = 41;

// Send the Group object to the DeleteObject method
conn.DeleteObject(noun);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')

# Any method below would work.
butler.delete_groups([41,42,43])
butler.delete_groups(['41','42','43'])
butler.delete_groups(41)
butler.delete_groups('41')

DELETE https://example.openasset.com/REST/1/Groups/:id

or

DELETE https://example.openasset.com/REST/1/Groups?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the group to delete

Keywords

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Query Parameters: Keywords

Example JSON Object:

{
    "name": "Exterior",
    "keyword_category_id": 1,
    "id": 8,
    "updated": "0"
}
Parameter Type Description
name string Display name associated with this keyword.
keyword_category_id integer The unique ID of the keyword category that this keyword belongs to.
id integer The unique ID associated with this keyword.
updated datetime The last time this keyword was modified.

Get All Keywords

This endpoint retrieves 10 keywords by default. To get ALL keywords on the endpoint add 'limit=0' to the request.

Example query:

private static List<Keyword> GetKeywords()
        {
            RESTOptions<Keyword> options = new RESTOptions<Keyword>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Keyword>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
keywords = @@butler.keywords

HTTP Request

GET https://example.openasset.com/REST/1/Keywords

To get all keywords on the instance:

GET https://example.openasset.com/REST/1/Keywords?limit=0

Get a Specific Keyword

This endpoint retrieves a specific Keyword.

Example query - Get keyword ID 41:

private static List<Keyword> GetKeywords()
        {
            RESTOptions<Keyword> options = new RESTOptions<Keyword>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Keyword>(1);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
keywords = @@butler.get_keywords(1)

HTTP Request

GET https://example.openasset.com/REST/1/Keywords/:id

URL Parameters

Parameter Description
ID The ID of the Keyword to retrieve

Update a Specific Keyword

Certain attributes of a Keyword noun can be updated. Below are the different attributes that can be updated:

Update the description of a keyword.

Keyword keywordObject = new Keyword();

keywordObject.id   = 1;
keywordObject.name = "New name for this Keyword!";

Keyword responseKeyword = conn.SendObject<Keyword>(keywordObject, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '1')
options.add_option('name', 'New name for this Keyword!')
keywords = @@butler.update_keywords(options)

HTTP Request

PUT https://example.openasset.com/REST/1/Keywords/:id

Attributes that can be updated

Parameter Type Description
name string Display name associated with this keyword.

Updating Multiple Keywords

PUT Request:

[
    {
        "id": 40,
        "name": "New Keyword Name 1"
    },
    {
        "id": 42,
        "name": "New Keyword Name 2"
    }
]

PUT (Truncated) Example Response:

[
    {
        "id": 40,
        "_http_header_X_Ignored_Fields": "id",
        "name": "New Keyword Name 1",
        "http_status_code": 200
    },
    {
        "id": 42,
        "_http_header_X_Ignored_Fields": "id",
        "name": "New Keyword Name 2",
        "http_status_code": 200
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/Keywords/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new Keyword

This endpoint allows creation of Keywords. Below are the required minimum parameters to create a new Keyword:

// Create a new keyword object
Keyword keywordItem = new Keyword();

//Set the name of the copyright
keywordItem.Name = "New keyword!";
keywordItem.Keyword_Category_id = 1;

// Make a POST request by setting the last parameter as TRUE
conn.SendObject<Keyword>(keyword, true);
Parameter Type Description
name string The display name associated with this string.
keyword_category_id id The Keyword Category ID that this keyword belongs to.

HTTP Request

POST https://example.openasset.com/REST/1/Keywords/

Create Multiple New Keywords

It is possible to create multiple items simultaneously by sending a POST request with multiple valid Objects within the body of the request.

Example JSON Object

[
    {
        "keyword_category_id": 2,
        "name": "Keyword1"
    },
    {
        "keyword_category_id": 5,
        "name": "Keyword2"
    }
]

Example Response

[
   {
      "_http_header_Location": "http://localhost:8787/REST/1/Keywords/56",
      "dead_image_count": 0,
      "http_status_code": 201,
      "id": 56,
      "keyword_category_id": 2,
      "name": "Keyword1",
      "private_image_count": 0,
      "public_image_count": 0,
      "unapproved_image_count": 0,
      "updated": "20200603104244"
   },
   {
      "_http_header_Location": "http://localhost:8787/REST/1/Keywords/57",
      "dead_image_count": 0,
      "http_status_code": 201,
      "id": 57,
      "keyword_category_id": 5,
      "name": "Keyword2",
      "private_image_count": 0,
      "public_image_count": 0,
      "unapproved_image_count": 0,
      "updated": "20200603104244"
   }
]

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_Location string The REST Address where the newly created object can be found.
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Delete a Specific Keyword

This endpoint allows DELETES of keywords.

HTTP Request

// Create a new keyword object
Keyword keywordItem = new Keyword();

// Set the id to an existing image in OpenAsset
keywordItem.Id = 41;

// Send the Keyword object to the DeleteObject method
conn.DeleteObject(noun);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')

# Any method below would work.
butler.delete_keywords([41,42,43])
butler.delete_keywords(['41','42','43'])
butler.delete_keywords(41)
butler.delete_keywords('41')

DELETE https://example.openasset.com/REST/1/Keywords/:id

or

DELETE https://example.openasset.com/REST/1/Keywords?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the keyword to delete

Merge Keywords

MERGE Request:

[
    {
        "id": 40
    },
    {
        "id": 42
    }
]

or

[
    40,
    42
]

This endpoint allows the merging of one or more Keywords into a single Keyword. This targets a single Keyword with the body being an array of ids or objects containing the id of what you want merged.

All Keywords must below to the same KeywordCategory to be merged.

The response is the individual object GET after the merge request is completed.

HTTP Request

MERGE https://example.openasset.com/REST/1/Keywords/:id

KeywordCategories

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Query Parameters: KeywordCategories

Example JSON Object:

{
    "category_id": 1,
    "code": "TypeofAsset",
    "display_order": 3,
    "id": 4,
    "name": "Type of Asset",
    "updated": "20160215125042"
}
Parameter Type Description
category_id integer Unique ID of the Parent Category this keyword category belongs to.
code string Unique Code identifying this Keyword Category.
display_order integer The order this Keyword Category appears on front-end displays. Lower value indicates higher priority
id integer Unique ID of this Keyword Category.
name string The display name associated with this Keyword Category.
updated datetime The date time this Keyword Category was last modified.

Get All KeywordCategories

This endpoint retrieves 10 keyword categories by default. To get ALL keyword categories on the endpoint add 'limit=0' to the request.

Example query:

private static List<File> GetKeywordCategories()
        {
            RESTOptions<File> options = new RESTOptions<File>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<File>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
keywordCategories = @@butler.get_keywordCategories

HTTP Request

GET https://example.openasset.com/REST/1/KeywordCategories

To get all keyword categories on the instance:

GET https://example.openasset.com/REST/1/KeywordCategories?limit=0

Get a Specific KeywordCategories

This endpoint retrieves a specific KeywordCategory.

Example query - Get keywordcategories ID 41:

private static List<File> GetKeywordCategories()
        {
            RESTOptions<File> options = new RESTOptions<File>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<File>(41);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
keywordCategories = @@butler.get_keywordCategories(options)

HTTP Request

GET https://example.openasset.com/REST/1/KeywordCategories/:id

URL Parameters

Parameter Description
ID The ID of the KeywordCategories to retrieve

Update a Specific KeywordCategory

Certain attributes of KeywordCategories noun can be updated. Below are the different attributes that can be updated:

Update the description of a keywordcategories.

// Create a new keywordCategory object
File keywordCategoryItem = new File();

// Set the id to an existing image in OpenAsset
keywordCategoryItem.Id = 41;

// Updating its description field
keywordCategoryItem.Description = "Updated Description!!";

// Make a PUT request by setting the last parameter as FALSE
File responseFile = conn.SendObject<File>(keywordCategoryItem, false);

HTTP Request

PUT https://example.openasset.com/REST/1/KeywordCategories/:id

Attributes that can be updated

Parameter Type Description
name string The display name associated with this Keyword Category.
display_order integer The order this Keyword Category appears on front-end displays. Lower value indicates higher priority.

Updating Multiple KeywordCategories

PUT Request:

[
    {
        "id": 40,
        "display_order": 1
    },
    {
        "id": 42,
        "name": "New KeywordCategory name"
    }
]

PUT (Truncated) Example Response:

[
    {
        "id": 40,
        "_http_header_X_Ignored_Fields": "id",
        "display_order": 1,
        "http_status_code": 200
    },
    {
        "id": 42,
        "_http_header_X_Ignored_Fields": "id",
        "name": "New KeywordCategory name",
        "http_status_code": 200
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/KeywordCategories/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new Keyword Category

This endpoint allows creation of Keyword Categories. Below are the required minimum parameters to include in your POST request:

Parameter Type Description
name string The display name associated with this string.
category_id id The Category ID that this keyword category belongs to
// Create a new KeywordCategory object
KeywordCategory KeywordCategoryItem = new KeywordCategory();

//Set the name of the KeywordCategory
KeywordCategoryyItem.Name = "My KeywordCategory Name";
KeywordCategoryItem.Category_id = 1;

// Make a POST request by setting the last parameter as TRUE
conn.SendObject<KeywordCategory>(KeywordCategoryyItem, true);

HTTP Request

POST https://example.openasset.com/REST/1/KeywordCategories/

Delete a Specific KeywordCategory

This endpoint allows deletion of keyword categories.

HTTP Request

// Create a new keywordCategory object
File keywordCategoryItem = new File();

// Set the id to an existing image in OpenAsset
keywordCategoryItem.Id = 41;

// Send the File object to the DeleteObject method
conn.DeleteObject(noun);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')

# Any method below would work.
butler.delete_keywordCategories([41,42,43])
butler.delete_keywordCategories(['41','42','43'])
butler.delete_keywordCategories(41)
butler.delete_keywordCategories('41')

DELETE https://example.openasset.com/REST/1/KeywordCategories/:id

or

DELETE https://example.openasset.com/REST/1/KeywordCategories?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the keywordcategories to delete

Merge KeywordCategories

MERGE Request:

[
    {
        "id": 40
    },
    {
        "id": 42
    }
]

or

[
    40,
    42
]

This endpoint allows the merging of one or more Keyword Categories into a single Keyword Category. This targets a single Keyword Category with the body being an array of IDs or objects containing the ID of what you want merged.

All Keyword Categories must belong to the same Category to be merged.

The response is the individual object GET after the merge request has completed.

HTTP Request

MERGE https://example.openasset.com/REST/1/KeywordCategories/:id

Photographers

Available HTTP Verbs include:

GET

POST

PUT

Query Parameters: Photographers

Example JSON Object:

{
    "id": 1,
    "name": "Tim, OpenAsset",
    "updated": "20190620151620"
}
Parameter Type Description
name string The display name associated with this Photographer
id integer The unique ID associated with this Photographer
updated datetime The last time this Photographer was modified.

Get All Photographers

This endpoint retrieves 10 photographers by default. To get ALL photographers on the endpoint add 'limit=0' to the request.

Example query:

private static List<Photographer> GetPhotographers()
        {
            RESTOptions<Photographer> options = new RESTOptions<Photographer>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Photographer>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
photographers = @@butler.photographers

HTTP Request

GET https://example.openasset.com/REST/1/Photographers

To get all photographers on the instance:

GET https://example.openasset.com/REST/1/Photographers?limit=0

Get a Specific Photographer

This endpoint retrieves a specific Photographer.

Example query - Get photographer ID 41:

private static List<Photographer> GetPhotographers()
        {
            RESTOptions<Photographer> options = new RESTOptions<Photographer>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Photographer>(1);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
photographers = @@butler.get_photographers(1)

HTTP Request

GET https://example.openasset.com/REST/1/Photographers/:id

URL Parameters

Parameter Description
ID The ID of the Photographer to retrieve

Update a Specific Photographer

Certain attributes of a Photographer noun can be updated. Below are the different attributes that can be updated:

Update the description of a photographer.

Photographer photographerObject = new Photographer();

photographerObject.id   = 1;
photographerObject.name = "New name for this Photographer!";

Photographer responsePhotographer = conn.SendObject<Photographer>(photographerObject, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '1')
options.add_option('name', 'New name for this Photographer!')
photographers = @@butler.update_photographers(options)

HTTP Request

PUT https://example.openasset.com/REST/1/Photographers/:id

Attributes that can be updated

Parameter Type Description
name string The display name associated with this Photographer

Updating Multiple Photographers

PUT Request:

[
    {
        "id": 40,
        "name": "Bill Microsoft"
    },
    {
        "id": 42,
        "name": "Tim Apple"
    }
]

PUT (Truncated) Example Response:

[
    {
        "id": 40,
        "_http_header_X_Ignored_Fields": "id",
        "name": "Bill Microsoft",
        "http_status_code": 200
    },
    {
        "id": 42,
        "_http_header_X_Ignored_Fields": "id",
        "name": "Tim Apple",
        "http_status_code": 200
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/Photographers/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new Photographer

This endpoint allows for the creation of new Photographers. The minimum required arguments to send in a POST are:

// Create a new photographer object
Photographer photographerItem = new Photographer();

//Set the name of the copyright
photographerItem.Name = "New photographer!";

// Make a POST request by setting the last parameter as TRUE
conn.SendObject<Photographer>(photographer, true);

Required POST attributes

Parameter Type Description
name string The display name associated with this Photographer

HTTP Request

POST https://example.openasset.com/REST/1/Photographers/

Delete a Specific Photographer

This endpoint allows DELETES of photographers.

HTTP Request

// Create a new photographer object
Photographer photographerItem = new Photographer();

// Set the id to an existing image in OpenAsset
photographerItem.Id = 41;

// Send the Photographer object to the DeleteObject method
conn.DeleteObject(noun);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')

# Any method below would work.
butler.delete_photographers([41,42,43])
butler.delete_photographers(['41','42','43'])
butler.delete_photographers(41)
butler.delete_photographers('41')

DELETE https://example.openasset.com/REST/1/Photographers/:id

or

DELETE https://example.openasset.com/REST/1/Photographers?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the photographer to delete

Merge Photographers

MERGE Request:

[
    {
        "id": 40
    },
    {
        "id": 42
    }
]

or

[
    40,
    42
]

This endpoint allows the merging of one or more Photographers into a single Photographer. This targets a single Photographer with the body being an array of ids or objects containing the id of what you want merged.

The response is the individual object GET after the merge request is completed.

HTTP Request

MERGE https://example.openasset.com/REST/1/Photographers/:id

Projects

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Query Parameters: Projects

Example JSON Object:

{
    "alive": 1,
    "code": "101.5232AB",
    "code_alias_1": "101.5",
    "code_alias_2": "101AB",
    "dead_image_count": 0,
    "id": 1,
    "name": "Foo Bar",
    "name_alias_1": "Foo",
    "name_alias_2": "Bar",
    "private_image_count": 0,
    "public_image_count": 1,
    "unapproved_image_count": 0,
    "updated": "20190422113908"
}
Parameter Type Description
alive bool Whether the project is enabled (1), or disabled (0).
code string A unique code identifier for the project.
code_alias_1 string A secondary code for the project. (Used as a substitute for complicated Project codes.)
code_alias_2 string A tertiary code for the project. (Used as a substitute for complicated Project codes.)
created datetime The time at which this project was created.
dead_image_count integer Number of deleted images within the project.
id integer The ID associated with this project.
name string The name of this project.
name_alias_1 string A secondary name for this project.
name_alias_2 string A tertiary name for this project.
private_image_count integer The number of images in this project of a level 2 Access Level.
public_image_count integer The number of images in this project of a level 1 Access Level.
unapproved_image_count integer The number of images in this project awaiting approval from an administrator.
updated datetime The last time this project was modified.

Get All Projects

This endpoint retrieves 10 projects by default. To get ALL projects on the endpoint add 'limit=0' to the request.

Example query:

private static List<Project> GetProjects()
        {
            RESTOptions<Project> options = new RESTOptions<Project>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Project>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
projects = @@butler.projects

HTTP Request

GET https://example.openasset.com/REST/1/Projects

To get all projects on the instance:

GET https://example.openasset.com/REST/1/Projects?limit=0

Get a Specific Project

This endpoint retrieves a specific Project.

Example query - Get project ID 1:

private static List<Project> GetProjects()
        {
            RESTOptions<Project> options = new RESTOptions<Project>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Project>(1);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
projects = @@butler.get_projects(1)

HTTP Request

GET https://example.openasset.com/REST/1/Projects/:id

URL Parameters

Parameter Description
ID The ID of the Project to retrieve

Update a Specific Project

Certain attributes of a Project noun can be updated. Below are the different attributes that can be updated:

Update the name of a project.

Project projectObject = new Project();

projectObject.id   = 1;
projectObject.name = "New name for this Project!";

Project responseProject = conn.SendObject<Project>(projectObject, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '1')
options.add_option('name', 'New name for this Project!')
projects = @@butler.update_projects(options)

HTTP Request

PUT https://example.openasset.com/REST/1/Projects/:id

Attributes that can be updated

Parameter Type Description
name string The string associated with the name of the project.
code string The string associated with the Unique code of the project.
alive boolean Whether the project is enabled or disabled.
code_alias_1 string A string associated with an alias for the project code.
code_alias_2 string A secondary string associated with an alias for the project code.
name_alias_1 string A string associated with an alias for the project name.
name_alias_2 string A secondary string associated with an alias for the project name.
updated datetime The last time this project was modified.

Updating Multiple Projects

PUT Request:

[
    {
        "name": "London Bridges Olympic Lighting",
        "id": 2,
        "code_alias_1": "ABC123-London",
        "code": "ABC123"
    },
    {
        "name": "The Economist",
        "id": 3,
        "code_alias_1": "NewCode123-Economist",
        "code": "NewCode123"
    }
]

PUT (Truncated) Example Response:

[
    {
        "name": "London Bridges Olympic Lighting",
        "_http_header_X_Ignored_Fields": "id",
        "id": 2,
        "http_status_code": 200,
        "code_alias_1": "ABC123-London",
        "code": "ABC123"
    },
    {
        "name": "The Economist",
        "_http_header_X_Ignored_Fields": "id",
        "id": 3,
        "http_status_code": 200,
        "code_alias_1": "NewCode123-Economist",
        "code": "NewCode123"
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/Projects/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new Project

This endpoint allows for the creation of new Projects. The minimum required arguments to send in a POST are:

Parameter Type Description
name string The name of the project
code string The unique code of the project

HTTP Request

POST https://example.openasset.com/REST/1/Projects/

Creating Multiple Projects

It is possible to create multiple items simultaneously by sending a POST request with multiple valid Objects within the body of the request.

Example Request

[
    {
        "code": "NewProjectCode1237",
        "name": "New Project Creation 1"
    },
    {
        "code": "NewProjectCode4567",
        "name": "New Project Creation 2"
    }
]

Example Response

[
    {
        "id": 321,
        "name_alias_2": "",
        "dead_image_count": 0,
        "code_alias_1": "",
        "code": "NewProjectCode123",
        "name": "New Project Creation 1",
        "_http_header_Location": "https://demo-fpa.openasset.com/REST/1/Projects/321",
        "code_alias_2": "",
        "public_image_count": 0,
        "private_image_count": 0,
        "created": "20190620141230",
        "updated": "20190723182230",
        "alive": 1,
        "http_status_code": 201,
        "unapproved_image_count": 0,
        "name_alias_1": ""
    },
    {
        "id": 322,
        "name_alias_2": "",
        "dead_image_count": 0,
        "code_alias_1": "",
        "code": "NewProjectCode456",
        "name": "New Project Creation 2",
        "_http_header_Location": "https://demo-fpa.openasset.com/REST/1/Projects/322",
        "code_alias_2": "",
        "public_image_count": 0,
        "private_image_count": 0,
        "created": "20190620141230",
        "updated": "20190723182230",
        "alive": 1,
        "http_status_code": 201,
        "unapproved_image_count": 0,
        "name_alias_1": ""
    }
]

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_Location string The REST Address where the newly created object can be found.
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Delete a Specific Project

This endpoint allows DELETES of projects.

HTTP Request

DELETE https://example.openasset.com/REST/1/Projects/:id

or

DELETE https://example.openasset.com/REST/1/Projects?id=1,2,3,4

URL Parameters

Parameter Description
ID The ID of the project to delete

Nested Nouns

Project Keywords

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Query Parameters: Project Keywords

Example JSON Object:

{
    "id": 47,
    "name": "New York",
    "project_count": 2,
    "project_keyword_category_id": 2,
    "updated": "0"
}
Parameter Type Description
id integer Unique ID associated with this ProjectKeyword
name string Display name of this ProjectKeyword
project_count integer The number of projects this keyword has been assigned to.
project_keyword_category_id integer The ProjectKeywordCategory this ProjectKeyword belongs to.
updated datetime The last time this ProjectKeyword was updated.

Get All Project Keywords

This endpoint retrieves 10 Project Keywords by default. To get ALL Project Keywords on the endpoint add 'limit=0' to the request.

Example query:

private static List<ProjectKeyword> GetProjectKeywords()
        {
            RESTOptions<ProjectKeyword> options = new RESTOptions<ProjectKeyword>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<ProjectKeyword>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
projectKeywords = @@butler.get_projectKeywords

HTTP Request

GET https://example.openasset.com/REST/1/ProjectKeywords

To get all projectkeywords on the instance:

GET https://example.openasset.com/REST/1/ProjectKeywords?limit=0

Get a Specific Project Keyword

This endpoint retrieves a specific Project Keyword.

Example query - Get projectkeyword ID 41:

private static List<ProjectKeyword> GetProjectKeywords()
        {
            RESTOptions<ProjectKeyword> options = new RESTOptions<ProjectKeyword>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<ProjectKeyword>(41);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
projectKeywords = @@butler.get_projectKeywords(options)

HTTP Request

GET https://example.openasset.com/REST/1/ProjectKeywords/:id

URL Parameters

Parameter Description
ID The ID of the Project Keyword to retrieve

Update a Specific Project Keyword

Certain attributes of a Project Keyword noun can be updated. Below are the different attributes that can be updated:

Update the name of a projectkeyword.

// Create a new projectKeyword object
ProjectKeyword projectKeywordItem = new ProjectKeyword();

// Set the id to an existing ProjectKeyword in OpenAsset
projectKeywordItem.Id = 41;

// Updating its name field
projectKeywordItem.Name = "Updated Name!!";

// Make a PUT request by setting the last parameter as FALSE
ProjectKeyword responseProjectKeyword = conn.SendObject<ProjectKeyword>(projectKeywordItem, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
options.add_option('name', 'Updated Name!!')
projectKeywords = @@butler.update_projectKeywords(options)

HTTP Request

PUT https://example.openasset.com/REST/1/ProjectKeywords/:id

Attributes that can be updated

Parameter Type Description
name string Display name of this ProjectKeyword

Updating Multiple ProjectKeywords

PUT Request:

[
    {
        "id": 40,
        "name": "New ProjectKeyword Name1"
    },
    {
        "id": 420,
        "name": "New ProjectKeyword Name2"
    }
]

PUT (Truncated) Example Response:

[
    {
        "id": 40,
        "_http_header_X_Ignored_Fields": "id",
        "name": "New ProjectKeyword Name1",
        "http_status_code": 200
    },
    {
        "id": 420,
        "_http_header_X_Ignored_Fields": "id",
        "name": "New ProjectKeyword Name2",
        "http_status_code": 200
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/ProjectKeywords/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new Project Keyword

This endpoint allows for the creation of new Project Keywords. The minimum required parameters to POST on this noun are:

Parameter Type Description
name string The string associated with this Project Keyword
project_keyword_category_id integer The ID of the project keyword category this keyword will be created under.

HTTP Request

POST https://example.openasset.com/REST/1/ProjectKeywords/

Create Multiple New Project Keywords

It is possible to create multiple items simultaneously by sending a POST request with multiple valid Objects within the body of the request.

Example JSON Object

[{
    "name": "Keyword1",
    "project_keyword_category_id": 1
},
{
    "name": "Keyword2",
    "project_keyword_category_id": 1
}]

Example Response

[
   {
      "_http_header_Location": "http://localhost/REST/1/ProjectKeywords/116",
      "http_status_code": 201,
      "id": 116,
      "name": "Keyword1",
      "project_count": 0,
      "project_keyword_category_id": 1,
      "updated": "20200603104527"
   },
   {
      "_http_header_Location": "http://localhost/REST/1/ProjectKeywords/117",
      "http_status_code": 201,
      "id": 117,
      "name": "Keyword2",
      "project_count": 0,
      "project_keyword_category_id": 1,
      "updated": "20200603104527"
   }
]

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_Location string The REST Address where the newly created object can be found.
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Delete a Specific Project Keyword

This endpoint allows DELETES of projectkeywords.

HTTP Request

// Create a new projectKeyword object
ProjectKeyword projectKeywordItem = new ProjectKeyword();

// Set the ID to an existing ProjectKeyword in OpenAsset.
projectKeywordItem.Id = 41;

// Send the ProjectKeyword object to the DeleteObject method
conn.DeleteObject(noun);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')

# Any method below would work.
butler.delete_projectKeywords([41,42,43])
butler.delete_projectKeywords(['41','42','43'])
butler.delete_projectKeywords(41)
butler.delete_projectKeywords('41')

DELETE https://example.openasset.com/REST/1/ProjectKeywords/:id

or

DELETE https://example.openasset.com/REST/1/ProjectKeywords?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the projectkeyword to delete

Merge ProjectKeywords

MERGE Request:

[
    {
        "id": 40
    },
    {
        "id": 42
    }
]

or

[
    40,
    42
]

This endpoint allows the merging of one or more ProjectKeywords into a single ProjectKeyword. This targets a single ProjectKeyword with the body being an array of ids or objects containing the id of what you want merged.

All ProjectKeywords must below to the same ProjectKeywordCategory to be merged.

The response is the individual object GET after the merge request is completed.

HTTP Request

MERGE https://example.openasset.com/REST/1/ProjectKeywords/:id

ProjectKeywordCategories

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Query Parameters: ProjectKeywordCategories

Example JSON Object:

{
    "code": "City",
    "display_order": 1,
    "id": 2,
    "name": "City",
    "updated": "20190501195601"
}
Parameter Type Description
code string Unique string associated with this ProjectKeywordCategory
display_order integer The order in which this ProjectKeywordCategory appears on the ProjectKeywords page. A lower number carries higher priority.
id integer Unique ID associated with this ProjectKeywordCategory
name string The display name for this ProjectKeywordCategory
updated datetime The last time this ProjectKeywordCategory was updated.

Get All ProjectKeywordCategories

This endpoint retrieves 10 ProjectKeywordCategories by default. To get ALL ProjectKeywordCategories on the endpoint add 'limit=0' to the request.

Example query:

private static List<ProjectKeywordCategory> GetProjectKeywordCategories()
        {
            RESTOptions<ProjectKeywordCategory> options = new RESTOptions<ProjectKeywordCategory>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<ProjectKeywordCategory>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
projectKeywordCategories = @@butler.get_projectKeywordCategories

HTTP Request

GET https://example.openasset.com/REST/1/ProjectKeywordCategories

To get all ProjectKeywordCategories on the instance:

GET https://example.openasset.com/REST/1/ProjectKeywordCategories?limit=0

Get a Specific ProjectKeywordCategories

This endpoint retrieves a specific ProjectKeywordCategories.

Example query - Get projectKeywordcategories ID 41:

private static List<ProjectKeywordCategory> GetProjectKeywordCategories()
        {
            RESTOptions<ProjectKeywordCategory> options = new RESTOptions<ProjectKeywordCategory>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<ProjectKeywordCategory>(41);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
projectKeywordCategories = @@butler.get_projectKeywordCategories(options)

HTTP Request

GET https://example.openasset.com/REST/1/ProjectKeywordCategories/:id

URL Parameters

Parameter Description
ID The ID of the ProjectKeywordCategories to retrieve

Update a Specific ProjectKeywordCategories

Certain attributes of a ProjectKeywordCategories noun can be updated. Below are the different attributes that can be updated:

Update the name of a Project Keyword Category.

// Create a new projectKeywordCategory object
ProjectKeywordCategory projectKeywordCategoryItem = new ProjectKeywordCategory();

// Set the id to an existing image in OpenAsset
projectKeywordCategoryItem.Id = 41;

// Updating its name field
projectKeywordCategoryItem.name = "Updated name!!";

// Make a PUT request by setting the last parameter as FALSE
ProjectKeywordCategory responseProjectKeywordCategory =
    conn.SendObject<ProjectKeywordCategory>(projectKeywordCategoryItem, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
options.add_option('name', 'Updated name!!')
projectKeywordCategories = @@butler.update_projectKeywordCategories(options)

HTTP Request

PUT https://example.openasset.com/REST/1/ProjectKeywordCategories/:id

Attributes that can be updated

Parameter Type Description
display_order integer The order in which this ProjectKeywordCategory appears on the ProjectKeywords page. A lower number carries higher priority.
name string The display name for this ProjectKeywordCategory

Updating Multiple ProjectKeywordCategories

PUT Request:

[
    {
        "id": 40,
        "display_order": 1
    },
    {
        "id": 42,
        "name": "New Project Keyword Category"
    }
]

PUT (Truncated) Example Response:

[
    {
        "id": 40,
        "_http_header_X_Ignored_Fields": "id",
        "display_order": 1,
        "http_status_code": 200
    },
    {
        "id": 42,
        "_http_header_X_Ignored_Fields": "id",
        "name": "New Project Keyword Category",
        "http_status_code": 200
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/ProjectKeywordCategories/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new ProjectKeywordCategory

This endpoint allows the creation of new Project Keyword Categories. The minimum required arguments to include in a POST request are the following:

Parameter Type Description
name string The string associated with the display name of this Project Keyword Category.

HTTP Request

POST https://example.openasset.com/REST/1/ProjectKeywordCategories/

Delete a Specific ProjectKeywordCategories

This endpoint allows DELETES of ProjectKeywordCategories.

HTTP Request

// Create a new projectKeywordCategory object
ProjectKeywordCategory projectKeywordCategoryItem = new ProjectKeywordCategory();

// Set the id to an existing image in OpenAsset
projectKeywordCategoryItem.Id = 41;

// Send the ProjectKeywordCategory object to the DeleteObject method
conn.DeleteObject(noun);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')

# Any method below would work.
butler.delete_projectKeywordCategories([41,42,43])
butler.delete_projectKeywordCategories(['41','42','43'])
butler.delete_projectKeywordCategories(41)
butler.delete_projectKeywordCategories('41')

DELETE https://example.openasset.com/REST/1/ProjectKeywordCategories/:id

or

DELETE https://example.openasset.com/REST/1/ProjectKeywordCategories?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the projectKeywordcategories to delete

Merge ProjectKeywordCategories

MERGE Request:

[
    {
        "id": 40
    },
    {
        "id": 42
    }
]

or

[
    40,
    42
]

This endpoint allows the merging of one or more ProjectKeywordCategories into a single ProjectKeywordCategory. This targets a single ProjectKeywordCategory with the body being an array of ids or objects containing the id of what you want merged.

The response is the individual object GET after the merge request is completed.

HTTP Request

MERGE https://example.openasset.com/REST/1/ProjectKeywordCategories/:id

Searches

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Query Parameters: Searches

Example JSON Object:

{
    "all_users_can_modify": 0,
    "approved_company_saved_search": 0,
    "can_modify": 1,
    "code": "4de3bb39692b98846817041bb29b52f3",
    "company_saved_search": 0,
    "created": "20190626135704",
    "id": 1534,
    "locked": 0,
    "name": "SavedSearch",
    "saved": 1,
    "search_items": [
        {
            "code": "popularFields",
            "exclude": 0,
            "values": ["test"]
        }
    ],
    "share_with_all_users": 0,
    "updated": "20190626135704",
    "user_id": 22
}
Parameter Type Description
all_users_can_modify boolean Whether all users can make modifications to this Saved Search
approved_company_saved_search boolean Whether this is a company approved saved Search.
can_modify boolean Whether your account has the ability to modify this saved search.
code string A unique hash associated with this saved search. Primarily used in RSS Feeds.
company_saved_search boolean Whether this is a company saved search or not.
created datetime The date time this saved search was created.
id integer The unique ID for this Search.
locked boolean Whether it is possible to edit the search terms of this search.
name string The display name associated with this Search.
saved boolean Whether this is a saved search (1) or a regular temporary search (0).
search_items array[SearchItem] The parameters associated with this SavedSearch. Read the section below for an explanation of this type of object.
share_with_all_users boolean Whether this object is shared with all users.
updated datetime The date time this Search was last updated.
user_id integer The unique ID of the user that created this Search.

Search Item Object

{
    "code": "<enum>",
    "exclude": "<bool>",
    "operator": "<operator>",
    "values/ids": ["<string/int>"]
}

This is a nested object that belongs to this noun. Below is a description:

Parameter Type Description
code enum Affects what field the search is executed under. See the "Available Enums" section for relevant codes.
exclude boolean If true (1), excludes any results that do not satisfy all search conditions.
operator AND/OR Affects whether the search will be evaluated to satisfy all conditionals, or individual conditionals.
values array[strings] The values to search for.

Available Enums

The codes below can be used in the SearchItem Object's code property to define what field to search under.

Code Description Accepted Values Values and/or Ids
album Array of Albums by ID int ids
project Array of Projects by ID int ids
created Array of dates (refinable with a prefix):'<' before '=' equal to '>' after string values
uploaded See above values
caption Search only image captions string values
description Search only image description string values
filename Search only image filename string values
originalFilename Search only image original filename string values
photographer Search by photographer string/int values/ids
copyrightHolder Search by copyright holder int ids
user Search by user int ids
colourspace Search by coulourspace int ids
category Search by category int ids
accessLevel Search by access level int ids
aspectRatio Search by aspect ratio int ids
rank Search by rank (refinable with a prefix):'<' less than '=' equal to '>' more than string values
size See above string values
width See above string values
keywordCount See above string values
popularFields Searches:filename original filename caption description keywords project keywords string values
deleted Search by deleted images bool n/a
keyword. A list of Keywords, in the following format [ { "code": "keyword.1", "ids": [ "2", "3", "4" ] } ] int ids
projectKeyword. See above int ids
field. See above values ids
fileFormat int ids
deleted Search by deleted images int ids

Get All Searches

This endpoint retrieves 10 searches by default. To get ALL searches on the endpoint add 'limit=0' to the request.

Example query:

private static List<Search> GetSearches()
        {
            RESTOptions<Search> options = new RESTOptions<Search>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Search>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
searches = @@butler.get_searches

HTTP Request

GET https://example.openasset.com/REST/1/Searches

To get all searches on the instance:

GET https://example.openasset.com/REST/1/Searches?limit=0

This endpoint retrieves a specific Search.

Example query - Get Search ID 41:

private static List<Search> GetSearches()
        {
            RESTOptions<Search> options = new RESTOptions<Search>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Search>(41);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
searches = @@butler.get_searches(options)

HTTP Request

GET https://example.openasset.com/REST/1/Searches/:id

URL Parameters

Parameter Description
ID The ID of the Search to retrieve

Certain attributes of a Search noun can be updated. Below are the different attributes that can be updated:

Update the name of a Search.

// Create a new search object
Search searchItem = new Search();

// Set the id to an existing image in OpenAsset
searchItem.Id = 41;

// Updating its name field
searchItem.Name = "Updated Name!!";

// Make a PUT request by setting the last parameter as FALSE
Search responseSearch = conn.SendObject<Search>(searchItem, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
options.add_option('name', 'Updated Name!!')
searches = @@butler.update_searches(options)

HTTP Request

PUT https://example.openasset.com/REST/1/Searches/:id

Attributes that can be updated

Parameter Type Description
all_users_can_modify boolean Whether all users can make modifications to this Saved Search
approved_company_saved_search boolean Whether this is a company approved saved Search.
company_saved_search boolean Whether this is a company saved search or not.
locked boolean
name string The display name associated with this Search.
saved boolean Whether this is a saved search (1) or a regular temporary search (0). Please note, if you change this to 0, the Search will no longer be considered a Saved search and will lose its Name.
search_items array[SearchItem] The parameters associated with this SavedSearch. Read the section below for an explanation of this type of object.
share_with_all_users boolean Whether this object is shared with all users.

Updating Multiple Searches

PUT Request:

[
    {
        "id": 1534,
        "name": "Important Search Renamed!",
        "share_with_all_users": 1,
        "saved": 1
    },
    {
        "id": 1537,
        "name": "Renamed Search 2!",
        "share_with_all_users": 1,
        "saved": 1
    }
]

PUT (Truncated) Example Response:

[
    {
        "name": "Important Search Renamed!",
        "_http_header_X_Ignored_Fields": "id",
        "id": 1534,
        "share_with_all_users": 1,
        "http_status_code": 200,
        "saved": 1
    },
    {
        "name": "Renamed Search 2!",
        "_http_header_X_Ignored_Fields": "id",
        "id": 1537,
        "share_with_all_users": 1,
        "http_status_code": 200,
        "saved": 1
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/Searches/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

This endpoint allows creation of new Searches. The minimum required parameters to include in a POST request are the following:

Parameter Type Description
name string The string associated with the display name of this search
search_items SearchItem Object Search Item object is defined above.

The Search item Object also has minimum parameters required of it's own:

Parameter Type Description
code enum As defined in the section 'Available Enums'
values/ids string/int The values to apply to the search or the specific IDs to include in the search.

HTTP Request

POST https://example.openasset.com/REST/1/Searches/

This endpoint allows DELETES of searches.

HTTP Request

// Create a new search object
Search searchItem = new Search();

// Set the id to an existing image in OpenAsset
searchItem.Id = 41;

// Send the Search object to the DeleteObject method
conn.DeleteObject(noun);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')

# Any method below would work.
butler.delete_searches([41,42,43])
butler.delete_searches(['41','42','43'])
butler.delete_searches(41)
butler.delete_searches('41')

DELETE https://example.openasset.com/REST/1/Searches/:id

or

DELETE https://example.openasset.com/REST/1/Searches?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the Search to delete

Sizes

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Query Parameters: Sizes

Example JSON Object:

{
    "alive": 1,
    "allow_use": 1,
    "always_create": 1,
    "colourspace": "RGB",
    "crop_to_fit": 0,
    "description": "",
    "display_order": 2,
    "file_format": "jpg",
    "height": 240,
    "id": 2,
    "is_video": 0,
    "name": "Small",
    "original": 0,
    "postfix": "small",
    "protected": 1,
    "quality": 90,
    "size_protected": 1,
    "updated": "0",
    "use_for_contact_sheet": 0,
    "use_for_power_point": 0,
    "use_for_zip": 1,
    "width": 240,
    "x_resolution": 72,
    "y_resolution": 72
}
Parameter Type Description
alive boolean Whether this size is enabled.
allow_use boolean Whether this size can be utilized.
always_create boolean Whether this size will always be generated for newly uploaded images.
colourspace string The colourspace(RGB) for images generated in this size
crop_to_fit boolean Whether to crop the image to fit.
description string A description of this size.
display_order integer The order which this size is displayed on the ImageSizes page.
file_format string Size extension applied to images in this image size.
height integer The height dimension to apply to images in this size.
id integer The unique ID of this image size.
is_video boolean Whether this image size is for Videos.
name string The display name associated with this image size.
original boolean Whether this is the Original Image size.
postfix string A string applied to the end of the generated image size's filename.
protected boolean Whether this image size is protected from edits. Built in image sizes will be protected from edits.
quality integer An integer representing the JPG quality. The lower the quality the higher compression is used.
size_protected boolean Whether this size is protected.
updated datetime The last time this size was modified.
use_for_contact_sheet boolean Whether this image size will be utilized on the contact sheet.
use_for_power_point boolean Whether this image size will be utilized for powerpoints.
use_for_zip boolean Whether this image size can be included in Size exports/Batch Downloads.
width integer The width dimension to apply to images in this size.
x_resolution integer The X resolution (X DPI).
y_resolution integer The Y resolution (Y DPI).

Get All Sizes

This endpoint retrieves 10 sizes by default. To get ALL sizes on the endpoint add 'limit=0' to the request.

Example query:

private static List<Size> GetSizes()
        {
            RESTOptions<Size> options = new RESTOptions<Size>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Size>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
sizes = @@butler.get_sizes

HTTP Request

GET https://example.openasset.com/REST/1/Sizes

To get all sizes on the instance:

GET https://example.openasset.com/REST/1/Sizes?limit=0

Get a Specific Size

This endpoint retrieves a specific Size.

Example query - Get size ID 41:

private static List<Size> GetSizes()
        {
            RESTOptions<Size> options = new RESTOptions<Size>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Size>(41);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
sizes = @@butler.get_sizes(options)

HTTP Request

GET https://example.openasset.com/REST/1/Sizes/:id

URL Parameters

Parameter Description
ID The ID of the Size to retrieve

Update a Specific Size

Certain attributes of a Size noun can be updated. Below are the different attributes that can be updated:

Update the description of a size.

// Create a new size object
Size sizeItem = new Size();

// Set the id to an existing image in OpenAsset
sizeItem.Id = 41;

// Updating its description field
sizeItem.Description = "Updated Description!!";

// Make a PUT request by setting the last parameter as FALSE
Size responseSize = conn.SendObject<Size>(sizeItem, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
options.add_option('description', 'Updated Description!!')
sizes = @@butler.update_sizes(options)

HTTP Request

PUT https://example.openasset.com/REST/1/Sizes/:id

Attributes that can be updated

Parameter Type Description
description string A description of this size.
display_order integer The order which this size is displayed on the ImageSizes page.
name string The display name associated with this image size.
use_for_contact_sheet boolean Whether this image size will be utilized on the contact sheet.
use_for_power_point boolean Whether this image size will be utilized for powerpoints.
use_for_zip boolean Whether this image size can be included in File exports/Batch Downloads.

Updating Multiple Sizes

PUT Request:

[
    {
        "name": "SmallSize",
        "id": 2,
        "use_for_zip": 1,
        "use_for_contact_sheet": 1,
        "use_for_power_point": 1,
        "display_order": 4
    },
    {
        "name": "SquareRenamed",
        "id": 3,
        "use_for_zip": 1,
        "use_for_contact_sheet": 1,
        "use_for_power_point": 1,
        "display_order": 2
    },
    {
        "name": "ThumbnailRenamed",
        "id": 4,
        "use_for_zip": 1,
        "use_for_contact_sheet": 1,
        "use_for_power_point": 1,
        "display_order": 3
    }
]

PUT (Truncated) Example Response:

[
    {
        "id": 2,
        "use_for_contact_sheet": 1,
        "use_for_zip": 1,
        "display_order": 4,
        "use_for_power_point": 1,
        "_http_header_X_Ignored_Fields": "id",
        "name": "SmallSize",
        "http_status_code": 200
    },
    {
        "id": 3,
        "use_for_contact_sheet": 1,
        "use_for_zip": 1,
        "display_order": 2,
        "use_for_power_point": 1,
        "_http_header_X_Ignored_Fields": "id",
        "name": "SquareRenamed",
        "http_status_code": 200
    },
    {
        "id": 4,
        "use_for_contact_sheet": 1,
        "use_for_zip": 1,
        "display_order": 3,
        "use_for_power_point": 1,
        "_http_header_X_Ignored_Fields": "id",
        "name": "ThumbnailRenamed",
        "http_status_code": 200
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/Albums/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new Size

This endpoint allows for the creation of a new image Size. The minimum required parameters to include in a POST request are the following:

Parameter Type Description
postfix string The string appended to the end of the filename, before the file extension. I.E. For 'small': Foobar_small.jpg
file_format enum The file format to convert files in this image size to. Possible values include: 'jpg'
colourspace enum The colourspace to apply to files in this image size. Possible values include: 'RGB'
width int The width dimensions for the image size to adhere to.
height int The height dimensions for the image size to adhere to.
always_create boolean Whether to always create this image size (1), or to leave the image size for manual creation (0).

HTTP Request

POST https://example.openasset.com/REST/1/Sizes/

Delete a Specific Size

This endpoint allows DELETES of sizes.

HTTP Request

// Create a new size object
Size sizeItem = new Size();

// Set the id to an existing image in OpenAsset
sizeItem.Id = 41;

// Send the Size object to the DeleteObject method
conn.DeleteObject(noun);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')

# Any method below would work.
butler.delete_sizes([41,42,43])
butler.delete_sizes(['41','42','43'])
butler.delete_sizes(41)
butler.delete_sizes('41')

DELETE https://example.openasset.com/REST/1/Sizes/:id

or

DELETE https://example.openasset.com/REST/1/Sizes?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the size to delete

TextRewrites

Available HTTP Verbs include:

GET

Query Parameters: TextRewrites

Example JSON Object:

{
        "case_sensitive": 0,
        "id": 10,
        "preserve_first_letter_case": 1,
        "text_match": "External Use",
        "text_replace": "Rewriting External Use Access Level"
    }
Parameter Type Description
case_sensitive boolean Whether the TextRewrite will check case sensitivity.
id integer The Unique ID associated with this TextRewrite
preserve_first_letter_case boolean Maintain the case sensitivity of the first letter based on the matching text's case.
text_match string The string Openasset will search for to replace.
text_replace string The string OpenAsset will use to replace text_match.

Get All TextRewrites

This endpoint retrieves 10 text rewrites by default. To get ALL text rewrites on the endpoint add 'limit=0' to the request.

Example query:

private static List<TextRewrite> GetTextRewrites()
        {
            RESTOptions<TextRewrite> options = new RESTOptions<TextRewrite>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com", 
                "username", 
                "password"
            );
            return conn.GetObjects<TextRewrite>(options);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
textRewrites = @@butler.get_textRewrites

HTTP Request

GET https://example.openasset.com/REST/1/TextRewrites

To get all text rewrites on the instance:

GET https://example.openasset.com/REST/1/TextRewrites?limit=0

Get a Specific TextRewrite

This endpoint retrieves a specific TextRewrite.

Example query - Get textrewrite ID 41:

private static List<TextRewrite> GetTextRewrites()
        {
            RESTOptions<TextRewrite> options = new RESTOptions<TextRewrite>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com", 
                "username", 
                "password"
            );
            return conn.GetObjects<TextRewrite>(41);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
textRewrites = @@butler.get_textRewrites(options)

HTTP Request

GET https://example.openasset.com/REST/1/TextRewrites/:id

URL Parameters

Parameter Description
ID The ID of the TextRewrite to retrieve

Topics

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Query Parameters: Topics

Example JSON Object

{
    "id": 9,
    "code": "CompanyAlbumTopic",
    "display_order": 3,
    "name": "Company Album Topic",
    "protected": 0,
    "updated": "20190814173006"
}
Parameter Type Description
name string Display name associated with this Topic.
id integer The unique ID associated with this Topic.
protected boolean Whether this Topic can be deleted or not
code string Unique Code associated with this Topic
display_order integer The order in which this Topic is displayed on Front-end UI
updated datetime The last time this Topic had a property modified

Get All Topics

This endpoint retrieves 10 Topics by default. To get ALL topics on the endpoint add 'limit=0' to the request.

HTTP Request

GET https://example.openasset.com/REST/1/Topics

To get all topics on the instance:

GET https://example.openasset.com/REST/1/Topics?limit=0

Get a Specific Topic

This endpoint retrieves a specific Topic.

HTTP Request

GET https://example.openasset.com/REST/1/Topics/:id

URL Parameters

Parameter Description
ID The ID of the Topic to retrieve

Update a Specific Topic

Certain attributes of a Topic noun can be updated..

Attributes that can be updated

Parameter Type Description
name string Display name associated with this Topic.
display_order integer The order in which this Topic is displayed on Front-end UI

HTTP Request

PUT https://example.openasset.com/REST/1/Topics/:id

Updating Multiple Topics

PUT Request:

[
    {
        "id": 13,
        "name": "New Topic Name 2",
        "display_order": 3
    },
    {
        "id": 37,
        "name": "New Topic Name 2",
        "display_order": 5
    }
]

PUT Example Response:

[
    {
        "_http_header_X_Ignored_Fields": "id",
        "code": "NewTopicName1",
        "display_order": 3,
        "http_status_code": 200,
        "id": 13,
        "name": "New Topic Name 1",
        "protected": 0,
        "updated": "20190814172730"
    },
    {
        "_http_header_X_Ignored_Fields": "id",
        "code": "NewTopicName2",
        "display_order": 5,
        "http_status_code": 200,
        "id": 37,
        "name": "New Topic Name 2",
        "protected": 0,
        "updated": "20190814172730"
    }
]

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/Topics/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new Topic

This endpoint allows creation of Topics. Below are the required minimum parameters to create a new Topic:

Parameter Type Description
name string The display name associated with this Topic.

HTTP Request

POST https://example.openasset.com/REST/1/Topics/

Delete a Specific Topic

This endpoint allows DELETES of Topics.

HTTP Request

DELETE https://example.openasset.com/REST/1/Topics/:id

or

DELETE https://example.openasset.com/REST/1/Topics?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the Topic to delete

Merge Topics

MERGE Request:

[
    {
        "id": 40
    },
    {
        "id": 42
    }
]

or

[
    40,
    42
]

This endpoint allows the merging of one or more Topics into a single Topic. This targets a single Topic with the body being an array of ids or objects containing the id of what you want merged.

The response is the individual object GET after the merge request is completed.

HTTP Request

MERGE https://example.openasset.com/REST/1/Topics/:id

Users

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Query Parameters: Users

Example JSON Object:

{
    "alive": 1,
    "current_album_id": 817,
    "email": "",
    "expires": 0,
    "expiry_date": "20370101000000",
    "full_name": "token",
    "hidden": 0,
    "id": 22,
    "protected": 0,
    "username": "token",
    "valid": 1
}
Parameter Type Description
alive boolean Whether this User exists (1) or is disabled (0).
current_album_id integer The album the user currently has selected. Zero if the user has no album selected.
email string The email associated with this user.
expires boolean Whether this user will expire on the date time provided for expiry_date.
expiry datetime The date time when this user will expire if expires is true.
full_name string The full name associated with this user.
hidden boolean Whether this user is completely invisible to common users.
id integer The unique id associated with this User.
protected boolean Whether this user is protected from modifications.
username string The username associated with this User.
valid boolean Whether this account is not deleted (1) or deleted (0).

Get All Users

This endpoint retrieves 10 users by default. To get ALL users on the endpoint add 'limit=0' to the request.

Example query:

HTTP Request

GET https://example.openasset.com/REST/1/Users

To get all users on the instance:

GET https://example.openasset.com/REST/1/Users?limit=0

Get a Specific User

This endpoint retrieves a specific User.

Example query - Get user ID 41:

private static List<User> GetUsers()
        {
            RESTOptions<User> options = new RESTOptions<User>();
            Connection conn = Connection.GetConnection(
                "https://example.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<User>(41);
        }
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
users = @@butler.get_users(options)

HTTP Request

GET https://example.openasset.com/REST/1/Users/:id

URL Parameters

Parameter Description
ID The ID of the User to retrieve

Update a Specific User

Certain attributes of a User noun can be updated. Below are the different attributes that can be updated:

Update the username of a user.

// Create a new user object
User userItem = new User();

// Set the id to an existing image in OpenAsset
userItem.Id = 41;

// Updating its description field
userItem.Username = "Timmy";

// Make a PUT request by setting the last parameter as FALSE
User responseUser = conn.SendObject<User>(userItem, false);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')
options  = RestOptions.new
options.add_option('id', '41')
options.add_option('username', 'Timmy')
users = @@butler.update_users(options)

HTTP Request

PUT https://example.openasset.com/REST/1/Users/:id

Attributes that can be updated

Parameter Type Description
alive boolean Whether this User exists (1) or is disabled (0).
email string The email associated with this user.
expires boolean Whether this user will expire on the date time provided for expiry_date.
expiry datetime The date time when this user will expire if expires is true.
full_name string The full name associated with this user.
username string The username associated with this User.

Updating Multiple Users

PUT Request:

[
    {
        "id": 7,
        "email": "example2@axomic.com",
        "full_name": "Bill Microsoft"
    },
    {
        "id": 9,
        "email": "example@axomic.com",
        "full_name": "Tim Apple"
    }
]

PUT (Truncated) Example Response:

[
    {
        "email": "example2@axomic.com",
        "_http_header_X_Ignored_Fields": "id",
        "id": 7,
        "full_name": "Bill Microsoft",
        "http_status_code": 200
    },
    {
        "email": "example@axomic.com",
        "_http_header_X_Ignored_Fields": "id",
        "id": 9,
        "full_name": "Tim Apple",
        "http_status_code": 200
    }
]

There are two requirements for multi-item updating in one PUT request:

  1. Send an array of Objects.
  2. Send the unique ID with each respective object.

HTTP Request

Unlike with a singular HTTP Request, to update multiple items via PUT you must not specify the ID in the URL. Instead, you must specify the ID in the request body.

PUT https://example.openasset.com/REST/1/Users/

In addition to each respective Object's normal properties, you will see two unique response properties:

Parameter Type Description
_http_header_X_Ignored_Fields string The properties sent in the Request that were ignored by this endpoint. (Cannot be updated/modified).
http_status_code integer The HTTP Status Code associated with this response. 200 indicates success.

Create a new User

This endpoint allows for the creation of new Users. The minimum required parameters to include with a Users POST request are the following:

Parameter Type Description
full_name string The string associated with the display name of this user.
username string The login username.
password string The plain text password to set on this account. (Passwords WILL be salted and hashed).

HTTP Request

POST https://example.openasset.com/REST/1/Users/

Delete a Specific User

This endpoint allows DELETES of users.

HTTP Request

// Create a new user object
User userItem = new User();

// Set the id to an existing image in OpenAsset
userItem.Id = 41;

// Send the User object to the DeleteObject method
conn.DeleteObject(noun);
@@butler = OpenAsset::RestClient.new('https://example.openasset.com/', 'username')

# Any method below would work.
butler.delete_users([41,42,43])
butler.delete_users(['41','42','43'])
butler.delete_users(41)
butler.delete_users('41')

DELETE https://example.openasset.com/REST/1/Users/:id

or

DELETE https://example.openasset.com/REST/1/Users?id=41,42,43,44

URL Parameters

Parameter Description
ID The ID of the user to delete

Errors

The API returns a variety of errors:

Error Code Meaning
400 Bad Request -- No JSON body provided for POST request
401 Unauthorized -- Session not active, requires valid login,
403 Forbidden -- Access denied to access resource.
404 Not Found -- Cannot create requested REST module {Resource}
405 Method Not Allowed -- Method {VERB} not allowed on this object
409 Conflict -- An object matching the required parameters already exists.
500 Internal Server Error -- If this repeatedly occurs - contact OpenAsset Support