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# which leverage our publicly available REST Libraries.

You can find more information about these libraries here:

C# Library

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 Token Authentication outlined below:

Token Authentication

To create an authentication token, navigate to the security settings of your openasset system {client_domian}.openasset.com/Page/AuthenticationTokens and create a token. Please also make note of the token ID as this will be required within the header.

The process to use a token to authenticate is to use an Authorization header with the following format:

Header key: Authorization

Header Value: OATU <token_id>:<token_string>

Please make sure to include the OATU in the value section as this is required when making the request (as seen above). Add the authentication header to each call you make to the API.

Best Practices

For resource updates (POST, PUT, DELETE) we strongly advise a limit of 100 resources/objects per batch with a ceiling of no more than 200 objects per request.

For image uploads specifically, we recommend a max of 3gb worth of images per batch.

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:idDescididAsccodeDescIt'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.

exact - The value must match what is given on the URL completely.
contains - The value just needs to appear somewhere in the string.
wildcard - You have control of fuzzy matching by use of the * wildcard. To escape the * and search for it directly, use \*. Since \ is used for escaping, you must also escape it as \\. You may also include ! at the beginning of string to indicate a NOT match. To search for a literal ! at start of a string, you must escape it as \!.

URL Arrays and Objects

Some simple value to URL examples:

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

becomes

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



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

becomes

https://{client_domain}.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.

Array - For an array, you may add a numerical index, or leave it completely empty.
Object - For an object, rather than a numerical index - a non-numeric character is needed.

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

Filtering on Custom Fields

For the Files, Projects, and Employees endpoints, you can perform basic filtering on the custom fields to filter down the objects returned. You will need to use the field’s “rest_code” as a query parameter with a string value to filter on. This filtering method only allows for case insensitive string filtering. You can also utilize the textMatching parameter for additional string matching options.

For example, if we have a custom multi-line project field with the rest_code as “project_description” and we want to filter for all projects with “building”, we can perform the following call: GET: https://{client_domain}.openasset.com/REST/1/Projects?project_description=building&limit=50

Below is a list of all supported formats for filtering:

Field Types

REST API Field Types	Front End Name	Value Formats
singleLine	Single Line	String
multiLine	Multi Line	String
date	Date	String in a supported date format of: `YYYYMMDDHHMMSS` & `YYYY-MM-DD` Please see this section for additional date range filtering
suggestion	Auto-Complete	String (max 255 characters)
fixedSuggestion	Fixed Auto-Complete	String (max 255 characters)
option	Drop Down Menu	String (max 255 characters)
boolean	Yes/No Switch	Value of 0 or 1. With 1 corresponding to yes and 0 for no.

To filter on a Yes/No Switch field, you can make a request similar to the following:

Example: GET: https://{client_domain}.openasset.com/REST/1/Projects?project_completed=1

Multiple custom field filters can be used in a single call as well. (AND filtering). - Searching for projects where project description contains “park” AND city contains “london”:

Example: GET: https://{client_domain}.openasset.com/REST/1/Projects?project_description=park&city=london

For adding multiple filters for the same custom field (OR filtering):

Searching for projects where project description contains “the”, “park” or “london”

Example: GET: https://{client_domain}.openasset.com/REST/1/Projects?project_description[0]=the&project_description[1]=Park&project_description[2]=london

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.

Limit & Offsets

The limit and offset query parameters are available for users to batch requests. The limit will set the number of objects returned for your request while the offset will exclude/skip those number of objects from the request. The default limit is 10 objects returned for all endpoints.

To utilize the limit and offset feature for batching requests you can first choose a limit for your endpoint request and begin with an offset of 0.

Example: https://{client_domain}.openasset.com/REST/1/Files?limit=100&offset=0

Once the first set of data is returned, you can retrieve the next set of objects by adding the limit number to the existing offset and repeating until all objects are retrieved.

To know when to stop incrementing your offset, you can make your requests while incrementing the offset and stop when the number of objects retrieved is empty or less than the limit. Alternatively, you can retrieve the total number of objects for your query by making a request and checking the X-Full-Results-Count response header that is returned for each request.

Example with a total number of objects of 1234 and a limit of 250:

GET https://{client_domain}.openasset.com/REST/1/Files?limit=250&offset=250

GET https://{client_domain}.openasset.com/REST/1/Files?limit=250&offset=500

...

GET https://{client_domain}.openasset.com/REST/1/Files?limit=250&offset=1000

Limit & Offset Best Practices

For resource retrieval (GET) we STRONGLY recommend batching requests for endpoints with a large number of objects. Please avoid performing limit=0 queries on endpoints with large numbers of objects, such as: - Files - Projects - Employees

When batching please do not exceed a batch of objects greater than 500 for GET requests on the Files endpoint as the amount of data being returned per request increases, the amount of server resources and memory required will increase. Increasing the limit will allow for more objects to be returned at a time, but an unreasonably large limit may negatively impact the normal usage of OpenAsset for end users.

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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Album>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/Albums

To get all albums on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Album>(41);
        }

HTTP Request

GET https://{client_domain}.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);

HTTP Request

PUT https://{client_domain}.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:

Send an array of Objects.
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://{client_domain}.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);

HTTP Request

POST https://{client_domain}.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);

DELETE https://{client_domain}.openasset.com/REST/1/Albums/:id

DELETE https://{client_domain}.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

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

https://{client_domain}.openasset.com/REST/1/Albums/:id

Album Noun Expansions

Parameter	Description
groups	Returns an array that includes group ids in which the parent album(s) are shared with as well as associated modify permissions to the album(s) selected.
projects	Returns an array of project ids that is associated with an album
topics	Returns an array of associated topic ids
users	Returns an array of user ids in which the parent album(s) are shared with as well as associated modify permissions to the album(s) selected.

// Example of expanded groups request
https://{client_prefix}.openasset.com/REST/1/Albums/231?groups=all

[
  {
    "all_users_can_modify": 0,
    "code": "be7522bf9a3978250ed74859ccf658ea",
    "id": 231,
    "locked": 0,
    "created": "20190103113120",
    "approved_company_album": 1,
    "groups": [
      {
        "can_modify": 0,
        "id": 5
      }
    ],
    "private_image_count": 0,
    "unapproved_image_count": 0,
    "public_image_count": 17,
    "share_with_all_users": 0,
    "name": "Logos and Graphic Icons",
    "shared_album": 1,
    "company_album": 1,
    "my_album": 1,
    "updated": "20191010204248",
    "can_modify": 1,
    "user_id": 3,
    "description": ""
  }
]

// Example of expanded projects request
https://{client_prefix}.openasset.com/REST/1/Albums/126?projects=all

  {
    "company_album": 1,
    "can_modify": 1,
    "approved_company_album": 1,
    "projects": [
      {
        "id": 4
      },
      {
        "id": 3
      },
      {
        "id": 6
      }
    ],
    "all_users_can_modify": 0,
    "updated": "20210514195245",
    "private_image_count": 1,
    "user_id": 3,
    "locked": 0,
    "share_with_all_users": 1,
    "id": 126,
    "public_image_count": 15,
    "my_album": 1,
    "unapproved_image_count": 0,
    "shared_album": 1,
    "description": "",
    "name": "Best Furniture Shots",
    "created": "20160216103509",
    "code": "f0ffca19262a591d540917cde3dd8fb8"
  },

// Example of expanded topics request
https://{client_prefix}.openasset.com/REST/1/Albums/126?topics=all

[
  {
    "can_modify": 1,
    "company_album": 1,
    "approved_company_album": 1,
    "all_users_can_modify": 0,
    "updated": "20210514195245",
    "private_image_count": 1,
    "user_id": 3,
    "locked": 0,
    "id": 126,
    "share_with_all_users": 1,
    "public_image_count": 15,
    "my_album": 1,
    "unapproved_image_count": 0,
    "shared_album": 1,
    "description": "",
    "name": "Best Furniture Shots",
    "topics": [
      {
        "id": 5
      }
    ],
    "created": "20160216103509",
    "code": "f0ffca19262a591d540917cde3dd8fb8"
  }
]

