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 either the Authentication header like Authentication: token mytoken (since 2.8.12) or the Authorization header (since 2.9.5)
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
123,searchterm searches for the term "searchterm" in the infofield 123123,42 searches for the number "42" in the infofield 123123,42,1337 searches for numbers between 42 and 1337 in the infofield 123123,2 searches for dropdown item #2 in the infofield 123123,false searches for "false" values in the infofield 123123,456,789 searches for nodes 456 or 789 in the infofield 123123,1970-01-01 _searches for the first of January 1970 in the infofield 123yyyy-MM-dd, dd.MM.yyyy or MM/dd/yyyy123,2019-01-01,2019-12-31 _searches for any day in 2019 in the infofield 123123,null,2019-12-31An information field query provides the possible values and properties where applicable (dropdowns, boolean, nodereference)
facet_fields=info_123,info_456,fileExtensionssearch_file_category=2,5 . Note that this will override the search_<type> parameters such as search_image. Since 2.9.21.Example:
[GET] server.com/anura/node.do?search_folder=4&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
Example:
[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", ...][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).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"}, ...]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
}