Anura always responds in JSON using UTF-8 (application/javascript; charset=UTF-8), except for thumbnails (image/jpeg) and downloads (application/zip).
JSONP is supported through the callback parameter.
Non-JSON responses usually indicate that a fatal error has occurred outside of Anura's control. Check celum's ims.log/appserver.log in such cases for more information.
Based on the name of the dispatcher (usually anura) there are two services:
Results are always cached on the server side for a configurable amount of time (default: 1h). Use the flush parameter to force a refresh.
The responses have also been designed to behave well when using an additional caching reverse proxy or load balancer in front of the API and will always send the appropriate Cache-Control, Content-Type and Content-Disposition headers.
Parameters you should ignore include callback, and depending on your use case also token. Furthermore you may want to listen to the cache control parameters flush (invalidates the cache) and cache (circumvents the cache for this request).
The API is public by default (and by design), so no authentication is needed. It it however possible to require authentication (see tokenVerifier), in which case you MUST pass a token either via the parameter token (...&token=mytoken) or preferably through the Authorization header (since 2.9.5), e.g. Authorization: Bearer <your-token>.
Note that the foo[]-notation for GET parameters is not supported by the server, use foo=1&foo=2 instead.
Required parameters are marked in bold
Version 2 was developed for CELUM 5 - while it tries to be as compatible as possible, not all features are available on both platforms. The most notable change in version 2 is that every response is delivered in an envelope, e.g.
{
"version": 2,
"status": 200,
"data": {/* result, same as in 1.x */}
}This means that you always get an answer, even if something went wrong. The status code (which can't be obtained with JSONP otherwise) is also provided and set to 200 in the HTTP response when the callback parameter is set (otherwise nothing will arrive in your callback function). Additionally, the API version is specified and an optional message-parameter may be present when an error has occurred.
Example:
[GET] server.com/node.do?tree=4123&kind=103&depth=2
[{
"id": 2620,
"type": 103,
"name": "Color",
"children":[
{"id": 2791, "type": 103, "name": "Greyscale"},
{"id": 2792, "type": 103, "name": "RGB"},
{"id": 2793, "type": 103, "name": "CMYK"}
]
}]Note: You can construct virtual root nodes by specifying multiple tree parameters from which that node should be constructed, i.e. tree=4123&tree=1337&tree=42
Example:
[GET] server.com/anura/node.do?kind=101&id=7&alt_name=2
[
{"id": 1337,"type": 1, "name": "pic_12_001.jpg", "alt_name": "This is an example"},
{"id": 1338,"type": 2, "name": "api_demo.odt", "alt_name": "Demonstration of the API"}
]Note: type is 1=image, 2=document, 3=video, 4=audio, 5=text, 0=unknown
search (string) - full text search, e.g. "ponies"
search_extensions (string[]) - search by file extension, e.g. search_extensions=png,eps
search_uploaded_after (string) - restrict results to assets uploaded after this date
search_uploaded_before (string) - restrict results to assets uploaded before this date
search_modified_after (string) - restrict results to assets modified after this date
search_modified_before (string) - restrict results to assets modified before this date
search_limit (int) - limit the number of search results (limited by the server's maxSearchResults)
search_infofield (int,mixed...[]) - search by information field value, syntax:
text: 123,searchterm searches for the term "searchterm" in the infofield 123
number: 123,42 searches for the number "42" in the infofield 123
number range: 123,42,1337 searches for numbers between 42 and 1337 in the infofield 123
dropdown: 123,2 searches for dropdown item #2 in the infofield 123
boolean: 123,false searches for "false" values in the infofield 123
noderefs: 123,456,789 searches for nodes 456 or 789 in the infofield 123
date: 123,1970-01-01 _searches for the first of January 1970 in the infofield 123
various date formats are auto-detected, such as yyyy-MM-dd, dd.MM.yyyy or MM/dd/yyyy
jchronic-expressions such as "yesterday" are also supported
date range: 123,2019-01-01,2019-12-31 _searches for any day in 2019 in the infofield 123
open ranges can be defined using the term "null", e.g. anything before 2020 123,null,2019-12-31
An information field query provides the possible values and properties where applicable (dropdowns, boolean, nodereference)
search_or_mode (boolean) - connect different search terms with OR (the default is AND)
search_text_or_mode (boolean) - connect fulltext search terms with OR (default, since 2.9.15)
search_asset_type (list of long) - asset type IDs (e.g. 3000,4000)
search_node (list of long) - node IDs to restrict the search to, e.g. search_node=123&search_node=987 or search_node=123,987
search_node_recursive (boolean) - search in subnodes as well, default is true
search_node_or_mode (boolean) - ORs the searched nodes (independent of search_or_mode), default is false
search_node_type (list of long) - node type IDs (e.g. 105,106), (since 2.7)
search_id (list of long) - search particular assets via their ID (since 2.6)
search_facets (int) - return facets (if a facet-provider is installed), 0 = disabled (default), 1 = only facets, 2 = facets and assets, since 2.6
search_custom (string) - a custom string that gets parsed by a CustomSearchProvider, since 2.7
search_file_category (list of int) - search for certain file categories (1 = image, 2 = document, 3 = video, 4 = audio, 5 = text, 6 = 3D, 0 = unknown), e.g. search_file_category=2,5 . Note that this will override the search_<type> parameters such as search_image. Since 2.9.21.
search_folder (int) - celum ID of the folder to restrict the search to, DEPRECATED in 2.x -> use search_node
search_keyword (int[]) - celum ID of the keyword to restrict the search to, multiple keywords (AND search) may be specified using search_keyword=1&search_keyword=2, DEPRECATED in 2.x -> use search_node
search_ (boolean) - default is true - DEPRECATED -> use search_file_category
also see result controls for additional parameters
Example:
[GET] server.com/anura/node.do?search_node=42&search=ponies
[
{"id": 42, "type": 1, "name": "ponies_on_a_farm.jpg"},
{"id": 1337, "type": 2,"name": "My favorite ponies.xls"}
]These parameters are applicable to node content and search queries
sort_order=name,date&sort_order_seq=desc,ascasc (default) or descending desc, since 2.2Example:
[GET] server.com/anura/node.do?top=15&days=7
[
{"id": 1337, "type": 1, "name": "pic_12_001.jpg", "alt_name": "This is an example", "downloads": 9001},
{"id":1338, "type": 2, "name": "api_demo.odt", "alt_name": "Demonstration of the API", "downloads": 1234}
]Query the related assets of a particular asset (since: 2.9.8)
[GET] server.com/anura/node.do?relations=42
[
{"id": 1337, "type": 1, "name": "related.jpg", ...},
{"id":1338, "type": 2, "name": "also_related.odt", ...}
]Suggest node names based on a partial string (since: 2.9.24)
[GET] server.com/anura/node.do?suggest=sco
["Scorpions", "Scoliosis", "Scooby-Doo", ...]Retrieve metadata about a single asset, but in the format that a search query would yield (since: 2.10), where you'd normally use asset.do?details=. Implicitly supports result controls as far as applicable.
[GET] server.com/anura/node.do?asset=42
{"id": 42, "type": 1, "name": "cows_on_a_farm.jpg", infofields: []}[GET] your.server.com/anura/node.do?about=true
{
"apiVersion": 2.0,
"cacheTimeSeconds": 3600,
"celumVersion": "5.10.3",
"containerLanguages": ["en", "de", "fr"],
"customFieldLanguages": ["en", "de", "fr"],
"defaultLanguage": "en",
"guiLanguages": ["en", "de", "fr"],
"infoField": [{"id":148},{"id":102}],
"nodeTypes": [
{"id": "101", "name": "Folders", "value": "folder", "type": "permission_defining"},
{"id": "103", "name": "Keywords", "value": "keyword", "type": "non_permission_defining"}
],
"supportEmail": "support@brix.ch",
"userId": 2
}Note: depending on your version, not all fields may be present - this tends to grow over time.
There are two kinds of previews available (Content-Disposition=inline, Content-Type=image/jpeg). How big those are may be configured, default is: thumb 256x256px, preview 1024x1024px (maximum)
thumb or preview (int) - celum ID of the asset you want a thumb/preview of.
X-Pages with the number of pages that are known to exist.preview, alternative media formats may be available for non-images, since 2.9: pdf for documents a PDF file is available (internally "prvwsrc") for use in a PDF viewer, video or audio essentially the same as calling play or stream (see below), or 3D for whitelisted 3D formats, returns the original 3D file for preview (e.g. model-viewer.dev).play or stream (int) - celum ID of the video asset to be played back, play will use celum's player and stream will return the raw file
Example: [GET] your.server.com/anura/asset.do?thumb=1337&img=a.jpg
Note: The &img=a.jpg part does absolutely nothing but has been added because some browsers might like to have a file extension at the end
First of all you'll need to get a list of the available download formats (should be done once on application launch):
[GET] your.server.com/anura/asset.do?downloadformats=1
[
{"name":"Originalformat","icon":"../img/icons/32x32/originalImageTargetFormat.gif","id":6, "position":1},
{"name":"Web Format","icon":"../img/icons/32x32/webImageTargetFormat.gif","id":5, "position":2}
]Notes:
-1 instead (since 2.9.18). For specific assets, always use downloadformats_for if you can, as download format access is subject to permissions.As of version 2.0 you can also query the available download formats by file extension(s), e.g.:
[GET] your.server.com/anura/asset.do?downloadformats=jpg (DEPRECATED, use downloadformats_for if possible)
[
{"id": 1, "name": "Original file", "description": "Download original file", "icon": "../../images/download-formats/dark/big/orig.png"},
{"id": 2, "name": "Web JPG", "description": "JPG 1024x1024", "icon": "../../images/download-formats/dark/big/web.png"}
]Multiple extensions are supported as well (intersection):
[GET] your.server.com/anura/asset.do?downloadformats=jpg,mp4 (DEPRECATED, use downloadformats_for if possible)
[{"id": 1, "name": "Original file", "description": "Download original file", "icon": "../../images/download-formats/dark/big/orig.png"}]As of version 2.2, you can query the available download formats for an asset:
[GET] your.server.com/anura/asset.do?downloadformats_for=1337&locale=en
{"name": "0100181.psd", "extension": "psd", "type": 1, "formats": [
{"id": 1, "name": "Original file", "description": "Download original file", "icon": "../../images/download-formats/dark/big/orig.png"},
{"id": 2, "name": "Web JPG", "description": "Download JPG optimized for web", "icon": "../../images/download-formats/dark/big/web.png" }
]}As of version 2.6, you'll get some additional infos about enabled DownloadFormatInterceptors (see CMA)
[GET] your.server.com/anura/asset.do?downloadformats_for=1337
[{"id": 8, "name": "User Definable", "description": "Allows the user to choose the size", "icon": "../../images/download-formats/dark/big/orig.png", "resizeable": true, "editable": false, "message": false}]As of version 2.7, you can also request infofields alongside the download infos, just as you would with asset and container requests:
[GET] your.server.com/anura/asset.do?downloadformats_for=1337&locale=en&infofields=148,137
{"name": "0100181.psd", "extension": "psd", "type": 1, "formats": [/*... snip ...*/],
"infofields": {"148": "Example", "137": "Jan 1, 2020"},
"infofields_raw": {"148": {"en": "Example", "de": "Beispiel"}, "137": 1577833200000}}Sidenote: The reason there are two info-maps here is to maintain backwards compatibility, as "raw" was introduced later
As of version 2.8, you can also ask for multiple assets at once to get a map of id -> download-info:
[GET] your.server.com/anura/asset.do?downloadformats_for=42,1337&locale=en
{
"42": {"name": "0100181.psd", "extension": "psd", "type": 1, "formats": [/*... snip ...*/]},
"1337": {"name": "some.jpg", "extension": "jpg", "type": 1, "formats": [/*... snip ...*/]}
}As of version 2.9, you can also ask for asset versions in this request:
[GET] your.server.com/anura/asset.do?downloadformats_for=42,1337&locale=en&versions=true
{"name": "flag_of_the_earth.png", "extension": "png", "type": 1, "formats": [/*... snip ...*/],
"versions": [
{"version": 1, "name": "flag_of_the_earth_fixed.png", "date": "May 2, 2016, 3:52:37 PM", "date_raw": 1462197157361, "active": true}
{"version": 0, "name": "flag_of_the_earth.png", "date": "May 2, 2016, 7:58:45 AM", "date_raw": 1462175925468, "active": false}
]
}As of version 2.9.19 you can also ask for an alternative name (same as in node requests)
[GET] your.server.com/anura/asset.do?downloadformats_for=42,1337&alt_name=105
Knowing the download format IDs, you can then trigger a download:
You can download multiple files at once in a ZIP by specifying more than one download, e.g. download=42,1337,7 (the old notation "download=1&download=2" is still supported)
Example: [GET] your.server.com/anura/asset.do?download=42&format=6
This will stream the file directly to the browser with Content-Disposition=attachment.
As of version 2.0, you can specify download formats per asset (colon-separated, overrides the format parameter) with download=download=1337:6 or download=42:1,1337:6,7:1
As of version 2.6, you can add additional download format options (if a DownloadFormatInterceptor is present), e.g. download=1337:8:width=100;height=100;unit=px
Known parameters:
<width>x<height>{+-}<xoffset>{+-}<yoffset>, e.g. crop=1280×720+50+50 crops to a 1280x720px area with an offset of 50px from the top and left. (since 2.9)
+ as %2B\d+(\.\d+)?%?x\d+(\.\d+)?%?([+-]\d+){0,2}Example:
[GET] your.server/anura/asset.do?details=1337&locale=en
{
"name":"gnampf.jpg",
"general_title":"Object Details",
"general":{
"Creation date": "Jul 18, 2013 2:51:56 PM",
"File size": "205 KB",
"File extension":"jpg",
"Size": "1049 x 697 Pixels",
"DPI": "72",
"Graphic type": "Raster",
"ICC-Profile":"Adobe RGB (1998)"
},
"infofields_title":"Information Fields",
"infofields":[
{"id": "info_108", "name": "Copyright Required", "value": "No", "type": "Boolean"},
{"id": "info_121", "name": "Copyright Information", "value": "Some copyright text", "type": "TextArea"},
],
"keywords_title":"Keywords",
"keywords":{
"RGB":"/Color/",
"Basel":"/Location/Europe/Switzerland/"
}[GET] your.server/anura/asset.do?details=1337&locale=en&details_keyword_paths=true&details_keyword_list=true&links=true
{
/* ...snip... */
"keyword_paths": [
"/Color/RGB",
"/Location/Europe/Switzerland/Basel"
],
"keyword_list": [
{id: "123", name: "RGB", path: "/Color"},
{id: "456", name: "Basel", path: "/Location/Europe/Switzerland"}
],
"links":[
{id: 55456, type: 2, name: "license_agreement.pdf"}
]
}As of 2.1 the response will also contain the available download formats in the download fields (same as if you'd request downloadformats=
{
/* ...snip... */
"infofields": [
{
"id": "info_125",
"name": "Type of Document",
"type": "NodeReference",
"value": "First value, Second value",
"values": [
{"id": "noderef_2702", "name": "First value", "value": "2702", "type": "103", "info": "/Path/To/Value"}
{"id": "noderef_4702", "name": "Second value", "value": "4702", "type": "103", "info": "/Path/To/Value"}
]
}
],
"downloads": [
{"id": 1,"name": "Original file", "description": "Download original file", "icon": "../../images/download-formats/dark/big/orig.png"},
{/* snip */}
]
}you can override the name of informationfields if you don't like what informationfields.xml provides by specifying
anura.infofield.name.<infofield-id>=...in your message bundle. Same goes foranura.infofield.readerinfo.<infofield-id>=....
Get introspection details about the nature of an information field
Note: type is 0 = text, 1 = number, 2 = date, 3 = node reference (since 2.0), 4 = checkbox, 5 = dropdown
Example:
[GET] server.com/anura/asset.do?infofield=7
{"name": "Image source", "description": "Where you got it from", "type": 0}Dropdown fields also declare the possible values:
{..., "values":[{"name": "Fotolia", "id": 4},{"name": "Getty Images", "id": 5},{"name": "DigitalVision", "id": 6}]}Node referencing fields declare additional settings:
{..., "root_node": 1100, "show_root": false, max_selections": -1]}Get information about the configured asset types
Example:
[GET] server.com/anura/asset.do?assettype=true
[{"id":"1000","name":"Product Picture","value":"Product_Image"},{"id":"2000","name":"Product Video","value":"Product_Video"}, ...]Get information about the available file categories, since 2.9.21
Example:
[GET] server.com/anura/asset.do?file_categories=true
[{"id":"1","name":"Bild","value":"IMAGE"},{"id":"2","name":"Dokument","value":"DOCUMENT"},{"id":"3","name":"Video","value":"VIDEO"},{"id":"4","name":"Audio","value":"AUDIO"},...]Provides introspection for the general section of details - similar to what infofield=-1 does for infofields.
Example:
[GET] server.com/anura/asset.do?properties=true
[{"id": "name", "name": "Name", "type": "string"}, {"id": "original_name", "name": "File Name", "type": "string"}, ...]Downloads all related assets as a ZIP file (along with the asset itself) in the original , e.g. to get all assets placed in an InDesign file.
-1 to get a list of all available relation types (since 2.9.6)[GET] server.com/anura/asset.do?relations=1337
Access any translated string available in celum
Example:
[GET] server.com/anura/asset.do?string=detailview.title&string=detailview.infobox.noinfo
{"detailview.title":"Object Details","detailview.infobox.noinfo":"No information available"}Here's a list of translation keys that are known to be used by anura.
You can access labels in languages that are not used in CELUM, provided there's a corresponding
appserver/lang/customMessages_xy.properties. This however does not apply to information field names that have their labels defined outside of theinformationfields.xml- in that case the locale must be present in theguiLanguagesfor CELUM to load them (?)
Allows the creation of PINs. Note that anura.1.createPinParentNodeId must be configured. since 2.9
Because of a bug in the PIN view, the URL is not copyable (or to be more precise, it only works once, because showpin.do changes to pinaccess.do, which in turn creates a scoped session). You may want to add
history.replaceState(null, null, 'showpin.do'+location.search);as a custom JS to your PIN page to fix this.
Example:
[GET] server.com/anura/pin.do?create=42,1337&title=Example
{"pin":"dC2n8QysqXIn","link":"https://server.com/pinaccess/showpin.do?pinCode=dC2n8QysqXIn","title":"Example"}Get all reviews of a given asset ID.
Example:
[GET] server.com/anura/review.do?&get=321
{
"averageRating": 4.0,
"reviewList": [
{
"reviewId": "0e3f0e3f-e3d0-4f1f-b767-0037db907b17",
"createDate": "Jun 10, 2021 12:07:44 PM",
"creator": {
"userId": 234,
"userName": "anura",
"avatar": "AN"
},
"rating": 5,
"comment": "Very nice picture!",
"editable": true
},
{
"reviewId": "52d0bb37-1b37-42f7-954f-127eef96c167",
"createDate": "Jun 10, 2021 12:08:05 PM",
"lastModifiedDate": "Jun 10, 2021 12:11:19 PM",
"creator": {
"userId": 9,
"userName": "admin",
"avatar": "AD"
},
"rating": 3,
"comment": "Picture is ok!",
"editable": true
}
]
}Create a new review for a given asset ID
[GET] server.com/anura/review.do?&post=326&comment=Very%20nice%20picture!&rating=5
{
"anuraReview": {
"reviewId": "0e3f0e3f-e3d0-4f1f-b767-0037db907b17",
"createDate": "Jun 10, 2021 12:07:44 PM",
"creator": {
"userId": 234,
"userName": "anura",
"avatar": "AN"
},
"rating": 5,
"comment": "Very nice picture!",
"editable": true
},
"averageRating": 5.0
}