// Example of expanded users request
https://{client_prefix}.openasset.com/REST/1/Albums/230?users=all

[
  {
    "shared_album": 1,
    "public_image_count": 30,
    "unapproved_image_count": 0,
    "share_with_all_users": 0,
    "name": "Employee Headshots",
    "private_image_count": 12,
    "approved_company_album": 1,
    "users": [
      {
        "id": 1,
        "can_modify": 0
      }
    ],
    "can_modify": 1,
    "user_id": 3,
    "description": "",
    "updated": "20210324005549",
    "my_album": 1,
    "company_album": 1,
    "locked": 0,
    "id": 230,
    "all_users_can_modify": 0,
    "code": "e74deaa099650292513cf15f88300d2a",
    "created": "20190103113006"
  },
]

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://{client_domain}.openasset.com", 
                "username", 
                "password"
            );
            return conn.GetObjects<AspectRatio>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/AspectRatios

To get all aspect ratios on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com", 
                "username", 
                "password"
            );
            return conn.GetObjects<AspectRatio>(1);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/AspectRatios/:id

URL Parameters

Parameter	Description
ID	The ID of the AspectRatio to retrieve

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.

Parameter	Description
ID	The ID of the Category to retrieve

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.

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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<CopyrightHolder>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/CopyrightHolders

To get all CopyrightHolders on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<CopyrightHolder>(1);
        }

HTTP Request

GET https://{client_domain}.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);

HTTP Request

PUT https://{client_domain}.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:

Send an array of Objects.
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://{client_domain}.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://{client_domain}.openasset.com/REST/1/CopyrightHolders/

Merge CopyrightHolders

MERGE Request:

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

or

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://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<CopyrightPolicy>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/CopyrightPolicies

To get all CopyrightPolicies on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<CopyrightPolicy>(1);
        }

HTTP Request

GET https://{client_domain}.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);

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:

Send an array of Objects.
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://{client_domain}.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://{client_domain}.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);

DELETE https://{client_domain}.openasset.com/REST/1/CopyrightPolicies/:id

DELETE https://{client_domain}.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

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://{client_domain}.openasset.com/REST/1/CoprightPolicies/:id

DataIntegrations

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Query Parameters: DataIntegrations

Example JSON Object:

{
    "name": "FooBar Connection",
    "alive": 0,
    "last_ping": "20200207091004",
    "display_order": 1,
    "address": "<Address>",
    "last_connect": "20200207091004",
    "data_integration_type": "vision",
    "id": 1,
    "version": "7.0.0000.000"
}

Parameter	Type	Description
alive	boolean	Whether this DataIntegration is enabled (1) or disabled (0).
name	string	The name of associated with this DataIntegration
last_ping	datetime	The last time a successful ping occurred to the address for this DataIntegration using the credentials provided.
display_order	number	The order this DataIntegration appears on the DataIntegrations list page.
address	integer	The Address associated with this DataIntegration.
last_connect	datetime	The last time a successful connection was established to the address for this DataIntegration using the credentials provided.
data_integration_type	string	The type of data integration connection. ('cosential', 'vision')
id	integer	The unique id associated with this DataIntegration.
version	string	The current version of the system this DataIntegration is associated with.

Get All DataIntegrations

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

Example query:

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/DataIntegrations

To get all data integrations on the instance:

GET https://{client_domain}.openasset.com/REST/1/DataIntegrations?limit=0

Get a Specific DataIntegration

This endpoint retrieves a specific DataIntegration.

Example query - Get DataIntegration ID 41:

private static List<DataIntegration> GetDataIntegrations()
        {
            RESTOptions<DataIntegration> options = new RESTOptions<DataIntegration>();
            Connection conn = Connection.GetConnection(
                "https://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<DataIntegration>(41);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/DataIntegrations/:id

URL Parameters

Parameter	Description
ID	The ID of the DataIntegration to retrieve

Update a Specific DataIntegration

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

Update the name of a DataIngration.

// Create a new user object
DataIntegration aDataIntegration = new DataIntegration();

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

// Updating its description field
aDataIntegration.name = "New name";

// Make a PUT request by setting the last parameter as FALSE
DataIntegration responseDataIntegration = conn.SendObject<DataIntegration>(aDataIntegration, false);

HTTP Request

PUT https://{client_domain}.openasset.com/REST/1/DataIntegrations/:id

Attributes that can be updated

Parameter	Type	Description
alive	boolean	Whether this DataIntegration is enabled (1) or disabled (0).
name	string	The name of associated with this DataIntegration
display_order	number	The order this DataIntegration appears on the DataIntegrations list page.
address	integer	The Address associated with this DataIntegration.

Updating Multiple DataIntegrations

PUT Request:

[
    {
        "id": 7,
        "name": "DataIntegrationRenamed"
    },
    {
        "id": 9,
        "name": "DataIntegrationRenamed2"
    }
]

PUT (Truncated) Example Response:

[
    {
        "_http_header_X_Ignored_Fields": "id",
        "id": 7,
        "name": "DataIntegrationRenamed",
        "http_status_code": 200
    },
    {
        "_http_header_X_Ignored_Fields": "id",
        "id": 9,
        "name": "DataIntegrationRenamed",
        "http_status_code": 200
    }
]

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

Send an array of Objects.
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://{client_domain}.openasset.com/REST/1/DataIntegrations/

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 DataIntegration

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

Parameter	Type	Description
name	string	The name of associated with this DataIntegration
display_order	number	The order this DataIntegration appears on the DataIntegrations list page.
address	integer	The Address associated with this DataIntegration.
data_integration_type	string	The type of data integration connection. ('cosential', 'vision')

HTTP Request

POST https://{client_domain}.openasset.com/REST/1/DataIntegrations/

Delete a Specific DataIntegration

This endpoint allows DELETES of dataintegrations.

HTTP Request

// Create a new user object
DataIntegration aDataIntegration = new DataIntegration();

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

// Send the DataIntegration object to the DeleteObject method
conn.DeleteObject(noun);

DELETE https://{client_domain}.openasset.com/REST/1/DataIntegrations/:id

DELETE https://{client_domain}.openasset.com/REST/1/DataIntegrations?id=41,42,43,44

URL Parameters

Parameter	Description
ID	The ID of the user to delete

DataIntegration Noun Expansions

Parameter	Description
employeeKeywordCategories	Returns an array of employee keyword category ids mapped to the data integration
fields	Returns an array of field ids for a given data integration
keywordCategories	Returns an array of keywordCategory ids mapped to the data integration
projectKeywordCategories	Returns an array of project keyword category ids that are mapped to the integration

// Example of fields expansion from DataIntegrations parent
https://{client_prefix}.openasset.com/REST/1/DataIntegrations/1?fields=all

[
  {
    "alive": 1,
    "fields": [
      {
        "id": 41
      },
      {
        "id": 6
      },
      {
        "id": 9
      },
      {
        "id": 42
      },
      {
        "id": 37
      },
      {
        "id": 7
      }
    ],
    "version": "4.5.5.1217",
    "name": "Vantagepoint",
    "last_ping": "20220217111304",
    "data_integration_type": "vision",
    "id": 1,
    "last_connect": "20220217111304",
    "address": "https://vpopenasset.{client}.com/Vantagepoint/api",
    "display_order": 1
  }
]

// Example of nested keyword categories request
https://{client_prefix}.openasset.com/REST/1/DataIntegrations/1?keywordCategories=all

[
  {
    "last_ping": "20220209193239",
    "name": "Vision",
    "alive": 1,
    "last_connect": "20220209193239",
    "address": "https://vision.{client}.com/Vision/VisionWS.asmx",
    "version": "7.6.0767.050",
    "keywordCategories": [
      {
        "id": 42
      },
      {
        "id": 37
      },
      {
        "id": 7
      }
    ],
    "display_order": 1,
    "data_integration_type": "vision",
    "id": 1
  }
]

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://{client_domain}.openasset.com/REST/1/Employees

To get all employees on the instance:

GET https://{client_domain}.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://{client_domain}.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://{client_domain}.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://{client_domain}.openasset.com/REST/1/Employees/:id

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

URL Parameters

Parameter	Description
ID	The ID of the employee to delete

Employee Files Display Order

The Employee Files Noun Expansion contains a display_order field that allows order control for how files can be displayed or viewed within the Employees endpoint. Files that are associated with an employee will be automatically assigned an incremental display_order value for that employee. Each employee will have its own set of display orders for the associated employee files.

The display_order values will start at 1 and auto-increment as files are added to the employee. You can perform requests with the orderBy parameter set to display_order or display_orderDesc to have results ordered by the display order values in ascending or descending order.

Editing Employee Files display_order Values

The display_order values for an employee file can be set for each individual employee via PUT requests. You can first perform a GET request to the Employee Files Noun Expansion to retrieve an employee’s file ids with their display_order values. Once you have the values you want to update, you can perform a PUT request to the Employee Files Noun Expansion (seen in request below) with the new display_order values using the file ids. We recommend batching your GET requests with limit and offset values for any Employees with a large number of files for your system.

Example GET request:
https://{client}.openasset.com/REST/1/Employees/{{employee_id}}/Files?limit=200&offset=0

API Response: [ { "display_order": 1, "id": 16 }, { "id": 17, "display_order": 2 }, { "id": 18, "display_order": 3 }, { "id": 19, "display_order": 4 } ] Example PUT request: https://{client}.openasset.com/REST/1/Employees/{{employee_id}}/Files JSON Body: [ { "id": 16, "display_order": 2 }, { "id": 17, "display_order": 4 }, { "id": 18, "display_order": 1 }, { "id": 19, "display_order": 3 } ] This request will re-order these files from [16, 17, 18, 19] to [18, 16, 19, 17] when the files are ordered by the new display order values.

Employee Noun Expansions

Please reach out to our support team for more details on employee noun expansions.

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",
    "hero": 0,
    "id": 1,
    "include_on_info": 0,
    "include_on_search": 1,
    "name": "Client",
    "protected": 0,
    "regex": "",
    "regex_description": "",
    "required": 0,
    "rest_code": "Client",
    "updated": "20180726164253",
    "value_order_by": "displayOrder"
}

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
boolean	String or Integer with values of 0 or 1 (empty string is equivalent to 0)

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.
hero	boolean	Whether the field is prominently displayed on the respective view page. There can only be 1 hero field per field_type.
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.
value_order_by	enum	The ordering used for this field: displayOrder (default), name or nameDesc

Please see this section for more information on filtering

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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Field>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/Fields

To get all fields on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Field>(1);
        }

