Folders API

Operations on folders. Folders and files share the resource model, the listing endpoint, and the folder tree described in Common conventions; this page covers what applies to folders only.

Base URL and scope

/api/external/v1/folders

Read operations need api:read. Create, delete, rename, and move additionally need api:write.

Create a folder

Requires api:write

POST /api/external/v1/folders

Parameter	Type	Required	Description
fn	string	Yes	Folder name
pfs	long	No	Parent folder seq; required when ss is sent
ss	integer	No	Sharing user seq

Create folder

curl -X POST "https://drive.example.com/api/external/v1/folders" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"pfs": 5, "fn": "Contracts"}'

Create folder response

{
  "result": true,
  "code": 201,
  "message": "Created",
  "data": {
    "resourceSeq": 2056,
    "resourceName": "Contracts"
  }
}

Omitting pfs creates the folder at the drive root. To check a name before creating, use the name-collision endpoint in Common conventions.

Rename a folder

Requires api:write

PATCH /api/external/v1/folders/{resourceSeq}/rename

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the folder to rename
rn	string	Yes	New name
ss	integer	No	Sharing user seq; required for a shared folder
pfs	long	No	Parent folder seq; required for a shared folder

Rename folder

curl -X PATCH "https://drive.example.com/api/external/v1/folders/{resourceSeq}/rename" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"ss": 21, "pfs": 5, "rn": "Signed contracts"}'

Unlike the file rename endpoint, this one has no name-collision policy parameter.

Move a folder

Requires api:write

POST /api/external/v1/folders/{resourceSeq}/move

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the folder to move
ts	integer	No	Target user seq; required for a shared folder
pfs	long	No	Destination folder seq; required for a shared folder
ss	integer	No	Sharing user seq

Move folder

curl -X POST "https://drive.example.com/api/external/v1/folders/{resourceSeq}/move" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"ts": 1, "ss": 21, "pfs": 5}'

Moving a folder moves everything inside it.

Delete a folder

Requires api:write

PATCH /api/external/v1/folders/{resourceSeq}/delete

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the folder to delete

The folder and its contents move to the trash rather than being removed. A failed delete returns RESOURCE_001.

Download a folder

A folder downloads as a ZIP archive in two steps. First issue a token:

GET /api/external/v1/folders/{resourceSeq}/download-token

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the folder to download
ss	integer	No	Sharing user seq

Folder token response

{
  "result": true,
  "code": 200,
  "message": "OK",
  "data": {
    "linkUrl": "/folders/download?dt={token}"
  }
}

Then send the browser to the returned path:

GET /api/external/v1/folders/download?dt={dt}

HTTP 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="archive.zip"

Pinned folders

A user can pin folders for quick access. Pinned folders are per-user and limited to three.

Pinning uses the read scope

Registering and deleting a pinned folder is not treated as a write operation. A key holding only api:read can change the pinned list.

List pinned folders

GET /api/external/v1/pinned-folders

Takes no parameters. Results are ordered by when they were pinned. A pinned entry disappears from the list automatically when the underlying folder is deleted.

Field	Type	Meaning
pinnedFolderSeq	long	Identifier of the pin, used to remove it
resourceSeq	long	The pinned folder
sharedByUserSeq	integer	The user who owns the folder; your own user seq for your own folder
resourceName	string	Folder name
resourceType	enum	Always FOLDER

Pin a folder

POST /api/external/v1/pinned-folders

Parameter	Type	Required	Description
rs	long	Yes	Folder resource seq; passing a file seq fails with RESOURCE_005
ss	integer	No	User seq of the folder owner; required when pinning a folder shared with you

Pin folder

curl -X POST "https://drive.example.com/api/external/v1/pinned-folders" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"rs": 17466, "ss": 43}'

View permission on the folder is checked. A folder that is not shared with you fails with PERMISSION_001, and one you cannot access fails with PERMISSION_002. Pinning the same folder twice fails with PINNED_FOLDER_002, and going past three pins fails with PINNED_FOLDER_003.

Remove a pin

DELETE /api/external/v1/pinned-folders/{pinnedFolderSeq}

Parameter	Type	Required	Description
pinnedFolderSeq	long	Yes	Path parameter - the pin to remove

Removing a pin someone else owns, or one that is already gone, returns PINNED_FOLDER_001. The folder itself is not affected.

Errors

See Errors for the full list of codes these endpoints return.