WIwistia
Folders

List Folders

Changed on

Lists folders (previously called projects) belonging to the account. My Library folders are not included.

For tokens scoped to a specific user (all:delegate_to_contact_permissions), results are limited to folders that user can see in their content library: folders shared with them directly, through a contact group, or with the whole account (owners and managers see every folder). Public (unlocked) folders the user has no sharing on remain viewable by link but are not listed.

Requires api token with one of the following permissions

Read all folder and media data

Tokens with the "Act with a team member's permissions" permission (all:delegate_to_contact_permissions scope) can also be used. Requests made with such a token are authorized using the permissions of the contact assigned to the token.

An expiring access token created with the all:delegate_to_contact_permissions scope can also be used. Results are limited to the folders its authorizations name (any permission granted on a folder qualifies it), filtered as they would be for the contact the token was created for.

get/folders

Request

  • Base URL
    https://api.wistia.com/modern
  • URL
    https://api.wistia.com/modern/folders
  • Auth
    HTTP bearer

Query parameters

pageinteger

The page number to retrieve. This cannot be combined with cursor, pagination.

per_pageinteger

The number of medias per page. Use this for both offset pagination and cursor pagination.

enabled0 | 1

If cursor[enabled] is set to 1, the first result set will be fetched with cursor pagination enabled. This values is ignored if cursor[before] or cursor[after] are set.

beforestring

If cursor[before] is set then cursor pagination is enabled and all records before the cursor up to the per_page are returned. This feature is useful for fetching "new records", for example, in a "pull to refersh" feature when showing records in a descending order.

afterstring

If cursor[after] is set then cursor pagination is enabled and all records after the cursor up to the per_page are returned.

If cursor[enabled] is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the per_page. Cursor pagination will also be turned on if cursor[before] or cursor[after] are set. Records returned will have a cursor property set which can be used to fetch more records in the same sort_by ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set.

NOTE: a cursor value is only valid if the sort_by value hasn't changed from the last fetch. For example, you cannot fetch using sort_by id and then pass that cursor value to a sort_by name.

sort_by'name' | 'created' | 'updated' | 'mediaCount' | 'id'

Ordering. When using cursor pagination (see cursor param), only id, updated and created are supported. All other sort_by options require offset pagination.

sort_direction0 | 1

Ordering Sort Direction (0 = desc, 1 = asc; default is 1)

hashed_ids[]string[]

A collection of hashed ids belonging to folders to fetch

Headers

X-Wistia-API-Versionstring required

Response

A list of folders

idinteger required

A unique numeric identifier for the folder within the system.

namestring required

The folder’s display name.

descriptionstring nullable

The folder’s description.

media_countinteger required

The number of different medias that have been uploaded to the folder.

createdstring date-time required

The date that the folder was originally created.

updatedstring date-time required

The date that the folder was last updated.

hashed_idstring required

A private hashed id, uniquely identifying the folder within the system.

publicboolean required

A boolean indicating whether the folder is available for public (anonymous) viewing.

public_idstring nullable required

If the folder is public, this field contains a string representing the ID used for referencing the folder in public URLs.

anonymous_can_uploadboolean
anonymous_can_downloadboolean
kind'library' | 'shared' | 'account' required

Indicates the folder's access scope, relative to the requesting user. One of:

  • library: a library the requester owns. Libraries can still be shared with specific contacts or contact groups; the only restriction is that they cannot be shared with the whole account.
  • shared: a folder the requester has access to via a Contact or ContactGroup sharing — this includes both shared folders and another contact's library that the requester has been granted access to.
  • account: a folder shared with the whole account (everyone in the company can see it).
personal_libraryboolean required

Whether this folder is someone's personal library ("My Library"). Unlike kind, this is a property of the folder itself and does not depend on who is requesting — it is true for a personal library even when that library has been shared with you (where kind would read shared). Use this, not kind, to tell whether a folder is a personal library.

cursorstring nullable

A cursor for stable pagination based on current sort_by order. You can pass this to cursor[before] or cursor[after] as a parameter to fetch the records before or after this record in the same sort order. This is only populated if records were fetched with cursor[enabled], or cursor[before] or cursor[after].

Example response

[
  {
    "id": 22570,
    "name": "My Folder Title",
    "description": "About My Folder",
    "media_count": 2,
    "created": "2010-08-13T18:47:39+00:00",
    "updated": "2010-08-19T21:47:00+00:00",
    "hashed_id": "4d23503f70",
    "public_id": "4bD",
    "kind": "shared"
  }
]

Changes