HTTP Request

GET https://{client_domain}.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://{client_domain}.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);

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:

Send an array of Objects.
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://{client_domain}.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://{client_domain}.openasset.com/REST/1/Fields/

Delete a Specific Field

This endpoint allows DELETES of fields.

HTTP Request

DELETE https://{client_domain}.openasset.com/REST/1/Fields/:id

DELETE https://{client_domain}.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,
        "is_vr": 0,
        "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
is_vr	boolean	Whether the file is a panoramic VR 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
original_filesize	integer	The size, in bytes, of the file to be uploaded.
aws_presigned_urls	dict	Returned upon making the initial POST request when uploading a file directly to AWS.
s3_upload_complete	boolean	Used to indicate when a file has been uploaded to S3 when uploading a file to AWS.

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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<File>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/Files

To get all files on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<File>(41);
        }

HTTP Request

GET https://{client_domain}.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);

HTTP Request

PUT https://{client_domain}.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:

Send an array of Objects.
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://{client_domain}.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. There are currently two paths to upload a file to OpenAsset. The minimum required parameters to include in a POST request for the first path this endpoint are the following:

First OpenAsset API Request (POST)

URL Parameters

Parameter	Description
partNumbers	Comma-separated list of numbers specifying which parts to return AWS Presigned URLs for. "all" is also accepted, which will return the AWS Presigned URLs for all parts.

JSON body required parameters

Parameter	Types	Description
category_id	int	The Category ID to upload this file to
project_id	int	If uploading to a project based category, this is required. Otherwise, this parameter can be omitted.
original_filename	string	This MUST match the filename of the file to be uploaded.
original_filesize	int	This MUST match the filesize of the file to be uploaded. This parameter is required for the path to send files directly to S3.
part_size	int	(Optional) The size, in bytes per part. If omitted, it will default to 1GB or total size if filesize is under 1GB.

Sending Files to Amazon S3

The OpenAsset id of the file object that has been created and the AWS Presigned URL for the first part will be returned upon the initial post request by default if partNumbers is not specified in the request URL. Otherwise, to get the AWS Presigned URLs for the rest of the parts, users may make a GET request with the partNumbers parameter to get whichever other parts they need. Please note that the AWS Presigned URLs expire after 60 seconds, thus, we recommend not grabbing all of them at once for larger uploads with a larger amount of parts. For each part, the user will send the portion of the file with the presigned URL as the request URL as a PUT. Each part will return an ETag in the response headers. These ETags must be saved/noted for the final API request.

Last OpenAsset API Request (PUT)

JSON body required parameters

Parameter	Types	Description
id	int	The OpenAsset id of the file that has been uploaded.
s3_upload_complete	int	The value sent should be 1 to tell the API that the s3 uploads have been completed.
etags	arr, dict	Array or dictionary of etags returned from the S3 API to complete the upload. If dictionary is sent, keys must be the part numbers.

Second Pathway for Uploading Files

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://{client_domain}.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);

DELETE https://{client_domain}.openasset.com/REST/1/Files/:id

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

URL Parameters

Parameter	Description
ID	The ID of the file to delete

Files Noun Expansions

Parameter	Description
fields	Returns an array including the id and values for any given file(s)
keywords	Returns array of keyword ids for any given file(s)
albums	Returns an array of album ids that the file is included in
sizes	Returns an array of image size attributes for any given file(s) which can be parsed to create a static image link
employees	Returns an array of employee ids that are associated with any given file(s)

// Example of expanded fields request
https://{client_prefix}.openasset.com/REST/1/Files?id=32&fields=all

[
  {
    "recheck": 0,
    "copyright_holder_id": 2,
    "deleted_user_id": 3,
    "original_filename": "A0061_N22.jpg",
    "similarity_indexed": "0",
    "project_id": 4,
    "click_count": 0,
    "created": "20091015115217",
    "rank": 5,
    "access_level": 1,
    "fields": [
      {
        "id": 48,
        "values": [
          0
        ]
      },
      {
        "values": [
          "Charlotte Building, Gresse Street"
        ],
        "id": 44
      },
      {
        "values": [
          ""
        ],
        "id": 47
      },
      {
        "values": [
          ""
        ],
        "id": 42
      }
    ],
    "replaced_user_id": 0,
    "md5_now": "",
    "alive": 0,
    "original_details_verified": 1,
    "caption": "",
    "user_id": 3,
    "similarity_attempts": 0,
    "processing_failures": 6,
    "rotate_degrees": 0,
    "id": 32,
    "contains_video": 0,
    "download_count": 0,
    "video_frames_per_second": 0,
    "filename": "A0061_N4.jpg",
    "photographer_id": 13,
    "duration": 0,
    "replaced": "0",
    "md5_at_upload": "e97b5e51e03cd8f1618d9be875b89ebd",
    "category_id": 1,
    "contains_audio": 0,
    "alternate_store_id": 0,
    "description": "",
    "rotation_since_upload": 0,
    "uploaded": "20150211142343",
    "deleted": "20150211142858",
    "updated": "20200604200116"
  }
]

