Requests

All endpoints on the PhotoShelter API are located at /psapi/v3 and can be accessed at www.photoshelter.com as well as at a user subdomain and CNAME. (We encourage you to default to using only the major version number - e.g. v3 - since it is backward compatible and will always be at the latest point release.) To grab the image_id of all images in a particular gallery, for example, simply make the following request with your API key:

/psapi/v3/gallery/MY_GALLERY_ID/images?api_key=MY_API_KEY&fields=image_id

Public v. Member

There are two types of endpoints on the PhotoShelter API: public endpoints and member endpoints. The difference is that member endpoints require user authentication while public endpoints do not, since public endpoints are read-only and are subject to the permissions enforced by content owners.

Extensions

On the PhotoShelter API, an endpoint can be "extended" by one or more other related endpoints. Extensions allow one call to the API to hit two or more endpoints, enabling multiple actions to be performed with just one request. Neat, right?

To extend an endpoint, you must pass the extend parameter to the initial endpoint. The value to the extend parameter is a JSON object containing one or more key-value pairs, each of which represents an endpoint by which the initial endpoint is to be extended. The syntax of the key-value pairs is as follows:

Key	Value
Name of the record type that is returned by the extending endpoint, written in camelcase as a singular noun	An object with two property names: `fields`: a string of comma-separated list of requested output fields. This corresponds with the `fields` request parameter. `params`: an object consisting of pairs of input parameters ({"name":"value"}), as permitted for that particular endpoint.

For example, to extend Gallery (/psapi/v3/gallery/{gallery_id}) by GalleryImage (via /psapi/v3/gallery/{gallery_id}/images) and ImageLink (via /psapi/v3/image/{image_id}/link), set the extend parameter to:

var extendGal = {
	"GalleryImage": {
			"fields": "image_id",
			"params": {}
		},
	"ImageLink": {
		"fields": "link,base",
		"params": {
			"image_mode": "fit",
			"image_size": "300x300"
		}
	}
};

If an extension results in an error due to invalid or incomplete parameter inputs, the error will generally be ignored. The API will return the data that is possible to extract.

Check the reference to see what endpoints, if any, by which an endpoint can be extended.

JSONP

JSONP is supported by setting the callback parameter to the name of the callback function. For example:

/psapi/v3/image/MY_IMAGE_ID?api_key=MY_API_KEY&fields=image_id&callback=mycallback

Would respond with:

mycallback({...});

Request parameters

`fields`	When requesting data, you need to specify the fields to be returned by providing a `fields` parameter. The value is a comma separated list of the requested fields. Note that if the object id is an available output field (e.g. image_id or gallery_id), it must be included. `*` is supported to retrieve all fields, but its usage is discouraged.
`callback`	If you would like to wrap the response in a callback function (as in a JSONP request), specify the callback parameter in your API call.
`format` (default is “JSON”)	To receive the response in XML, instead of the default JSON, set `format=xml`. Note that the format parameter takes precedence over the callback parameter, which means that any callback function that is set will not be executed if the response format is set to XML.
`extend`	You can choose to extend an endpoint by one or more of its available extension endpoints by passing the `extend` parameter
`api_key`	You may pass your API key in the request URL using the `api_key` parameter. Alternatively, consider sending this in an HTTP header.
`auth_token`	If you request an access token (rather than HTTP cookies) to be returned upon user authentication, you need to set the `auth_token` parameter to this token in order to access member endpoints. Alternatively, consider sending this in an HTTP header.