Where can I get an API access token?
You can get access tokens for the API from Admin app of the Widen Collective site > API Setup under Global Settings in the left navigation.
How are API calls permissioned?
Every API call must be accompanied by a bearer token in the authorization header (the access token). These tokens are associated with a specific account in the Collective.
The assets you will have access to via the API are determined by the roles and permissions of your Collective account.
How do I search for specific assets via the API?
Searching for assets via the REST API is done with the Asset Search endpoint using this quick search string:
Any search that can be done through the Collective can also be done as a search through the REST API. The same quick search syntax is used in both places. This article explains this quick search syntax in more detail.
One easy way to get a quick search string is to use the advanced search in the Collective to craft the exact search you want. After running the search, the quick search bar will have your advanced search translated to quick search syntax.
For example, to search for all assets with "event" in the filename that are new or modified since 07/01/2016, the quick search string is:
fn:event lhd:[after 07/01/2016]
This quick search string can be URL encoded and supplied as the “quick-search-string” url query parameter.
How do I query for assets that have recently changed?
To return all assets that have been edited since a specific date (e.g., July 1, 2016), use this quick search:
To return all assets that have been edited since a specific time (e.g., July 1, 2017, at midnight, CT), use this quick search:
To return all assets that have been uploaded between two times (e.g., from July 1, 2017, at midnight, CT, to July 1, 2017, at 1:00 a.m., CT), use this quick search:
DateAdded:[2017-07-01T05:00:00Z to 2017-07-01T06:00:00Z]
All timestamps must be represented as ISO8601 format in GMT time.
To get all assets that have been edited within the past week (seven days), use this quick search:
If you want to see all assets that have been uploaded into the Collective in the past two days, use this quick search:
These quick search strings can then be URL encoded and passed into the Asset Search endpoint as a query parameter.
Can I search by upload or last edit time as well as date?
No. Date searches within both the API and the Collective are granular to the day, not to a specific timestamp.
Does the API cache responses?
No. Every API query will make a new call to either the elastic search index or directly to the database as needed.
Is there a limit to the number of API calls that can be made over a given time period?
Yes. We enforce a rate limit of 10 calls per second to the API. Exceeding this rate results in "429 too many requests" error responses.
There are no additional per-hour or per-day limits. This 10-calls-per-second rate is the only limitation to your API access.
This rate limit only applies to calls directly to the API (api.widencollective.com). Calls to "download links" that use our high availability CDN (embed.widencdn.net) are not subject to any limits, even if these links are served up through the API.
If your app is regularly hitting the limit of 10 calls per second, please contact your customer success manager or firstname.lastname@example.org to discuss your use case.