// Example of expanded keywords request
https://{client_prefix}.openasset.com/REST/1/Files/460?keywords=all

[
  {
    "download_count": 0,
    "contains_video": 0,
    "id": 460,
    "video_frames_per_second": 0,
    "filename": "S_181211_N2.jpg",
    "duration": 0,
    "replaced": "0",
    "photographer_id": 5,
    "md5_at_upload": "583669aa3e59a18d701b4d239875588f",
    "keywords": [
      {
        "id": 61
      },
      {
        "id": 77
      }
    ],
    "category_id": 3,
    "alternate_store_id": 0,
    "contains_audio": 0,
    "updated": "20200428235744",
    "rotation_since_upload": 0,
    "description": "",
    "uploaded": "20181211113023",
    "deleted": "0",
    "copyright_holder_id": 0,
    "recheck": 0,
    "deleted_user_id": 0,
    "click_count": 0,
    "original_filename": "A0061_N45.jpeg",
    "similarity_indexed": "20190128161401",
    "project_id": 0,
    "access_level": 1,
    "md5_now": "",
    "replaced_user_id": 0,
    "created": "0",
    "rank": 5,
    "alive": 1,
    "original_details_verified": 1,
    "similarity_attempts": 0,
    "processing_failures": 0,
    "rotate_degrees": 0,
    "caption": "This is a test",
    "user_id": 3
  }
]

// Example of expanded albums request
https://{client_prefix}.openasset.com/REST/1/Files/460?albums=all

[
  {
    "deleted_user_id": 0,
    "copyright_holder_id": 0,
    "recheck": 0,
    "replaced_user_id": 0,
    "md5_now": "",
    "access_level": 1,
    "rank": 5,
    "created": "0",
    "click_count": 0,
    "project_id": 0,
    "similarity_indexed": "20190128161401",
    "original_filename": "A0061_N45.jpeg",
    "rotate_degrees": 0,
    "processing_failures": 0,
    "similarity_attempts": 0,
    "user_id": 3,
    "caption": "This is a test",
    "alive": 1,
    "original_details_verified": 1,
    "video_frames_per_second": 0,
    "download_count": 0,
    "contains_video": 0,
    "id": 460,
    "replaced": "0",
    "duration": 0,
    "albums": [
      {
        "id": 230
      },
      {
        "id": 405
      },
      {
        "id": 437
      }
    ],
    "photographer_id": 5,
    "filename": "S_181211_N2.jpg",
    "category_id": 3,
    "md5_at_upload": "583669aa3e59a18d701b4d239875588f",
    "updated": "20200428235744",
    "deleted": "0",
    "uploaded": "20181211113023",
    "rotation_since_upload": 0,
    "description": "",
    "alternate_store_id": 0,
    "contains_audio": 0
  }
]

// Example of expanded sizes request
https://{client_prefix}.openasset.com/REST/1/Files/463?sizes=all

{
  "rotate_degrees": 0,
  "deleted": "0",
  "caption": "This is a test",
  "alive": 1,
  "replaced": "0",
  "replaced_user_id": 0,
  "id": 460,
  "project_id": 0,
  "processing_failures": 0,
  "contains_video": 0,
  "description": "",
  "created": "0",
  "category_id": 3,
  "original_filename": "Becky Pitcher.jpeg",
  "contains_audio": 0,
  "rank": 5,
  "rotation_since_upload": 0,
  "md5_now": "",
  "video_frames_per_second": 0,
  "uploaded": "20181211113023",
  "download_count": 0,
  "user_id": 3,
  "photographer_id": 5,
  "click_count": 0,
  "filename": "S_181211_N2.jpg",
  "recheck": 0,
  "md5_at_upload": "583669aa3e59a18d701b4d239875588f",
  "copyright_holder_id": 0,
  "deleted_user_id": 0,
  "original_details_verified": 1,
  "sizes": [
    {
      "cropped": 0,
      "width": 337,
      "file_format": "jpg",
      "id": 8,
      "relative_path": "583669aa3e59a18d701b4d239875588f/S_181211_N2_jpg/S_181211_N2_medium.jpg",
      "colourspace": "RGB",
      "y_resolution": 150,
      "default_office_size": 1,
      "x_resolution": 150,
      "quality": 0,
      "height": 337,
      "allow_use": 1,
      "http_root": "//data.openasset.com/db5c2e04/",
      "recreate": 0,
      "watermarked": 0,
      "filesize": 39859,
      "unc_root": "//data.openasset.com/db5c2e04/",
      "http_relative_path": "583669aa3e59a18d701b4d239875588f/S_181211_N2_jpg/S_181211_N2_medium.jpg"
    },
    {
      "filesize": 38274,
      "http_relative_path": "583669aa3e59a18d701b4d239875588f/S_181211_N2.jpg",
      "unc_root": "//data.openasset.com/db5c2e04/",
      "watermarked": 0,
      "recreate": 0,
      "http_root": "//data.openasset.com/db5c2e04/",
      "allow_use": 1,
      "x_resolution": 0,
      "height": 337,
      "quality": 0,
      "default_office_size": 0,
      "y_resolution": 0,
      "colourspace": "RGB",
      "file_format": "jpg",
      "id": 1,
      "relative_path": "583669aa3e59a18d701b4d239875588f/S_181211_N2.jpg",
      "width": 337,
      "cropped": 0
    },
    {
      "recreate": 0,
      "http_root": "//data.openasset.com/db5c2e04/",
      "http_relative_path": "583669aa3e59a18d701b4d239875588f/S_181211_N2_jpg/S_181211_N2_small.jpg",
      "unc_root": "//data.openasset.com/db5c2e04/",
      "filesize": 22337,
      "watermarked": 0,
      "height": 240,
      "quality": 90,
      "x_resolution": 72,
      "default_office_size": 0,
      "allow_use": 1,
      "colourspace": "RGB",
      "y_resolution": 72,
      "width": 240,
      "cropped": 0,
      "id": 2,
      "relative_path": "583669aa3e59a18d701b4d239875588f/S_181211_N2_jpg/S_181211_N2_small.jpg",
      "file_format": "jpg"
    }
  ],
  "updated": "20200428235744",
  "duration": 0,
  "similarity_attempts": 0,
  "access_level": 1,
  "similarity_indexed": "20190128161401",
  "alternate_store_id": 0
}

// Example of expanded employees request
https://{client_prefix}.openasset.com/REST/1/Files/463?employees=all

{
  "copyright_holder_id": 11,
  "md5_at_upload": "04e8a746218e2c68c5fd6076e39d052a",
  "recheck": 0,
  "filename": "S_181211_N5.jpg",
  "alternate_store_id": 0,
  "access_level": 1,
  "similarity_indexed": "20190128161409",
  "similarity_attempts": 0,
  "duration": 0,
  "updated": "20200609184008",
  "original_details_verified": 1,
  "deleted_user_id": 0,
  "photographer_id": 5,
  "user_id": 3,
  "click_count": 0,
  "employees": [
    {
      "id": 16
    }
  ],
  "video_frames_per_second": 0,
  "rotation_since_upload": 0,
  "rank": 5,
  "md5_now": "",
  "contains_audio": 0,
  "original_filename": "Main_Photo.JPG",
  "category_id": 3,
  "download_count": 0,
  "uploaded": "20181211113023",
  "replaced_user_id": 0,
  "alive": 1,
  "replaced": "0",
  "caption": "Test",
  "deleted": "0",
  "rotate_degrees": 0,
  "contains_video": 0,
  "description": "",
  "created": "20170309141133",
  "processing_failures": 0,
  "project_id": 0,
  "id": 463
}

