API Documentation

Introduction

Please note that:
  • You need an API key. Please read the getting started chapter here.
  • All requests should include the mandatory X-PhotoDeck-Authorization and X-PhotoDeck-Timestamp HTTP headers.
  • Strings should be encoded in UTF-8.
  • Most endpoints require user authentication. HTTP Basic authentication is supported for now, and should be performed once per session. A session cookie should be carried over for subsequent requests.
  • XML is used in the PhotoDeck services replies.
  • Request rate is limited.
    • Make sure that you don't make more than 1 request per second to the API, or throttle your requests according to the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset HTTP headers.
    • Properly manage HTTP 429 status code and respect the Retry-After HTTP header.
    • It is highly recommended to reuse existing HTTP connections (HTTP keep-alive) between consecutive requests. Failure to do so might result in HTTP 429 Too Many Requests errors, or connections being refused.

Passing parameters to API function calls

The functions specified hereafter requires mandatory and/or optional parameters.
  • For GET requests, pass them in the request query string
  • For POST, PUT and DELETE requests, pass them in a FORM (set the request content-type to application/x-www-form-urlencoded, and URL encode the parameters in the body).
    Note that file uploads require multi-part FORM instead of plain FORM.

Session management and user authentication

Logging in

Any request that requires user authentication needs either HTTP Basic authentication headers, or a valid session build during a previous request (session cookie _ficelle_session).

As such, there is no dedicated login procedure. Directly call the required API method.

Users with 2FA enabled need to have their password appended with the + sign and their current one-time use authentication code (eg., password+123456). Failing to do so for those users will result in an error reply with auth-method=basic:password+otp: in that case, ask the user for its current code and submit again with the code.

Carry cookies over each requests to maintain your session. Do not resubmit the user authentication HTTP Basic authentication headers at each request.

GET /logout.xml

Kill current session

GET /whoami.xml

Retrieve basic profile information for currently logged in user.

Also useful to know if current session is still valid or if correctly logged in.

It might be used as the first login request to PhotoDeck.

Pinging PhotoDeck Services

GET /ping.xml

Ping PhotoDeck API service. No user authentication required.

Parameters
textany message (optional)

GET /ping_auth.xml

Ping PhotoDeck API service. User authentication is required.

Parameters
textany message (optional)

Websites

GET /websites.xml

Retrieves the list of websites that current user as access to.

Parameters
view[list|details] (optional)
pagepage number
per_pageresults per page, 100 max

Galleries

GET /websites/urlname/galleries.xml

Retrieves the list of all galleries for a given website.

Parameters
view[list|details] (optional)
pagepage number
per_pageresults per page, 500 max

GET /websites/urlname/galleries/uuid.xml

Retrieves the details of a gallery.

Parameters
view[details|details_with_medias|details_with_contents] (optional)

POST /websites/urlname/galleries.xml

Creates a new gallery. Up to 1000 subgalleries can be created under any gallery, including the root gallery.

Parameters
gallery[name]name of the gallery (mandatory)
gallery[parent]uuid of the parent gallery (mandatory)
gallery[url_path]URL path of the gallery, blank to assign from name (optional)
gallery[description]gallery intro (optional)
gallery[display_style]uuid of gallery display style (optional)
gallery[cover_media]uuid of cover media (optional)
gallery[hidden][0|1] (optional)
gallery[indexing][0|1|2] (0=never, 1=auto [default], 2=always -- optional)
gallery[password]blank or password (optional)
gallery[content_order][manual-first|manual-last|file_name|file_name_nat|published_at|shot_at|created_at|updated_at|artist_rating] (optional)
gallery[content_order_direction][asc|desc] (optional)
gallery[order_subgalleries][0|1] (optional)

Optionally: to set authorizations, start with default authorizations:

Parameters
gallery[acl][0][email]DEFAULT
gallery[acl][0][read][0|1]
gallery[acl][0][comp_download][0|1]
gallery[acl][0][hires_download][0|1]

then you may authorize specific client(s) (repeat for each client, assign each one a unique one-time numeric id (1, 2, 3...)):

Parameters
gallery[acl][id][email]client email address
gallery[acl][id][read][0|1]
gallery[acl][id][comp_download][0|1]
gallery[acl][id][hires_download][0|1]

PUT /websites/urlname/galleries/uuid.xml

Updates an existing gallery.

Parameters
gallery[name]new name for the gallery (optional)
gallery[parent]uuid of new parent gallery (optional)
gallery[url_path]new URL path of the gallery, blank to assign from name (optional)
gallery[medias_order]reorder the medias as specified by this comma separated list of medias uuid (optional)
gallery[description]gallery intro (optional)
gallery[display_style]uuid of gallery display style (optional)
gallery[cover_media]uuid of media to use as cover (optional)
gallery[hidden][0|1] (optional)
gallery[indexing][0|1|2] (0=never, 1=auto [default], 2=always -- optional)
gallery[password]blank or password (optional)
gallery[content_order][manual-first|manual-last|file_name|file_name_nat|published_at|shot_at|created_at|updated_at|artist_rating] (optional)
gallery[content_order_direction][asc|desc] (optional)

