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
`text`	any message (optional)

`GET /ping_auth.xml`

Ping PhotoDeck API service. User authentication is required.

Parameters
`text`	any message (optional)

Websites

`GET /websites.xml`

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

Parameters
`view`	[list\|details] (optional)
`page`	page number
`per_page`	results 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)
`page`	page number
`per_page`	results 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_medias`	0\|1 (optional)
`medias_count`	expected 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
`page`	page number
`per_page`	results 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)
`page`	page number
`per_page`	results 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)
`page`	page number
`per_page`	results 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_id`	uuid of media library (optional)
`page`	page number
`per_page`	hits 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_id`	uuid of media library (optional)

For a smart collection:

Parameters (smart collection case only)
`medias_smart_collection[name]`	smart collection name (mandatory)
`artist_id`	uuid 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_medias`	0\|1 (optional)
`medias_count`	expected 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)
`page`	page number
`per_page`	results per page, 500 max
`artist_id`	uuid of media library (optional)
`gallery_id`	uuid of gallery (optional)
`medias_group_id`	uuid of media group (optional)
`lightbox_id`	uuid 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 successful, 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_id`	uuid of media library to upload to (optional)

Parameters returned by step 1
`media/uuid`	UUID of newly created media. Needed at step 3
`media/file-name`	name of the file to be uploaded, can be different than the one provided in step 1. Needed at step 3
`media/upload-location`	selected upload location, internal use. Needed at step 3
`media/upload-url`	URL to use to upload the actual file
`media/upload-method`	HTTP 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-param`	name 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-param`	value of first upload-param
`second upload-param`	value of second upload-param
`...`	... (repeat for each provided upload-param)
`value of upload-file-param`	actual 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
`select`	all\|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_count`	expected number of media to be updated (optional)
`gallery_id`	restrict operation to media within that gallery
`medias_group_id`	restrict operation to media within that media group
`lightbox_id`	restrict 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.