Project Display Order For Files

The project_display_order field allows for controlling the order for how files can be displayed or viewed for the Files endpoint. Files that are associated with a project will be automatically assigned an incremental project_display_order value for that project. Each project will have its own set of display orders for the associated project files. The display_order values will start at 1 and auto-increment as files are added to the project. You can perform api requests with the orderBy parameter set to project_display_order or project_display_orderDesc for results to be ordered by the project_display_order values (ascending or descending order).

Editing project_display_order

The project_display_order values can be set for each individual file in a project via PUT requests. You can first perform a GET request to the Files endpoint to retrieve a project’s file ids with their project_display_order value. Once you have the values you want to update, you can perform a PUT request back to the files endpoint with the new project_display_order values using the file ids. We recommend performing your GET request with a project_id filter to limit results to a particular project and batching your GET requests with limit and offset values for projects with a large number of files for your system.

Example GET request:
https://{client}.openasset.com/REST/1/Files?project_id={project_id}&displayFields=id,project_id,project_display_order&orderBy=project_display_order&limit=200&offset=0

First four objects in GET response: ```json [ { "project_id": 3, "project_display_order": 1, "id": 16 }, { "id": 17, "project_display_order": 2, "project_id": 3 }, { "project_id": 3, "project_display_order": 3, "id": 18 }, { "project_id": 3, "id": 19, "project_display_order": 4 } ]

Example PUT request:
```json
[
   {
       "project_id": 3,
       "project_display_order": 2,
       "id": 16
   },
   {
       "id": 17,
       "project_display_order": 4,
       "project_id": 3
   },
   {
       "project_id": 3,
       "project_display_order": 1,
       "id": 18
   },
   {
       "project_id": 3,
       "id": 19,
       "project_display_order": 3
   }
]

This request will re-order these files from [16, 17, 18, 19] to [18, 16, 19, 17] when the files are ordered by project_display_order.

Grid Fields

Available HTTP Verbs include:

GET

PUT

Grids are available for any Field that is using the grid field_display_type. Instead of a single value, they will be represented by an object. That object will contain the following:

{
    "limit": "<int>",
    "offset": "<int>",
    "total": "<<int>",
    "rows": [
       {
         "_row": "<int>",
         "<grid_column_code>": "<grid column data type>"
       }
    ]
}

For example, here is some data for a grid Field with the rest_code of roles. It contains 4 GridColumns each with the code: end_date, project_role, role_description, start_date.

[
  {
    "id": "1",
    "roles": {
      "limit": 10,
      "offset": 0,
      "rows": [
        {
          "_row": "1",
          "end_date": 0,
          "project_role": "Lead Engineer",
          "role_description": "Oversee All Design and Engineering",
          "start_date": "20150102000000"
        }
      ],
      "total": "1"
    }
  }
]

Parameter	Description
limit	Used to identify how many rows maximum will be showed or referenced when updating
offset	How many rows to skip from the start before the rows array starts
rows	The array of the rows returned for this grid _row - This gives the current row number. Can be used to move a row when updating, explained below.

GET Parameters for Grids

The offset and limit on grid objects can be controlled with URL parameters. The two universal ones are:

Parameter	Description
gridLimit	Limit for all grids that don't have a specific limit set, default 10, 0 will make the grid return all rows
gridOffset	Offset for all grids that don't have a specific offset set, default 0

To give a specific offset and limit, you would use <rest_code>[offset] and <rest_code>[limit]. For instance, if you had a grid Field with rest_code patents that you wanted the 6th row from while getting the first 3 rows for the other grid fields, you would use the following URL: /REST/1/Projects/1/Fields?gridLimit=3&patents[offset]=5&patents[limit]=1

This would result with patents having an offset of 5 and limit of 1 while any other grid fields would have offset of 0 and limit of 3.

Editing Row Data

PUT

Set the offset and limit to include the specific row or rows to be edited and change the data. The offset must be used in order to target the correct rows for editing. The first object correlates with an offset of 0. Only the fields that need changing need to be included but including data that has not been changed will not do anything than excluding it. For example, this changes the start_date field from above without modifying anything else:

[
  {
    "id": "1",
    "roles": {
      "limit": 1,
      "offset": 0,
      "rows": [
        {
          "start_date": "20141102000000"
        }
      ]
    }
  }
]

Adding Rows to Grids

PUT

To add new rows, you can either set the offset as “-1” or set the offset to be equal to the current number of existing rows in the rows array. Using the above example, here is adding a new row:

[
  {
    "id": "1",
    "roles": {
      "limit": 1,
      "offset": -1,
      "rows": [
        {
          "end_date": 0,
          "project_role": "Junior Engineer",
          "role_description": "Support Design and Engineering",
          "start_date": "20141002000000"
        }
      ]
    }
  }
]

It is also acceptable to edit the last rows by having the offset below total and include new rows that would go beyond the currently stored rows. Here is an example where the description is changed from before on the existing row with a new row being added.

[
  {
    "id": "1",
    "roles": {
      "limit": 2,
      "offset": 0,
      "rows": [
        {
          "role_description": "Oversee All Design and Engineering including Junior Engineers"
        },
        {
          "end_date": 0,
          "project_role": "Junior Engineer",
          "role_description": "Support Design and Engineering",
          "start_date": "20141002000000"
        }
      ]
    }
  }
]

Deleting Rows

PUT

To remove a row, include the row within the offset/limit range and set “rows” as an empty array [] . For example, to delete the second row added above:

[
  {
    "id": "1",
    "roles": {
      "limit": 1,
      "offset": 1,
      "rows": []
    }
  }
]

Note:

This can delete multiple rows. So take care of limit and offset values when editing grid data to make sure it lines up with the desired effect. It is highly recommended to work on one row at a time when making changes using limit=1.

Moving Rows

PUT

The special field _row not only tells what number a row is on GET, but can be used for changing the order of rows. Let's say after adding our new row above, we wanted to change row 2 to be row 1. This can be accomplished with:

[
  {
    "id": "1",
    "roles": {
      "limit": 1,
      "offset": 1,
      "rows": [
        {
          "_row": "1"
        }
      ]
    }
  }
]

This will shift the current row 1 down to be row 2. If there were multiple rows, then all rows after the listed move will be shifted down as well.

Grid Columns

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Endpoint

{client_domain}.openasset.com/REST/1/Fields/:id/GridColumns

This endpoint is used for manipulating GridColumns for a Grid Field in the system. Objects are always returned in a JSON format within an array. Empty results return an empty array.

The GridColumn object takes the following JSON object:

[
  {
    "code": "<string>",
    "display_order": "<int>",
    "field_display_type": "<enum>",
    "id": "<int>",
    "name": "<string>",
    "field_id": "<int>"
  }
]

Note:

field_id will not show up in the standard GET, only if using the optional GET without Fields in the endpoint.

ExampleGET: {client_domain}.openasset.com/REST/1/GridColumns/:id

As with other resources, this resource is subject to the global parameters mentioned in the REST Overview.

`PUT`

The following JSON parameters are available when updating a resource:

JSON Parameter	Allowed Values
code	string
name	string
display_order	integer

`POST`

The following JSON parameters are required when creating a resource:

JSON Parameter	Allowed Values
name	string
field_display_type	enum: suggestion, fixedSuggestion, option, singleLine, multiLine, date, boolean

`DELETE`

The resource can be deleted using this verb and including the id in the above endpoint URL

Examples

Fetching GridColumns for a grid GET:

https://{client_domain}.openasset.com/REST/1/Fields/61/GridColumns

https://{client_domain}.openasset.com/REST/1/Fields?id=61&gridColumns=all

`PUT` Examples:

https://{client_domain}.openasset.com/REST/1/Projects/35?fields=61

PUT will update the second object in the list offset = 1 if there are 2 or more objects already. limit = 1 ensures that only max of 1 object is edited:

