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
Folder
This reference only covers the most important details. Use the Live API Browser to see everything.
Live example: /api/v2/folder/user/cmac/SmugMug
You should only use this endpoint if you need to support older accounts that have not migrated to New SmugMug. If you only need New SmugMug support, use the Node endpoint instead.
A folder can contain albums, pages, and other folders. The API URI for a folder contains the full path to that folder.
For example, this is the /SmugMug/Heroes folder of the user cmac:
/api/v2/folder/user/cmac/SmugMug/Heroes
And this is cmac's root folder:
Important fields
| Owner-only? | Owner-writeable? | Name | Description |
|---|---|---|---|
| DateAdded | Time when this folder was created (which never changes) | ||
| DateModified | The latest LastUpdated value of any album under this folder (at any depth) | ||
| X | Description | The human-readable description | |
| X | Name | The human-readable title | |
| X | PasswordHint | The hint for the folder-viewing password | |
| X | X | Privacy | Public, Unlisted, or Private |
| X | X | SmugSearchable | Allow this folder to appear in SmugMug search results? |
| X | UrlName | The user-configurable part of the WebUri | |
| WebUri | The folder's page on the SmugMug website | ||
| X | X | WorldSearchable | Allow this folder to appear in external search results? |
The SmugSearchable and WorldSearchable fields have more possible values at the root folder than at other folders.
Important links
| Name | Description |
|---|---|
| FolderAlbums | The albums in this folder |
| FolderByID | A reference to this folder which will never change, even if this folder is renamed |
| FolderPages | The pages in this folder |
| Folders | The child folders of this folder |
| HighlightImage | An image which can be used as a representative of the entire folder |
| ParentFolder | The parent folder |
| ParentFolders | This folder and all its ancestors |
| UnlockFolder | Unlock this folder (only present if locked) |
| User | The user who owns this folder |
Creating a folder
To create a folder, you must POST to the Folders endpoint of the folder where you want the new folder to be created:
The response, if successful, will be the Folder object that was created. Note that there is a limit to how deep the folder hierarchy can be. The root of your account can contain folder trees that go five folders deep. Albums do not count toward this depth limit.
Legacy (non-migrated) user accounts
User accounts which have not migrated to New SmugMug do not have folders. Instead, they have a two-level hierarchy of Categories and Subcategories, and albums are not allowed at the root level. In the API, we present Categories and Subcategories as if they were folders, which means that your application should not have to worry about the distinction.
If your application supports creating new albums or folders, be aware that a folder may not have Folders or FolderAlbums links, which indicates that folders or albums cannot be created at that location.