You can use Orange Logic's Search API to quickly find the assets you need. This search is extremely flexible. It returns a list of assets that meet the criteria included in your API call, along with specific information you request about those assets. You can search for text contained in all searchable metadata fields, by text in a specific field, by asset type, by Tag, and more. You can also choose the sort order of your results, adjust the number of assets returned at a time, and choose whether results are returned in XML or JSON format.
The Search API includes one main Search endpoint you’ll use to search for assets and return the information you need about each of those assets.
The Search API also includes two supporting endpoints you can use to get a list of the search criteria and searchable fields you can use with the Search API in your Orange Logic platform. For example, let’s say the DAM administrators at Mangovations have created a number of searchable metadata fields. You can use the List Criteria and List Fields APIs to get a list of all searchable fields and their search criteria.
Security Functions and Permissions
You must have the Access to the Search APISecurity Function to use the Search API. For assets to appear in your search results, you must have Find and View Permissions on them. Orange Logic only returns the assets you have the Permissions and Security Functions to access.
Additional Security Functions
The following Security Functions are not required, but they grant users additional search functionality.
ℹ️
Note
You cannot use any of these Security Functions to override Permissions. API users can only return the assets they have permission to access.
Return hidden assets
By default, the Search API only returns assets that would appear in an equivalent search in the Orange Logic interface. For example, in the Orange Logic interface, only a Stack's lead asset appears in a search, while alternative assets in the Stack are hidden by default. Therefore, the Search API does not return alternative assets by default.
🎓
Insight: Stacks
When multiple assets are similar to each other, you can “stack” them so that you can keep them together. For example, if you upload a JPG, PNG, and TIF of the same image, you can stack these assets so that you can easily find and edit that group of assets all at once. A group of stacked assets is called a “Stack.”
When you stack assets, you pick which asset you want to represent the other assets. This becomes the “Lead Asset," which is shown as the “top” asset of the Stack. The other assets in the Stack are “Alternative Versions” of the Lead Asset.
Stacked assets are marked with an icon of two overlapping squares in the top left corner of their thumbnails:
Lead Asset: Yellow icon
Alternative Version: Gray icon
Stacked assets
When users view assets, they only see the “top” asset by default. Users can choose whether or not they want to view or download just the lead asset or all of the assets in a Stack.
To return all assets, including hidden assets such as the alternative versions of an asset in a Stack, you must have the Search API - Allow search on all documents Security Function. When a user with this Security Function runs a search, Alternative assets appear in the list of results.
The API response also contains additional information, which is detailed on the Search API page.
Search for Deleted Assets
Users with the Search for deleted assets Security Function can include soft-deleted assets in the search results with the includebinned parameter in the Search API .
🎓
Insight: Deleted assets
When you upload assets to the Orange Logic platform, the files and proxies for those assets are stored in one or more cloud storage buckets (such as an Amazon S3 or Microsoft Azure Blob Storage bucket). Additionally, Orange Logic creates a record of each asset that includes the asset’s metadata and thumbnail.
Asset record
When you soft-delete an asset, that asset’s record is removed from Orange Logic but its files remain in storage. Soft-deleted assets can be restored within a timeframe set by your organization (often 30 days).
In contrast, when you permanently delete an asset, its files are also removed from storage and the file cannot be restored. Permanently deleting an asset requires admin approval.
Users with the Can Expose Bucket Search API Security Function can include storage information in the search results with the includestorageinfo parameter in the Search API .