{
  "fields": [
    {
      "id": 61,
      "rows": [
        {
          "test_singleline": "4",
          "test_multiline": "4"
        }
      ],
      "limit": 1,
      "offset": 1
    }
  ]
}

PUT update creates a new grid field object offset = -1:

{
  "fields": [
    {
      "id": 61,
      "rows": [
        {
          "test_singleline": "4",
          "test_multiline": "4"
        }
      ],
      "limit": 1,
      "offset": -1
    }
  ]
}

PUT will delete the second grid field offset=1:

{
  "fields": [
    {
      "id": 61,
      "rows": [
      ],
      "limit": 1,
      "offset": 1
    }
  ]
}

PUT will move gird field row object at offset=2 to 1st row position:

{
  "fields": [
    {
      "id": 61,
      "rows": [
        {"_row": "1"}
      ],
      "limit": 1,
      "offset": 2
    }
  ]
}

EMPLOYEE PROJECT ROLES WITH GRID FIELDS

Available HTTP Verbs include:

GET

POST

PUT

DELETE

Employee-Project Roles grid field type specifically for linking projects with employees. This explicit roles grid will at a minimum contain the employee or project along with the employee’s role, a description of the role, the start and end dates, and the hours for each employee-project link. You can think of each Employee-Project relation as a separate grid field and the full list of employee-project roles to be a collection of grid fields that pertain to each employee-project pair.

Interacting with the employee-project roles grids will be similar to regular grid fields with exceptions being endpoint variation and the introduction of default grid columns.

`GET` Examples for Employee-Project Roles:

While employee-project roles are similar to regular grid fields, they exist under their special endpoints. The role data can be accessed in multiple ways.

Endpoints from the Projects perspective:

https://{client_domain}.openasset.com/REST/1/Projects/{{project_id}}/Employees

https://{client_domain}.openasset.com/REST/1/Projects/?employees=all

https://{client_domain}.openasset.com/REST/1/Projects/{{project_id}}?employees=all

https://{client_domain}.openasset.com/REST/1/Projects/?id={{project_id}}&employees=all

https://{client_domain}.openasset.com/REST/1/Projects/{{project_id}}/Employees/{{employee_id}}

Endpoints From the Employees perspective:

https://{client_domain}.openasset.com/REST/1/Employees/{{employee_id}}/Projects

https://{client_domain}.openasset.com/REST/1/Employees?projects=all

https://{client_domain}.openasset.com/REST/1/Employees/{{employee_id}}?projects=all

https://{client_domain}.openasset.com/REST/1/Employees?id={{employee_id}}&Projects=all

https://{client_domain}.openasset.com/REST/1/Employees/{{employee_id}}/Projects/{{project_id}}

Context:

As the roles exist via a link to a project and employee, they can be accessed from both the Projects Endpoint as well as the Employees endpoint. Keep in mind is that the nested ids will correspond to the nested noun.

At the top level base noun, the roles will show up with the nested nouns as an object including all roles which are identified by the id of the nested noun. For example, https://{client_domain}.openasset.com/REST/1/Projects/{{project_id}}/Employees will return employee nested noun role objects for the project.

Each employee-project pair behaves like a grid field. As it is possible for multiple employee-project roles to exist for an employee-project role pair, there may be multiple rows for each employee-project grid.

If you want to retrieve the roles for a specific employe-project pair, you can use the full nested expansion:

https://{client_domain}.openasset.com/REST/1/Projects/{{project_id}}/Employees/{{employee_id}}

https://{client_domain}.openasset.com/REST/1/Employees/{{employee_id}}/Projects/{{project_id}}

Editing Employee-Project Roles:

There are multiple ways to edit employee-project roles depending on which endpoint variant you use.

PUT Example:

https://{client_domain}.openasset.com/REST/1/Projects/33/Employees

[
  {
    "id": 7,
    "roles": {
      "rows": [
        {
          "end_date": "0",
          "project_role": "test",
          "hours": "",
          "start_date": "20200605000600",
          "role_description": "test1"
        }
      ],
      "limit": 10,
      "total": 1,
      "offset": 0
    }
  }
]

The above will overwrite the entire list of Employee roles for the project with an id of 33 with a single employe-project role for the employee id 7. The specifics of how to format the json body will be similar to editing a regular grid field. You can use the offset parameter to specify which row object you are editing. Please keep in mind that because this is a PUT request, it will also overwrite any other employee roles for this project other than the employee with the id of 7.

A safer way of editing a specific employee project role is to use the full nested expansion. You can also edit a specific employee-project role by performing a POST request to the full nested expansion and editing the grid data for just that employee-project pair seen below:

POST Example:

https://{client_domain}.openasset.com/REST/1/Projects/33/Employees/7

[
  {
    "id": 7,
    "roles": {
      "rows": [
        {
          "end_date": "0",
          "project_role": "test",
          "hours": "",
          "start_date": "20200605000600",
          "role_description": "test1"
        }
      ],
      "limit": 10,
      "total": 1,
      "offset": 0
    }
  }
]

The above will only update the employe-projects grid for the project 33 and employee 7 without changing any other employee role objects for the project 33. You can use the offset parameter to specify which row object you are editing.

Adding Roles to Employee-Project Roles

Similar to modifying regular grid fields, you can specify the offset parameter in order to create a new row object for each Employee-Project Role grid. This can be done by setting the offset equal to the existing number of rows or to -1 seen below.

PUT Example:

https://{client_domain}.openasset.com/REST/1/Projects/33/Employees

[
  {
    "id": 7,
    "roles": {
      "rows": [
        {
          "end_date": "0",
          "project_role": "test",
          "hours": "",
          "start_date": "20200605000600",
          "role_description": "test1"
        }
      ],
      "limit": 10,
      "total": 1,
      "offset": -1
    }
  }
]

As a warning, the above request will create a new role object for project 33 and employee 7 but it will also overwrite the entire list of employees for project 33 as the PUT requests will completely overwrite existing data with the new object. This can be useful if you are adding multiple roles at a time by ensuring that all previous roles are still present in your json body.

While you can perform this update via PUT requests to the nested noun, it is preferable to perform this with a POST request to the full nested expansion to avoid overwriting existing data seen below.

POST Example:

https://{client_domain}.openasset.com/REST/1/Projects/33/Employees/7

[
  {
    "id": 7,
    "roles": {
      "rows": [
        {
          "end_date": "0",
          "project_role": "test",
          "hours": "",
          "start_date": "20200605000600",
          "role_description": "test description"
        }
      ],
      "limit": 10,
      "total": 1,
      "offset": -1
    }
  }
]

Using offset of -1, we can create a new employee project role for the project 33 and employee 7 role pair.

Deleting Employee-Project Roles

Similar to deleting regular grid field rows, you can perform requests using the offset parameter to target a specific row and send an empty array for the rows in the request body. This can be done on both the nested noun and the full nested expansion.

The example below is NOT a recommended workflow:

PUT Example:

https://{client_domain}.openasset.com/REST/1/Projects/33/Employees

[
  {
    "id": 7,
    "roles": {
      "rows": [
      ],
      "limit": 10,
      "total": 1,
      "offset": 0
    }
  }
]

As a warning, the above request will delete the existing row object for project 33 and employee 7 but it will also overwrite the entire list of employees for project 33 as the PUT requests will completely overwrite existing data with the new object. This would effectively remove the roles for the project 33 and employee 7 as the PUT request would also be missing the data for any pre-existing role objects.

The example below IS the recommended workflow:

POST Example:

https://{client_domain}.openasset.com/REST/1/Projects/33/Employees/7

[
  {
    "id": 7,
    "roles": {
      "rows": [],
      "limit": 10,
      "total": 1,
      "offset": 1
    }
  }
]

Above is the preferred method for deleting a specific employee project role object as you are able to target the exact row to remove without overwriting any other existing roles.

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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Group>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/Groups

