SmugMug API
Tutorial
API Concepts
Advanced
- Optimizing response sizes
- Expanding related data
- Configuring expansions
- Rate Limits
- Method and Content Overrides
- Performance Metrics
- Multi-get
- Options requests
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:
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
:
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 |