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:

/api/v2/folder/user/cmac

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:

POST /api/v2/folder/user/example/Cats!folders HTTP/1.1
Host: www.smugmug.com
Accept: application/json
Content-Type: application/json

{"UrlName": "Big-Cats", "Name": "Big Cats", "Privacy": "Public"}

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.