To get all groups on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Group>(1);
        }

HTTP Request

GET https://{client_domain}.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);

HTTP Request

PUT https://{client_domain}.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:

Send an array of Objects.
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://{client_domain}.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://{client_domain}.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);

DELETE https://{client_domain}.openasset.com/REST/1/Groups/:id

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

URL Parameters

Parameter	Description
ID	The ID of the group to delete

Groups Nested Nouns

Parameter	Description
users	Returns a list of user ids within the given group

// Example of nested users request
https://{client_prefix}.openasset.com/REST/1/Groups?users=all

[
  {
    "protected": 1,
    "default_for_new_users": 0,
    "hidden": 0,
    "expiry_date": "20370101010101",
    "name": "Administrator",
    "users": [
      {
        "id": 1
      },
      {
        "id": 5
      },
      {
        "id": 9
      },
      {
        "id": 10
      }
    ],
    "id": 1,
    "expires": 0,
    "alive": 1
  }
]

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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Keyword>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/Keywords

To get all keywords on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Keyword>(1);
        }

HTTP Request

GET https://{client_domain}.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);

HTTP Request

PUT https://{client_domain}.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:

Send an array of Objects.
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://{client_domain}.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://{client_domain}.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);

DELETE https://{client_domain}.openasset.com/REST/1/Keywords/:id

DELETE https://{client_domain}.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

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://{client_domain}.openasset.com/REST/1/Keywords/:id

Keywords Noun Expansions

Parameter	Description
files	Returns an array of file ids that have been applied to a given keyword

// Example of expanded files request
https://{client_prefix}.openasset.com/REST/Keywords?files=all

[
  {
    "dead_image_count": 5,
    "updated": "20140213213407",
    "keyword_category_id": 5,
    "unapproved_image_count": 0,
    "name": "Stock",
    "public_image_count": 0,
    "files": [
      {
        "id": 240
      },
      {
        "id": 241
      },
      {
        "id": 242
      },
      {
        "id": 243
      },
      {
        "id": 244
      },
      {
        "id": 1002
      },
      {
        "id": 1003
      },
      {
        "id": 1004
      },
      {
        "id": 1005
      },
      {
        "id": 1007
      },
      {
        "id": 1008
      },
      {
        "id": 1009
      },
      {
        "id": 1010
      },
      {
        "id": 1011
      },
      {
        "id": 1012
      },
      {
        "id": 1013
      },
      {
        "id": 1014
      }
    ],
    "id": 57,
    "private_image_count": 168
  }
]

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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<File>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/KeywordCategories

To get all keyword categories on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<File>(41);
        }

HTTP Request

GET https://{client_domain}.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://{client_domain}.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:

Send an array of Objects.
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://{client_domain}.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://{client_domain}.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);

DELETE https://{client_domain}.openasset.com/REST/1/KeywordCategories/:id

DELETE https://{client_domain}.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

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://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Photographer>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/Photographers

To get all photographers on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Photographer>(1);
        }

HTTP Request

GET https://{client_domain}.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);

HTTP Request

PUT https://{client_domain}.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:

Send an array of Objects.
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://{client_domain}.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://{client_domain}.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);

DELETE https://{client_domain}.openasset.com/REST/1/Photographers/:id

DELETE https://{client_domain}.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

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://{client_domain}.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",
    "created": "20220224140306",
    "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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Project>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/Projects

To get all projects on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Project>(1);
        }

HTTP Request

GET https://{client_domain}.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);

HTTP Request

PUT https://{client_domain}.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:

Send an array of Objects.
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://{client_domain}.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://{client_domain}.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://{client_domain}.openasset.com/REST/1/Projects/:id

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

URL Parameters

Parameter	Description
ID	The ID of the project to delete

Projects Nested Nouns

Parameter	Description
fields	Returns an array of field values for a given project
projectKeywords	Returns an array of project keyword ids that have been applied to a given project
albums	Returns an array of album ids associated with a given project

// Example of expanded fields request
https://{client_prefix}.openasset.com/REST/1/Projects/2?fields=all

[
  {
    "name_alias_1": "",
    "code_alias_1": "",
    "id": 2,
    "updated": "20200715132834",
    "public_image_count": 14,
    "alive": 1,
    "code": "A0015",
    "private_image_count": 1,
    "unapproved_image_count": 0,
    "name": "London Bridges Olympic Lighting",
    "fields": [
      {
        "values": [
          ""
        ],
        "id": 16
      },
      {
        "values": [
          "Illuminating London's bridges for the 2012 London Olympic and Paralympic Games.\r\n\r\nThe new lighting scheme was specifically developed to enhance the aesthetics of London bridges and ensure an energy efficient lighting scheme was in place. More than 12 km architectural LED lighting has been installed on London bridges, Controls were also installed enabling the mood of the lighting to be changed to suit different occasions"
        ],
        "id": 5
      },
      {
        "values": [
          "LCOG"
        ],
        "id": 1
      },
      {
        "id": 42,
        "values": [
          ""
        ]
      },
      {
        "values": [
          "20120202000000"
        ],
        "id": 3
      }
    ],
    "deleted": 0,
    "created": "0",
    "code_alias_2": "",
    "name_alias_2": "",
    "dead_image_count": 14
  }
]

// Example of expanded projectKeywords request
https://{client_prefix}.openasset.com/REST/1/Projects?projectKeywords=all

[
  {
    "code_alias_2": "",
    "name_alias_2": "",
    "dead_image_count": 14,
    "name_alias_1": "",
    "projectKeywords": [
      {
        "id": 44
      },
      {
        "id": 68
      },
      {
        "id": 76
      },
      {
        "id": 79
      },
      {
        "id": 82
      },
      {
        "id": 87
      },
      {
        "id": 92
      },
      {
        "id": 116
      },
      {
        "id": 123
      },
      {
        "id": 176
      }
    ],
    "code_alias_1": "",
    "updated": "20200715132834",
    "id": 2,
    "alive": 1,
    "public_image_count": 14,
    "private_image_count": 1,
    "code": "A0015",
    "name": "London Bridges Olympic Lighting",
    "unapproved_image_count": 0,
    "created": "0"
  }
]

// Example of expanded albums request
https://{client_prefix}.openasset.com/REST/1/Projects?albums=all

[
  {
    "name_alias_2": "",
    "albums": [
      {
        "id": 125
      },
      {
        "id": 126
      }
    ],
    "code_alias_2": "",
    "dead_image_count": 12,
    "code_alias_1": "",
    "id": 4,
    "updated": "20181221101857",
    "name_alias_1": "",
    "unapproved_image_count": 2,
    "name": "The Charlotte Building",
    "deleted": 0,
    "created": "0",
    "public_image_count": 8,
    "alive": 1,
    "code": "A0061",
    "private_image_count": 4
  }
]

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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<ProjectKeyword>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/ProjectKeywords

To get all projectkeywords on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<ProjectKeyword>(41);
        }

HTTP Request

GET https://{client_domain}.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);

HTTP Request

PUT https://{client_domain}.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:

Send an array of Objects.
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://{client_domain}.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://{client_domain}.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);

DELETE https://{client_domain}.openasset.com/REST/1/ProjectKeywords/:id

DELETE https://{client_domain}.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

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://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<ProjectKeywordCategory>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/ProjectKeywordCategories

To get all ProjectKeywordCategories on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<ProjectKeywordCategory>(41);
        }

HTTP Request

GET https://{client_domain}.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);

HTTP Request

PUT https://{client_domain}.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:

Send an array of Objects.
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://{client_domain}.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://{client_domain}.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);

DELETE https://{client_domain}.openasset.com/REST/1/ProjectKeywordCategories/:id

DELETE https://{client_domain}.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

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://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Search>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/Searches

To get all searches on the instance:

