SmugMug API


Tutorial

API Concepts

Advanced Topics

Live API Browser

Reference

API Concepts

SmugMug API v2 is a "REST" API.

The REST concept has a long history, and not everyone agrees on what it means. For the SmugMug API, REST means:

  • Every object (such as an album, folder, image, or user) has a canonical identifying URI
  • Actions are performed by using the right HTTP method on an object's URI
  • Different HTTP status codes are used to convey different kinds of problems and different kinds of successful outcomes

HTTP Methods

Method Meaning Notes
GET Retrieve an object Never causes any changes
PATCH Edit an object Only the data fields you submit will be changed
POST Create an object Also used for special modifying actions which don't fit into the mold of PATCH
DELETE Delete an object
OPTIONS Learn about how to use an endpoint Read more

Object Identifiers

API v2 uses URIs to identify objects. For example, /api/v2/user/cmac identifies a user. When one object references another, it does so by URI. Thus, when you are using an endpoint that takes a reference to another object as an argument, you must send the API URI for that object as the argument.

For example, suppose you have an image /api/v2/image/53PwQMN-0 and an album /api/v2/node/LTQMF. To set that image to be that album's highlight image, you make a PATCH request to the album URI and pass the image URI as an argument:

PATCH /api/v2/node/LTQMF HTTP/1.1
Host: api.smugmug.com
Accept: application/json



{"HighlightImageUri": "/api/v2/image/53PwQMN-0"}

Creating Objects

Creating an object is done by making a POST request to the endpoint which returns the set of objects which are siblings of the one you want to create. That sounds complicated, but it's simple in practice. For example, let's say you want to create a new album under the folder /api/v2/node/tqzx6. The new album would be the sibling of any nodes returned by /api/v2/node/tqzx6!children, so that's the endpoint where you should POST:

POST /api/v2/node/tqzx6!children HTTP/1.1
Host: api.smugmug.com
Accept: application/json



{"Type": "Album", "Name": "My Smug Album", "UrlName": "My-Smug-Album", "Privacy": "Public"}

Status Codes

Error? Code Name Meaning
No 200 OK Success
No 201 Created Successfully created a new object
No 202 Accepted Successfully started an asynchronous task
No 301 Moved Permanently The object has a new URI and the change is permanent
No 302 Moved Temporarily The object has a new URI but the change is temporary
Yes 400 Bad Request Your request contained invalid parameters or was otherwise invalid
Yes 401 Unauthorized Your request requires permissions you do not have
Yes 402 Payment Required Your account's paid subscription has expired and you must renew to complete this request
Yes 403 Forbidden Your request is not allowed (for some reason other than a lack of permissions)
Yes 404 Not Found The object you requested does not exist, or you do not have the necessary permissions to be told that it exists
Yes 405 Method Not Allowed The HTTP method is not valid at this endpoint
Yes 406 Bad Accept The Accept header in your request is not valid
Yes 409 Conflict Your request failed due to a naming conflict (you tried to move or rename something but the desired name is in use by another object)
Yes 429 Too Many Requests You have made too many requests in too short a period of time
Yes 500 Internal Server Error You have found a bug in the SmugMug API. Please contact us.
Yes 503 Service Unavailable Our servers are overloaded and cannot handle your request