The prometheus image archive API, v1
Perform searches, retrieve images, and query collections.
Request URLs have the following format:
https://prometheus.uni-koeln.de/pandora/api/v1/:format/:path
version
(optional)- The API version (defaults to
v1
). format
(required)- One of the response formats listed with each method.
path
(required)- The path of the method as outlined below.
Global parameters
Parameters available to all methods.
Authorization
[HEADER]
Some API calls require authorization. Supported schemes are Basic and OAuth.
locale
[QUERY]
- Type
- String
- Options
- de, en
- Default
- en
Additional query parameters may be appended as usual. Header parameters need to be sent with the request headers.
Examples
List records from your database (see GET /upload/list
) and authorize with HTTP Basic authentication authorization header:
curl --request GET -v https://prometheus.uni-koeln.de/pandora/api/xml/upload/list --header 'Authorization: Basic YXBpOmV4YW1wbGU='
List records from your database (see GET /upload/list
) and authorize with OAuth authorization header:
curl --request GET -v https://prometheus.uni-koeln.de/pandora/api/xml/upload/list --header 'Authorization: OAuth oauth_consumer_key="<oauth_consumer_key>", oauth_nonce="<oauth_nonce>", oauth_signature="<oauth_signature>", oauth_signature_method="HMAC-SHA1", oauth_timestamp="<oauth_timestamp>", oauth_token="<oauth_token>", oauth_version="1.0"'
Basic information about pandora as JSON and XML (see GET /about
):
https://prometheus.uni-koeln.de/pandora/api/v1/json/about
https://prometheus.uni-koeln.de/pandora/api/v1/xml/about
The number of tree
images as JSON and XML (see GET /search/hits
):
https://prometheus.uni-koeln.de/pandora/api/v1/json/search/hits?term=tree
https://prometheus.uni-koeln.de/pandora/api/v1/xml/search/hits?term=tree
The search results matching the titles genius
and genius AND bavaria
as XML (see GET /search/search
and GET /search/advanced_search
):
https://prometheus.uni-koeln.de/pandora/api/xml/search/search?s%5B%5D=giessen_lri&term=genius
https://prometheus.uni-koeln.de/pandora/api/xml/search/advanced_search?f%5B%5D=title&o%5B%5D=and&s%5B%5D=giessen_lri&v%5B%5D=bavaria
The image THE GENIUS OF BAVARIA
in medium size (see GET /image/medium
) and its metadata as XML (see GET /image/show
):
https://prometheus.uni-koeln.de/pandora/api/blob/image/medium/giessen_lri-eb11de4bb8e2a6c50f0440b536d040165927c47f
https://prometheus.uni-koeln.de/pandora/api/xml/image/show/giessen_lri-eb11de4bb8e2a6c50f0440b536d040165927c47f
Create a record for your database (see POST /upload/create
):
curl -v -u <user name>:<password> -F upload[file]=@"<file path>" -F upload[title]="<title>" -F upload[rights_reproduction|credits]="<reproduction rights or credits>" -F upload[rights_work]="<work rights>" https://prometheus.uni-koeln.de/pandora/api/xml/upload/create
Read a record from your database (see GET /upload/edit
):
https://prometheus.uni-koeln.de/pandora/api/xml/upload/edit/<id>
Update a record from your database (see PUT /upload/edit
):
curl --request PUT -v -u <user name>:<password> -F id="<id>" -F upload[title]="<title>" https://prometheus.uni-koeln.de/pandora/api/xml/upload/edit
Delete a record from your database (see DELETE /upload/destroy
):
https://prometheus.uni-koeln.de/pandora/api/xml/upload/destroy/<id>
Delete a favorite (see DELETE /box/delete
):
curl --request DELETE -v -u <user name>:<password> -F id="<id>" https://prometheus.uni-koeln.de/pandora/api/xml/box/delete
Web application description
A machine-readable description of this API is available in WADL format:
https://prometheus.uni-koeln.de/pandora/pandora.wadl
GET /account/show
Get a user record.
Request parameters
id
[QUERY] (required)
The id of the user record.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- user
GET /account/terms_of_use
Get current terms of use.
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
POST /account/terms_of_use
Accept current terms of use.
Request parameters
accepted
[QUERY] (required)
True if accepted, false otherwise.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
GET /announcement/current
Get the list of current announcements.
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- announcements
announcement
(repeating)- /announcements/announcement
POST /box/create
Create a favorite.
Request parameters
box
[QUERY] (required)
Nested parameter that must contain box[id] (the ID of the object), box[controller] (the controller of the object, namely image, collection, or presentation), and box[action]='show'.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- box
id
- /box/id
DELETE /box/delete
Delete a favorite.
Request parameters
id
[QUERY] (required)
The id of the favorite.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- box
id
- /box/id
GET /box/list
List a user's favorites.
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- box
id
- /box/id
POST /collection/create
Create a collection.
Request parameters
collection
[QUERY] (required)
Nested parameter that must contain collection[title]. Images are included as nested parameter collection[images] with an array of image pids as value.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- collection
POST /collection/delete
Delete a collection.
Request parameters
id
[QUERY] (required)
The id of the collection.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- collection
GET /collection/images
Get the list of a collection's images.
Request parameters
direction
[QUERY]
Direction to sort collections in.
- Type
- String
- Options
- ASC, DESC
- Default
- ASC
id
[QUERY] (required)
Collection ID.
- Type
- String
order
[QUERY]
Attribute to sort collections by.
- Type
- String
- Options
- insertion_order, artist, title, location, credits
- Default
- insertion_order
page
[QUERY]
Number of page to return.
- Type
- Positiveinteger
- Default
- 1
per_page
[QUERY]
Number images per page to return.
- Type
- Positiveinteger
- Default
- 30
Response formats
json
- Media type
- application/json
- Object
- {:id, :title, :notes, :forked_at, :owner_id, :thumbnail_id, :public_access, :meta_image, :created_at, :updated_at, :changed_at, :references, :description, :links, images: [{:pid, :artist, :title, :location, :date, :credits, :source_id, :collection_id, :votes, :image_id, :score, :checked_at}]}
xml
- Media type
- application/xml
- Element
- images
image
(repeating)- /images/image
GET /collection/meta_image
Get the list of Meta-Image collections.
Request parameters
direction
[QUERY]
Direction to sort collections in.
- Type
- String
- Options
- ASC, DESC
- Default
- ASC
field
[QUERY]
Search field.
- Type
- String
- Options
- title, description, keywords, owner, [image]
order
[QUERY]
Attribute to sort collections by.
- Type
- String
- Options
- title, changed_at, owner
- Default
- title
page
[QUERY]
Number of page to return.
- Type
- Positiveinteger
- Default
- 1
value
[QUERY]
Query term.
- Type
- String
Response formats
json
- Media type
- application/json
- Object
- [{<collection fields>},...]
xml
- Media type
- application/xml
- Element
- collections
collection
(repeating)- /collections/collection
GET /collection/meta_image_owners_fullname
Get the list of the owners fullname from Meta-Image collections.
Request parameters
direction
[QUERY]
Direction to sort collections in.
- Type
- String
- Options
- ASC, DESC
- Default
- ASC
field
[QUERY]
Search field.
- Type
- String
- Options
- title, description, keywords, owner, [image]
order
[QUERY]
Attribute to sort collections by.
- Type
- String
- Options
- title, changed_at, owner
- Default
- title
page
[QUERY]
Number of page to return.
- Type
- Positiveinteger
- Default
- 1
value
[QUERY]
Query term.
- Type
- String
Response formats
json
- Media type
- application/json
- Object
- [{"fullname":<fullname>, "id":<id>},...]
xml
- Media type
- application/xml
- Element
- fullnames
GET /collection/meta_image_status
Get a collection's Meta-Image status. (Restricted access)
Request parameters
id
[QUERY] (required)
Collection ID.
- Type
- String
Response formats
xml
- Media type
- application/xml
- Element
- collection
id
- /collection/id
meta-image
- /collection/meta-image
PUT /collection/meta_image_status
Set a collection's Meta-Image status. (Restricted access)
Request parameters
id
[QUERY] (required)
Collection ID.
- Type
- String
Response formats
xml
- Media type
- application/xml
- Element
- collection
id
- /collection/id
meta-image
- /collection/meta-image
GET /collection/number_of_pages
Get a collection's number of pages.
Request parameters
type
[QUERY] (required)
Collection type, either own, shared, public, or meta_image.
- Type
- String
Response formats
json
- Media type
- application/json
- Object
- {:number_of_pages}
xml
- Media type
- application/xml
- Element
- number_of_pages
GET /collection/own
Get the list of your collections.
Request parameters
direction
[QUERY]
Direction to sort collections in.
- Type
- String
- Options
- ASC, DESC
- Default
- ASC
field
[QUERY]
Search field.
- Type
- String
- Options
- title, description, keywords, owner, [image]
order
[QUERY]
Attribute to sort collections by.
- Type
- String
- Options
- title, changed_at, owner
- Default
- title
page
[QUERY]
Number of page to return.
- Type
- Positiveinteger
- Default
- 1
value
[QUERY]
Query term.
- Type
- String
Response formats
json
- Media type
- application/json
- Object
- [{<collection fields>},...]
xml
- Media type
- application/xml
- Element
- collections
collection
(repeating)- /collections/collection
GET /collection/own_all
Get the list of all your collections.
Response formats
json
- Media type
- application/json
- Object
- [{<collection fields>},...]
xml
- Media type
- application/xml
- Element
- collections
collection
(repeating)- /collections/collection
GET /collection/public
Get the list of public collections.
Request parameters
direction
[QUERY]
Direction to sort collections in.
- Type
- String
- Options
- ASC, DESC
- Default
- ASC
field
[QUERY]
Search field.
- Type
- String
- Options
- title, description, keywords, owner, [image]
order
[QUERY]
Attribute to sort collections by.
- Type
- String
- Options
- title, changed_at, owner
- Default
- title
page
[QUERY]
Number of page to return.
- Type
- Positiveinteger
- Default
- 1
value
[QUERY]
Query term.
- Type
- String
Response formats
json
- Media type
- application/json
- Object
- [{<collection fields>},...]
xml
- Media type
- application/xml
- Element
- collections
collection
(repeating)- /collections/collection
GET /collection/public_owners_fullname
Get the list of the owners fullname from public collections.
Request parameters
direction
[QUERY]
Direction to sort collections in.
- Type
- String
- Options
- ASC, DESC
- Default
- ASC
field
[QUERY]
Search field.
- Type
- String
- Options
- title, description, keywords, owner, [image]
order
[QUERY]
Attribute to sort collections by.
- Type
- String
- Options
- title, changed_at, owner
- Default
- title
page
[QUERY]
Number of page to return.
- Type
- Positiveinteger
- Default
- 1
value
[QUERY]
Query term.
- Type
- String
Response formats
json
- Media type
- application/json
- Object
- [{"fullname":<fullname>, "id":<id>},...]
xml
- Media type
- application/xml
- Element
- fullnames
POST /collection/remove
Remove an image from a collection.
Request parameters
id
[QUERY] (required)
The id of the collection.
- Type
- String
image
[QUERY] (required)
The pid of the image.
- Type
- Array
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- collection
GET /collection/shared
Get the list of collections that have been shared with you.
Request parameters
direction
[QUERY]
Direction to sort collections in.
- Type
- String
- Options
- ASC, DESC
- Default
- ASC
field
[QUERY]
Search field.
- Type
- String
- Options
- title, description, keywords, owner, [image]
order
[QUERY]
Attribute to sort collections by.
- Type
- String
- Options
- title, changed_at, owner
- Default
- title
page
[QUERY]
Number of page to return.
- Type
- Positiveinteger
- Default
- 1
value
[QUERY]
Query term.
- Type
- String
Response formats
json
- Media type
- application/json
- Object
- [{<collection fields>},...]
xml
- Media type
- application/xml
- Element
- collections
collection
(repeating)- /collections/collection
GET /collection/shared_owners_fullname
Get the list of the owners fullname from collections that have been shared with you.
Request parameters
direction
[QUERY]
Direction to sort collections in.
- Type
- String
- Options
- ASC, DESC
- Default
- ASC
field
[QUERY]
Search field.
- Type
- String
- Options
- title, description, keywords, owner, [image]
order
[QUERY]
Attribute to sort collections by.
- Type
- String
- Options
- title, changed_at, owner
- Default
- title
page
[QUERY]
Number of page to return.
- Type
- Positiveinteger
- Default
- 1
value
[QUERY]
Query term.
- Type
- String
Response formats
json
- Media type
- application/json
- Object
- [{"fullname":<fullname>, "id":<id>},...]
xml
- Media type
- application/xml
- Element
- fullnames
POST /collection/store
Store images in a collection.
Request parameters
collection
[QUERY] (required)
Nested parameter that must contain collection[collection_id].
- Type
- String
image
[QUERY] (required)
Images are included as an array of image pids.
- Type
- Array
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- collection
GET /collection/writable
Get the list of current user's writable collections.
Response formats
json
- Media type
- application/json
- Object
- [{"id":<id>, "title":<title>},...]
xml
- Media type
- application/xml
- Element
- fullnames
POST /image/add_meta_image_comment
Add Meta-Image comment to an image. (Restricted access)
Request parameters
collection
[QUERY] (required)
Collection ID.
- Type
- String
f[]
[QUERY] (required)
Metadata field.
- Type
- String
- Repeating
- true
id
[QUERY] (required)
Image ID.
- Type
- String
v[]
[QUERY] (required)
Metadata value.
- Type
- String
- Repeating
- true
Response formats
xml
- Media type
- application/xml
- Element
- image
pid
- /image/pid
GET /image/display_fields
Get image display fields and German translation.
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- display_fields
GET /image/large
Get an image's binary representation in large size.
Request parameters
id
[QUERY] (required)
Image ID.
- Type
- String
Response formats
blob
- Media type
- image/*
GET /image/list
Get the list of all images.
Request parameters
open_access
[QUERY]
Whether to return only Open Access images.
- Type
- Boolean
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- images
pid
(repeating)- /images/pid
GET /image/medium
Get an image's binary representation in medium size.
Request parameters
id
[QUERY] (required)
Image ID.
- Type
- String
Response formats
blob
- Media type
- image/*
GET /image/show
Get an image's metadata.
Request parameters
id
[QUERY] (required)
Image ID.
- Type
- String
Response formats
json
- Media type
- application/json
- Object
- {:source_id, :score, :checked_at, :votes, :pid, <all display fields>}
xml
- Media type
- application/xml
- Element
- image
pid
- /image/pid
artist
- /image/artist
title
- /image/title
GET /image/small
Get an image's binary representation in small size.
Request parameters
id
[QUERY] (required)
Image ID.
- Type
- String
Response formats
blob
- Media type
- image/*
GET /about
Get basic information about pandora.
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- pandora
version
- /pandora/version
facts
- /pandora/facts
GET /facts
Get basic facts about pandora.
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- pandora
images
- /pandora/images
sources
- /pandora/sources
licenses
- /pandora/licenses
accounts
- /pandora/accounts
version
- /pandora/version
POST /presentation/delete
Delete a presentation.
Request parameters
id
[QUERY] (required)
The id of the presentation.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- presentation
GET /presentation/own
Get the list of your presentations.
Request parameters
direction
[QUERY]
Direction to sort presentations in.
- Type
- String
- Options
- ASC, DESC
- Default
- ASC
field
[QUERY]
Search field.
- Type
- String
- Options
- title, description, keywords, owner, [image]
order
[QUERY]
Attribute to sort presentations by.
- Type
- String
- Options
- title, changed_at, owner
- Default
- title
page
[QUERY]
Number of page to return.
- Type
- Positiveinteger
- Default
- 1
value
[QUERY]
Query term.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- presentations
presentation
(repeating)- /presentations/presentation
GET /presentation/public
Get the list of public presentations.
Request parameters
direction
[QUERY]
Direction to sort presentations in.
- Type
- String
- Options
- ASC, DESC
- Default
- ASC
field
[QUERY]
Search field.
- Type
- String
- Options
- title, description, keywords, owner, [image]
order
[QUERY]
Attribute to sort presentations by.
- Type
- String
- Options
- title, changed_at, owner
- Default
- title
page
[QUERY]
Number of page to return.
- Type
- Positiveinteger
- Default
- 1
value
[QUERY]
Query term.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- presentations
presentation
(repeating)- /presentations/presentation
GET /presentation/run
Read a presentation as PDF.
Request parameters
id
[QUERY] (required)
The id of the presentation.
- Type
- String
Response formats
pdf
- Media type
- application/pdf
GET /presentation/shared
Get the list of presentations that have been shared with you.
Request parameters
direction
[QUERY]
Direction to sort presentations in.
- Type
- String
- Options
- ASC, DESC
- Default
- ASC
field
[QUERY]
Search field.
- Type
- String
- Options
- title, description, keywords, owner, [image]
order
[QUERY]
Attribute to sort presentations by.
- Type
- String
- Options
- title, changed_at, owner
- Default
- title
page
[QUERY]
Number of page to return.
- Type
- Positiveinteger
- Default
- 1
value
[QUERY]
Query term.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- presentations
presentation
(repeating)- /presentations/presentation
GET /search/advanced_search
Perform an "advanced" search.
Request parameters
f[]
[QUERY] (required)
Search field.
- Type
- String
- Options
- all, artist, title, location, discoveryplace, genre, material, keyword, description, date, credits, rights_reproduction, unspecified, associated, related
- Repeating
- true
o[]
[QUERY]
Search operator.
- Type
- String
- Options
- and, or, and not
- Repeating
- true
order
[QUERY]
Field to sort results by.
- Type
- String
- Options
- relevance, artist, title, location, credits, source_title, rating, comments
- Default
- relevance
page
[QUERY]
Number of page to return.
- Type
- Positiveinteger
- Default
- 1
per_page
[QUERY]
Number of results to display per page.
- Type
- Positiveinteger
- Default
- 10
s[]
[QUERY]
Sources to search.
- Type
- String
- Options
- amsterdam_museum, amsterdam_rijksmuseum, amtub, arachne, archgiessen, artemis, artemis_bk, assisi, beeskow_kunstarchiv, berlin_ikb_dias, berlin_spsg, berlin_udk, berlin_winckelmann, bern, bochum_kgi, bochum_ug, bpk, caerlangen, dadaweb, darmstadt_tu, daumier, ddorf, ddorf_ka, desanhalt, digidia, digidianeu, dmr, dresden, dresden_hfbk, eichstaett_ub, erlangen_drucke, erlangen_zeichnungen, ethzuerich, genf, giessen_kup, giessen_lri, goettingen_arch, gregorsmesse, halle_kg, hamburg, heidicon_aa, heidicon_ad, heidicon_al, heidicon_ar, heidicon_bp, heidicon_fb, heidicon_fk, heidicon_gs, heidicon_ha, heidicon_ka, heidicon_kb, heidicon_kg, heidicon_pu, heidicon_sd, heidicon_sh, heidicon_si, heidicon_ua, heidicon_wa, heidicon_zo, imago, kassel, kgerlangen, kiel_digicult, koeln_rba, koeln_rba_koer, leipzig, lueneburg_oppermann, mainz, mainz_kb, marburg_lba, mka, muenster_theologie, oldenburg_afrika, paderborn, passau_dilps, piranesi, plattner_panamericana, ppo, requiem, robertin, saarbruecken_ifk, salzburg, stabi, theoleik, trier, tuberlin, uustb, virtualart, wbarchiv, zi_muc
- Repeating
- true
v[]
[QUERY] (required)
Query term.
- Type
- String
- Repeating
- true
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- search
results/result
(repeating)- /search/results/result
count
- /search/count
query
- /search/query
GET /search/hits
Number of hits a "simple" search would yield.
Request parameters
field
[QUERY]
Search field.
- Type
- String
- Options
- all, artist, title, location, discoveryplace, genre, material, keyword, description, date, credits, rights_reproduction, unspecified, associated, related
- Default
- all
term
[QUERY] (required)
Query term.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- hits
query
- /hits/query
count
- /hits/count
GET /search/search
Perform a "simple" search.
Request parameters
field
[QUERY]
Search field.
- Type
- String
- Options
- all, artist, title, location, discoveryplace, genre, material, keyword, description, date, credits, rights_reproduction, unspecified, associated, related
- Default
- all
order
[QUERY]
Field to sort results by.
- Type
- String
- Options
- relevance, artist, title, location, credits, source_title, rating, comments
- Default
- relevance
page
[QUERY]
Number of page to return.
- Type
- Positiveinteger
- Default
- 1
per_page
[QUERY]
Number of results to display per page.
- Type
- Positiveinteger
- Default
- 10
term
[QUERY] (required)
Query term.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- search
results/result
(repeating)- /search/results/result
count
- /search/count
query
- /search/query
GET /source/list
Get the list of sources.
Response formats
json
- Media type
- application/json
POST /upload/create
Create a record for your database.
Request parameters
upload
[QUERY] (required)
Nested parameter that must contain upload[file], upload[title], upload[rights_reproduction] or upload[credits] and upload[rights_work].
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- upload
DELETE /upload/destroy
Delete a record of your database.
Request parameters
id
[QUERY] (required)
The id of the record of your database.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- upload
GET /upload/edit
Read a record of your database.
Request parameters
id
[QUERY] (required)
The id of the record of your database.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- upload
PUT /upload/edit
Update a record of your database.
Request parameters
id
[QUERY] (required)
The id of the record of your database.
- Type
- String
upload
[QUERY] (required)
Nested parameter where upload[title], upload[rights_reproduction] or upload[credits] and upload[rights_work] can not be empty.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- upload
GET /upload/list
Get the list of your database records.
Request parameters
direction
[QUERY]
Direction to sort database records in.
- Type
- String
- Options
- ASC, DESC
- Default
- ASC
field
[QUERY]
Search field.
- Type
- String
- Options
- artist, title, location, description, keywords, inventory_no
order
[QUERY]
Attribute to sort database records by.
- Type
- String
- Options
- updated_at, created_at, artist, title, location
- Default
- updated_at
page
[QUERY]
Number of page to return.
- Type
- Positiveinteger
- Default
- 1
per_page
[QUERY]
Number of results to display per page.
- Type
- Positiveinteger
- Default
- 40
value
[QUERY]
Query term.
- Type
- String
Response formats
json
- Media type
- application/json
xml
- Media type
- application/xml
- Element
- uploads
upload
(repeating)- /uploads/upload