GET https://{client_domain}.openasset.com/REST/1/Searches?limit=0

Get a Specific Search

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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Search>(41);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/Searches/:id

URL Parameters

Parameter	Description
ID	The ID of the Search to retrieve

Update a Specific Search

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);

HTTP Request

PUT https://{client_domain}.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:

Send an array of Objects.
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://{client_domain}.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.

Create a new Search

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://{client_domain}.openasset.com/REST/1/Searches/

Delete a Specific Search

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);

DELETE https://{client_domain}.openasset.com/REST/1/Searches/:id

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

URL Parameters

Parameter	Description
ID	The ID of the Search to delete

Searches Noun Expansions

Parameter	Description
groups	Returns an array that includes group ids in which the parent searches are shared with as well as associated modify permissions to the Searches selected.
users	Returns an array of user ids in which the parent searches are shared with as well as associated modify permissions to the searches selected.

// Example of expanded groups request
https://{client_prefix}.openasset.com/REST/1/Searches/356?groups=all

{
  "share_with_all_users": 0,
  "id": 356,
  "created": "20160218171210",
  "name": "Furniture",
  "user_id": 3,
  "search_items": [
    {
      "ids": [
        "1"
      ],
      "exclude": 0,
      "code": "category"
    },
    {
      "code": "keyword.1",
      "exclude": 0,
      "ids": [
        "63"
      ]
    }
  ],
  "groups": [
    {
      "can_modify": 0,
      "id": 6
    }
  ],
  "updated": "20160218171411",
  "saved": 1,
  "code": "c267600f0b59c1cd31f22e98628e251b",
  "all_users_can_modify": 0,
  "can_modify": 1,
  "locked": 0,
  "approved_company_saved_search": 0,
  "company_saved_search": 0
}

// Example of expanded users request
https://{client_prefix}.openasset.com/REST/1/Searches?users=all

[
  {
    "created": "20150427145610",
    "locked": 0,
    "saved": 1,
    "search_items": [
      {
        "code": "user",
        "exclude": 0,
        "ids": [
          "26"
        ]
      },
      {
        "values": [
          "=0"
        ],
        "code": "keywordCount",
        "exclude": 0
      }
    ],
    "can_modify": 1,
    "id": 1632,
    "users": [
      {
        "can_modify": 1,
        "id": 26
      }
    ],
    "name": "Seach assigned for a user to update",
    "user_id": 3,
    "code": "170839be4d8652d0c16299867d62e656",
    "company_saved_search": 0,
    "updated": "0",
    "share_with_all_users": 0,
    "all_users_can_modify": 0,
    "approved_company_saved_search": 0
  }
]

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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Size>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/Sizes

To get all sizes on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<Size>(41);
        }

HTTP Request

GET https://{client_domain}.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);

HTTP Request

PUT https://{client_domain}.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:

Send an array of Objects.
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://{client_domain}.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://{client_domain}.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);

DELETE https://{client_domain}.openasset.com/REST/1/Sizes/:id

DELETE https://{client_domain}.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://{client_domain}.openasset.com", 
                "username", 
                "password"
            );
            return conn.GetObjects<TextRewrite>(options);
        }

HTTP Request

GET https://{client_domain}.openasset.com/REST/1/TextRewrites

To get all text rewrites on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com", 
                "username", 
                "password"
            );
            return conn.GetObjects<TextRewrite>(41);
        }

HTTP Request

GET https://{client_domain}.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://{client_domain}.openasset.com/REST/1/Topics

To get all topics on the instance:

GET https://{client_domain}.openasset.com/REST/1/Topics?limit=0

Get a Specific Topic

This endpoint retrieves a specific Topic.

HTTP Request

GET https://{client_domain}.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://{client_domain}.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://{client_domain}.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://{client_domain}.openasset.com/REST/1/Topics/

Delete a Specific Topic

This endpoint allows DELETES of Topics.

HTTP Request

DELETE https://{client_domain}.openasset.com/REST/1/Topics/:id

DELETE https://{client_domain}.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

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://{client_domain}.openasset.com/REST/1/Topics/:id

Topics Noun Expansions

Parameter	Description
albums	Returns a nested array of album ids associated with a given topic

// Example expanded albums request
https://{client_prefix}.openasset.com/REST/1/Topics/12?albums=all

[
  {
    "protected": 0,
    "updated": "20190104161930",
    "name": "Test Topic",
    "id": 12,
    "display_order": 3,
    "albums": [
      {
        "id": 292
      },
      {
        "id": 293
      },
      {
        "id": 299
      },
      {
        "id": 300
      },
      {
        "id": 423
      },
      {
        "id": 424
      },
      {
        "id": 425
      }
    ],
    "code": "TESTCODE"
  }
]

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,
    "invited": 0,
    "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.
invited	boolean	Whether this user was invited by an administrator (1) or not (0).
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://{client_domain}.openasset.com/REST/1/Users

To get all users on the instance:

GET https://{client_domain}.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://{client_domain}.openasset.com",
                "username",
                "password"
            );
            return conn.GetObjects<User>(41);
        }

HTTP Request

GET https://{client_domain}.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);

HTTP Request

PUT https://{client_domain}.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:

Send an array of Objects.
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://{client_domain}.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://{client_domain}.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);

DELETE https://{client_domain}.openasset.com/REST/1/Users/:id

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

URL Parameters

Parameter	Description
ID	The ID of the user to delete

Users Noun Expansions

Parameter	Description
groups	Returns an array of groups that the users are in

// Example of nested groups request
https://{client_prefix}.openasset.com/REST/1/Users/1?groups=all

[
  {
    "expires": 0,
    "current_album_id": 0,
    "valid": 1,
    "sso_provider_id": 0,
    "expiry_date": "20370101010101",
    "hidden": 0,
    "email": "",
    "groups": [
      {
        "id": 1
      },
      {
        "id": 6
      }
    ],
    "full_name": "Administrator",
    "alive": 0,
    "username": "administrator",
    "id": 1,
    "protected": 1
  },
]

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.
422	Unprocessable Entity -- The request is well formed but cannot be processed at this time.
500	Internal Server Error -- If this repeatedly occurs - contact OpenAsset Support

Introduction

Authentication

Token Authentication

Best Practices

HTTP Verbs

Data Types

Parameters

Filtering

Basic Filters

Numeric and Date Operators

Text Matching

URL Arrays and Objects

Arrays

Objects

Filtering on Custom Fields

Field Types

Advanced Filters

Limit & Offsets

Limit & Offset Best Practices

Headers

Albums

Query Parameters: Albums

Get All Albums

HTTP Request

Get a Specific Album

HTTP Request

URL Parameters

Update a Specific Album

HTTP Request

Attributes that can be updated

Updating Multiple Albums

HTTP Request

Create a new Album

HTTP Request

Delete a Specific Album

HTTP Request

URL Parameters

Merge Albums

HTTP Request

Album Noun Expansions

AspectRatios

Query Parameters: AspectRatios

Get All AspectRatios

HTTP Request

Get a Specific AspectRatio

HTTP Request

URL Parameters

Categories

Query Parameters: Categories

Get All Categories

HTTP Request

Get a Specific Category

HTTP Request

URL Parameters

Update a Specific Category

HTTP Request

Attributes that can be updated

Updating Multiple Categories

HTTP Request

CopyrightHolders

Query Parameters: CopyrightHolders

Get All CopyrightHolders

HTTP Request

Get a Specific CopyrightHolders

HTTP Request

URL Parameters

Update a Specific CopyrightHolder

HTTP Request

Attributes that can be updated

Updating Multiple CopyrightHolders

HTTP Request

Create a new CopyrightHolder

HTTP Request

Merge CopyrightHolders

HTTP Request

CopyrightPolicies

Query Parameters: CopyrightPolicies

Get All CopyrightPolicies

HTTP Request

Get a Specific CopyrightPolicies