DELETE /websites/urlname/galleries/uuid.xml

Deletes a gallery and its sub-galleries.

Parameters
delete_medias0|1 (optional)
medias_countexpected number of media to be deleted (optional)

GET /websites/urlname/galleries/uuid/subgalleries.xml

Retrieves all parent galleries and paginated list of direct sub-galleries.

Parameters
pagepage number
per_pageresults per page, 500 max
filter[name]name of sub-gallery to search for (optional)

Gallery Display Styles

GET /websites/urlname/gallery_display_styles.xml

Retrieves the list of all gallery display styles.

Parameters
view[list|details] (optional)
pagepage number
per_pageresults per page, 500 max

Media libraries

GET /artists.xml

Retrieves the list of media libraries that current user has access to.

Parameters
view[list|details] (optional)
pagepage number
per_pageresults per page, 100 max

Media groups (collections and smart collections)

GET /medias_groups.xml

Retrieves the list of all collections and smart collections.

Parameters
view[list|details] (optional)
artist_iduuid of media library (optional)
pagepage number
per_pagehits per page, 500 max

GET /medias_groups/uuid.xml

Retrieves the details and content of a collection or smart collection.

Parameters
view[details|details_with_medias] (optional)

POST /medias_groups.xml

Creates a new collection or smart collection.

For a collection:

Parameters (collection case only)
medias_collection[name]collection name (mandatory)
artist_iduuid of media library (optional)

For a smart collection:

Parameters (smart collection case only)
medias_smart_collection[name]smart collection name (mandatory)
artist_iduuid of media library (optional)

PUT /medias_groups/uuid.xml

Updates an existing collection or smart collection.

For a collection:

Parameters (collection case only)
medias_collection[name]new collection name (optional)

For a smart collection:

Parameters (smart collection case only)
medias_smart_collection[name]new smart collection name (optional)

DELETE /medias_groups/uuid.xml

Deletes a collection or smart collection.

Parameters
delete_medias0|1 (optional)
medias_countexpected number of media to be deleted (optional)

Images, videos and documents

GET /medias.xml

Retrieves the list of all media (images, videos, documents...).

Parameters
view[list|base|details|public_details] (optional)
pagepage number
per_pageresults per page, 500 max
artist_iduuid of media library (optional)
gallery_iduuid of gallery (optional)
medias_group_iduuid of media group (optional)
lightbox_iduuid of lightbox (optional)

GET /medias/uuid.xml

Retrieves the details of a media.

POST /medias.xml

Creates and upload a new media. This is a 3-steps process.

Step 1 : create a new media in the backend. If successfull, an upload URL and parameters are returned.

Parameters (POST /medias.xml)
media[content][upload_location]REQUEST (mandatory)
media[content][file_name]name of file to be uploaded, eg: IMG1234.JPG (mandatory)
media[content][file_size]size of file, in bytes (mandatory)
media[content][mime_type]MIME type of file, eg: image/jpeg (mandatory)
media[replace]set to 1 to replace any existing media that has the same file name (a new media will be created if no match is found) (optional)
media[add_to_medias_collections][]collection uuids; repeat this parameter for each collection (optional)
media[publish_to_galleries][]gallery uuids; repeat this parameter for each gallery (optional)
artist_iduuid of media library to upload to (optional)

Parameters returned by step 1
media/uuidUUID of newly created media. Needed at step 3
media/file-namename of the file to be uploaded, can be different than the one provided in step 1. Needed at step 3
media/upload-locationselected upload location, internal use. Needed at step 3
media/upload-urlURL to use to upload the actual file
media/upload-methodHTTP method (eg, POST) to use to upload actual file
media/upload-params/...parameters that should be included when uploading the actual file (should be included before file content)
media/upload-file-paramname of field to use to for the file content

Step 2: upload the file to the given URL with given parameters.

Parameters (UPLOAD-METHOD upload-url)
first upload-paramvalue of first upload-param
second upload-paramvalue of second upload-param
...... (repeat for each provided upload-param)
value of upload-file-paramactual file content

Step 3 : inform backend when upload is complete.

Parameters (PUT /medias/uuid.xml)
media[content][upload_location]upload location as returned in step 1 (mandatory)
media[content][file_name]name of file as returned by step 1 (mandatory)
media[content][file_size]size of file as provided in step 1 (mandatory)
media[content][mime_type]MIME type of file as provided in step 1 (mandatory)

Example from command line using curl:

$ api_key=your api key; api_secret=your secret key $ file=path to file to upload $ # Step 1 $ request='/medias.xml'; querystring=''; timestamp=$(date -R); sign=$(printf "POST\n$request\n$querystring\n$api_secret\n$timestamp\n" | sha1sum | cut -f1 -d' ') $ curl -H "X-PhotoDeck-Authorization:$api_key:$sign" -H "X-PhotoDeck-Timestamp: $timestamp" \ -u your@email.address -F media[content][upload_location]=REQUEST -F media[content][file_name]=`basename "$file"` -F media[content][file_size]=`stat -c "%s" "$file"` -F media[content][mime_type]=`mimetype -b "$file"` "https://api.photodeck.com$request${querystring:+?$querystring}" $ # Step 2 $ curl -X value of upload-method \ -F first upload-param=value of first upload-param -F second upload-param=value of second upload-param -F ...repeat for each upload-param... \ -F value of upload-file-param=@"$file" "value of upload-url" $ # Step 3 $ request='/medias/media uuid.xml'; querystring=''; timestamp=$(date -R); sign=$(printf "PUT\n$request\n$querystring\n$api_secret\n$timestamp\n" | sha1sum | cut -f1 -d' ') $ curl -X PUT -H "X-PhotoDeck-Authorization:$api_key:$sign" -H "X-PhotoDeck-Timestamp: $timestamp" \ -u your@email.address -F media[content][upload_location]=value returned at step 1 -F media[content][file_name]=value returned at step 1 -F media[content][file_size]=`stat -c "%s" "$file"` -F media[content][mime_type]=`mimetype -b "$file"` "https://api.photodeck.com$request${querystring:+?$querystring}"

PUT /medias/uuid.xml

Updates the meta data of a media and set galleries / collections in which the media is published.

Note: parameters should be posted using multipart/form-data encoding. application/x-www-form-urlencoded encoding is not supported on this operation.

Note: to replace the file with another one, use the same parameters as step 1 of the initial upload, and then follow the same process for step 2 and 3.

Parameters
media[title]title (optional)
media[description]description (optional)
media[keywords]keywords, separated by commas (optional)
media[add_keywords]keywords to be added, separated by commas (optional)
media[remove_keywords]keywords to be removed, separated by commas (optional)
media[location]location (optional)
media[city]city (optional)
media[state]state (optional)
media[country]country (optional)
media[region]region (optional)
media[author]author (optional)
media[copyright]copyright notice (optional)
media[model_release]0|1 (optional)
media[property_release]0|1 (optional)
media[artist_id]uuid of media library to move media to (optional)
media[medias_collections][]collection uuid in which the media should be; repeat this parameter for each collection (optional)
media[add_to_medias_collections][]collection uuids; repeat this parameter for each collection (optional)
media[remove_from_medias_collections][]collection uuids; repeat this parameter for each collection (optional)
media[galleries][]gallery uuid in which the media should be visible; repeat this parameter for each gallery (optional) Note: existing galleries not specified here will unpublish the media (unless existing galleries are passed again to the list). Use publish_to_galleries or unpublish_from_galleries if this behavior is not wanted.
media[publish_to_galleries][]gallery uuids; repeat this parameter for each gallery (optional)
media[unpublish_from_galleries][]gallery uuids; repeat this parameter for each gallery (optional)
media[add_pricing_profiles][]pricing profile uuids to add; repeat if more than one pricing profile (optional)
media[remove_pricing_profiles][]pricing profile uuids to remove; repeat if more than one pricing profile (optional)

PUT /medias/batch_update.xml

Updates a batch of media. The batch can either be a list of media or all media within a gallery, media group (collection or smart collection), lightbox...

Note: updates will be performed asynchronously, usually within a couple of minutes.

Parameters
selectall|list of media uuids to be updated, separated by commas (mandatory) Note: or use all to update all media within a given gallery/collection/lightbox/... (and pass the corresponding id in the gallery_id, medias_group_id or lightbox_id parameter)
medias_countexpected number of media to be updated (optional)
gallery_idrestrict operation to media within that gallery
medias_group_idrestrict operation to media within that media group
lightbox_idrestrict operation to media within that lightbox
medias[title]title (optional)
medias[description]description (optional)
medias[keywords]keywords, separated by commas (optional)
medias[add_keywords]keywords to be added, separated by commas (optional)
medias[remove_keywords]keywords to be removed, separated by commas (optional)
medias[location]location (optional)
medias[city]city (optional)
medias[state]state (optional)
medias[country]country (optional)
medias[region]region (optional)
medias[model_release]0|1 (optional)
medias[property_release]0|1 (optional)
medias[artist_id]uuid of media library to move media to (optional)
medias[medias_collections][]collection uuid in which the media should be; repeat this parameter for each collection (optional)
medias[add_to_medias_collections][]collection uuids; repeat this parameter for each collection (optional)
medias[remove_from_medias_collections][]collection uuids; repeat this parameter for each collection (optional)
medias[galleries][]gallery uuid in which the media should be visible; repeat this parameter for each gallery (optional) Note: existing galleries not specified here will unpublish the media (unless existing galleries are passed again to the list). Use publish_to_galleries or unpublish_from_galleries if this behavior is not wanted.
medias[publish_to_galleries][]gallery uuids; repeat this parameter for each gallery (optional)
medias[unpublish_from_galleries][]gallery uuids; repeat this parameter for each gallery (optional)
medias[add_pricing_profiles][]pricing profile uuids to add; repeat if more than one pricing profile (optional)
medias[remove_pricing_profiles][]pricing profile uuids to remove; repeat if more than one pricing profile (optional)
medias[delete]1 (optional) to delete media permanently

DELETE /medias/uuid.xml

Deletes a media.