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